From 39952ceb029281ee966e06c6571f2e14ccce611b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sascha=20K=C3=B6nig?= Date: Sat, 14 Nov 2026 10:23:23 +0100 Subject: [PATCH] docs: propose client labels for per-client content selection Add docs/proposals/client-labels.md: an optional agent-lib.labels.json in the work repository, a "labels" field in the client config (admin-pinned), filtering before planning with deselected items following the upstream-deletion rules, plus status and validate support. Tracked as beads issue agent_lib-fh4. --- .beads/issues.jsonl | 1 + docs/proposals/client-labels.md | 159 ++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+) create mode 100644 docs/proposals/client-labels.md diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 33935fa..0ee87d8 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,3 +1,4 @@ +{"_type":"issue","id":"agent_lib-fh4","title":"Client labels: deliver items only to clients with a matching label","description":"Design: docs/proposals/client-labels.md (proposed 14.11.2026).\n\nOptional repo file agent-lib.labels.json ({version:1, labels:{label:[item names]}}); unlabeled items go to everyone. Client config gains 'labels'; absent = no filtering, [] = only unlabeled. Admin default config's labels win over user/env config. Invalid labels file aborts sync before any disk change. Filter before planning (internal/client/sync.go loop over inv.Deployable()); deselected items reuse the upstream-deleted path with reason 'not selected for this client's labels'. status --json reports labels/source/filtered; validate checks the file (names resolve incl. MCP). Revises README non-goal 'client-side selection or profiles'.\n\nConsumer: az-agent-defaults (agent-lib.labels.json already prepared) + az-fleet agent_lib role.","acceptance_criteria":"Tests per proposal section 'Tests' green; README documents file format, config field, admin precedence; release tagged; second sync with labels is a byte-level no-op.","status":"open","priority":2,"issue_type":"feature","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-14T09:11:57Z","created_by":"m3ta-chiron","updated_at":"2026-11-14T09:11:57Z","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"agent-lib-u5t","title":"vendor rename: Vendor-Skills nachträglich umbenennen","description":"Kuratoren sollen vendored Items nachträglich (nicht nur bei vendor add) benutzerfreundlich umbenennen können. Neuer Befehl vendor rename \u003csource\u003e up=new / --reset; umbenannte Skills bekommen den name: im SKILL.md-Frontmatter angepasst (OpenCode verlangt name == Ordnername).","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-05T07:43:31Z","created_by":"m3ta-chiron","updated_at":"2026-11-05T07:45:14Z","started_at":"2026-11-05T07:43:50Z","closed_at":"2026-11-05T07:45:14Z","close_reason":"vendor rename implemented with SKILL.md name rewrite, tests + README","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"agent-lib-4wx.11","title":"Deliver end-to-end documentation and release gate","description":"Finish the MVP by documenting the full workflow and proving it through an offline end-to-end acceptance path. The slice should provide README content, quickstart, CLI reference, Home Manager examples, security/trust notes, troubleshooting, and a release gate that demonstrates init, Source add, inspect, snippet, Home Manager eval/render, target Manifests, and a green offline check.","acceptance_criteria":"- Documentation covers installation, quickstart, CLI reference, Home Manager configuration, Lockfile behavior, discovery conventions, security/trust model, troubleshooting, MVP scope, and non-goals\n- An offline end-to-end fixture workflow demonstrates initialization, Source discovery, selection, Pi and Opencode Rendered output, target Manifests, and no unmanaged overwrites\n- nix flake check is green without external network access and verifies the MVP acceptance criteria","notes":"E2E fixture check green. All steps verified: init creates lockfile, discover finds all items, lockfile has rev/narHash/HM-compatible schema, inspect/snippet/validate commands work, managed-file protection present. nix flake check passes.","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:50:02Z","created_by":"m3tam3re","updated_at":"2026-05-28T08:13:15Z","started_at":"2026-05-28T07:46:50Z","closed_at":"2026-05-28T08:13:15Z","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:50:01Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.1","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.10","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.2","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.4","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.6","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.9","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":10,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"agent-lib-4wx.10","title":"Complete CLI operational workflows and snippets","description":"Complete the day-to-day CLI workflow around existing Sources, Profiles, and Targets. The slice should make update/review/switch workflows practical with added/removed Item reports, offline and fetch validation modes, minimal and full Nix snippets, JSON output, non-interactive defaults, and an optional interactive entry point without automatic Nix edits.","acceptance_criteria":"- source update and source update --all report added and removed Items without changing Home Manager selection\n- validate runs offline by default, validate --fetch performs explicit reachability checks, and list/inspect/validate support stable JSON output\n- snippet emits both minimal Profile include snippets and full example configuration, while the CLI remains non-interactive by default and never edits Nix files","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:57Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:46:28Z","started_at":"2026-05-28T07:39:36Z","closed_at":"2026-05-28T07:46:28Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:56Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":4,"dependent_count":1,"comment_count":0} diff --git a/docs/proposals/client-labels.md b/docs/proposals/client-labels.md new file mode 100644 index 0000000..8df2510 --- /dev/null +++ b/docs/proposals/client-labels.md @@ -0,0 +1,159 @@ +# Proposal: client labels — deliver content to a subset of clients + +Status: proposed (14.11.2026) + +## Problem + +A work repository serves every client the same content. Organisations with +teams want *relevant* content per team: finance needs finance skills, sales +needs sales agents, and nobody benefits from all of it. A long skill list +also hurts routing quality of small models. + +Today the only way to split is one repository or one branch per team. Both +force shared content to be maintained N times (merges, drift) and cannot +serve a client that belongs to two teams — a client pulls exactly one ref. + +## Decision in one sentence + +Content items may carry **labels** in the work repository; clients carry +**labels** in their config; `sync` delivers an item when it is unlabeled or +shares at least one label with the client. + +agent-lib stays generic: it knows "label" and "item", never "department", +"role" or any organisation's vocabulary. What a label means and who gets it +is decided outside agent-lib (curator: which item has which label; fleet +tooling: which client has which label). + +This revises the v2 non-goal "client-side selection or profiles": labels are +a selection, but no profiles — there is no per-label content, overrides or +inheritance, only a filter over the one shared inventory. + +## Repository side: `agent-lib.labels.json` + +Optional file in the work repository root, next to `agent-lib.lock.json`. +JSON keeps the binary free of a YAML dependency (frontmatter is hand-parsed +today) and matches the lockfile and client config. + +```json +{ + "version": 1, + "labels": { + "sales": ["crm-agent", "quote-writer"], + "finance": ["officecli-financial-model", "invoice-check"], + "dev": ["grilling", "to-spec"] + } +} +``` + +Rules: + +- **Unlabeled = everyone.** Only items that should be restricted appear in + the file. Adding an item to the repository without touching the file + delivers it to all clients — same as today. +- An item may appear under several labels (OR). +- Entries are **deployed item names** (after vendor renames), matched across + types: `foo` covers the skill `foo` and the command `foo` alike. Type- + qualified entries are not needed until a real collision appears. +- Label form `^[a-z0-9][a-z0-9-]*$`; lists must be non-empty. +- Names may also refer to MCP fragments. The binary never deploys MCP, but + fleet tooling can read the same file to scope MCP servers — one source of + truth for "who gets what". +- Unknown top-level keys are an error (typo protection); `version` is + required. + +## Client side: `labels` in the client config + +```json +{ + "repo_url": "https://git.example.com/company/agent-content.git", + "ref": "main", + "labels": ["sales", "leadership"] +} +``` + +| `labels` | Effect | +|---|---| +| field absent | **no filtering** — every item, as today (backward compatible) | +| `[]` | only unlabeled items | +| `["a","b"]` | unlabeled items plus items labeled `a` or `b` | + +Client labels that no item uses are fine (no warning): a client may be +labeled ahead of content. + +### Admin-pinned labels + +Today the first config found wins as a whole, and the user-level config +precedes the admin default. For labels that would let a user widen their +own selection. Rule: + +> If the admin default config exists and contains `labels`, that value +> applies — whichever config supplied `repo_url`. User-level and env +> configs cannot set or override `labels` while an admin value exists. +> Without an admin value, `labels` from the chosen config applies +> (personal machines keep full control). + +`--labels a,b` as a flag is deliberately not offered for sync; for testing +use `--config` with a file that has no admin counterpart, i.e. on a machine +without an admin default. + +Labels are a **relevance filter, not access control**: the whole repository +revision is still fetched into the local cache. Confidential content needs +a separately authenticated repository. + +## Sync behaviour + +1. Build the inventory as today. +2. Read `agent-lib.labels.json` from the **same revision**. + - Absent → no filtering. + - Invalid (parse error, bad label form, empty list, unknown key, + unknown version) → **sync aborts before any change** with a clear + error. Never fall back to "deliver everything". + - A name that matches no item → warning in sync log/status, not fatal + (the curator-side `validate` is the hard gate). +3. Drop items whose labels do not intersect the client labels before + hashing/planning (`internal/client/sync.go`, loop over + `inv.Deployable()`). +4. Planning is unchanged. A previously deployed item that is no longer + selected is handled exactly like an upstream deletion: unmodified → + remove; locally modified → skip + warn (`--force` removes). The plan + reason and toast text say **"not selected for this client's labels"** + instead of "upstream deleted" so users understand why. + +## Status + +`status --json` gains: + +```json +"labels": { "client": ["sales"], "source": "admin", "filtered": 12 } +``` + +`source` is `admin` | `user` | `env` | `flag` | `none`. Human output +prints one line: `labels: sales (admin) — 12 items not selected`. + +## Curator side + +`agent-lib validate` checks `agent-lib.labels.json` when present: +schema/version, label form, non-empty lists, every name resolves to an +inventory item (own or external, any type including MCP). Errors are +fatal, so a broken file never reaches clients through CI. + +No new curator command is required; the file is edited by hand. A later +`agent-lib labels list` (item → labels table) is a nice-to-have. + +## Tests + +- planner/sync: absent field, `[]`, single/multi label, item under two + labels, label removed from client → remove unmodified / keep modified, + `--force`. +- config: admin labels beat user labels; user labels apply without admin + value; absent everywhere → no filtering. +- labels file: absent, invalid variants (abort, no disk change), unknown + name (warning). +- validate: each error class. +- e2e: second run is a byte-level no-op with labels active. + +## Rollout + +Additive and backward compatible: old clients ignore the file, new +clients without `labels` ignore the file. Fleet tooling adds the field +after pinning the release that understands it.