@event4u/agent-config 8.12.0 → 9.0.0

package/dist/agent-src/commands/project.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: project
 disable-model-invocation: true
+argument-hint: "[analyze|health]"
 pack: engineering-base
 intent: "Project dispatcher — full analysis or quick health check"
 routes_to: [project-analyze, project-health]
@@ -37,7 +38,7 @@ Top-level orchestrator for the `/project` family — project-wide inspection.
 | `/project health` | `commands/project/health.md` | Quick health check — status of docs, modules, contexts, roadmaps; creates nothing |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/dist/agent-src/commands/refine-ticket.md

@@ -9,6 +9,7 @@ tier: 1
 visibility: advanced
 skills: [refine-ticket]
 description: Refine a Jira/Linear ticket before planning — rewritten ticket + Top-5 risks + persona voices, orchestrates validate-feature-fit and threat-modeling, ends with a close-prompt
+argument-hint: "[ticket-key | url | text] [--personas=<list>] [--user-type=<id>] [--fresh-eyes]"
 suggestion:
   eligible: true
   trigger_description: "refine PROJ-123, tighten the acceptance criteria, is this ticket clear"
@@ -68,6 +69,12 @@ application, synthesis, and close-prompt.
 - `--personas=<list>` — comma-separated override of the Core-6 default
   (e.g. `--personas=developer,senior-engineer,critical-challenger`)
 - `--personas=+qa` — add the QA specialist to the Core-6
+- `--user-type=<id>` — load one user-type from `user-types/<id>.md` and
+  add an end-user simulation lens to the persona stack (e.g.
+  `--user-type=galabau-field-crew`). Composes orthogonally with
+  `--personas=`; persona = methodology lens, user-type = end-user lens.
+  v1 is CLI-only (no skill-level default). Contract:
+  [`docs/contracts/user-type-schema.md`](../docs/contracts/user-type-schema.md).
 - `--fresh-eyes` — reweight toward first-time-reader confusion signals
   (critical-challenger voice gets more lines; less assumed context)
 

package/dist/agent-src/commands/research/deep.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: research
 sub: deep
 description: "Read `outline.yaml`, research each item in batches, write per-item JSON validated against the project-local research-schema. No Python runtime, no `~/.claude/` paths."
+argument-hint: "[--batch-confirm=each|once|auto]"
 skills: [deep-reading-analyst]
 suggestion:
   eligible: true

package/dist/agent-src/commands/research.md

@@ -2,6 +2,7 @@
 model_tier: high
 name: research
 disable-model-invocation: true
+argument-hint: "[<topic>|deep|report] [args]"
 pack: product-discovery
 tier: 2
 visibility: internal

package/dist/agent-src/commands/review/routing.md

@@ -8,6 +8,7 @@ sub: routing
 cluster: review
 skills: [review-routing, reviewer-awareness]
 description: Compute reviewer roles and matched historical bug patterns for the current diff, using project-local ownership-map.yml and historical-bug-patterns.yml
+argument-hint: "[base-ref head-ref]"
 suggestion:
   eligible: true
   trigger_description: "who should review this, suggest reviewers for this PR"

package/dist/agent-src/commands/review.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: review
 disable-model-invocation: true
+argument-hint: "[changes|routing]"
 pack: engineering-base
 intent: "Review dispatcher — multi-judge self-review of the current diff, or reviewer routing"
 routes_to: [review-changes, review-routing]
@@ -38,7 +39,7 @@ reviewer selection.
 | `/review routing` | `commands/review/routing.md` | Compute reviewer roles + matched historical bug patterns for the current diff (ownership-map.yml, historical-bug-patterns.yml) |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/dist/agent-src/commands/roadmap/ai-council.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: ai-council
 skills: [ai-council, agent-docs-writing, roadmap-management]
 description: Challenge a roadmap with the AI council (deep tier) and refactor from convergence findings. Wraps `/council default` pinned to `--input-mode roadmap --depth deep`; patches surface as numbered options.
+argument-hint: "[roadmap-name | path]"
 council_depth: deep
 suggestion:
   eligible: true

package/dist/agent-src/commands/roadmap/materialize.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: materialize
 skills: [emit-tickets]
 description: Materialise a roadmap into a self-contained, importable ticket bundle under agents/tickets/
+argument-hint: "[roadmap-path]"
 suggestion:
   eligible: true
   trigger_description: "turn this roadmap into tickets, materialise the roadmap, mach Tickets aus der Roadmap"

package/dist/agent-src/commands/roadmap/process-full.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: process-full
 skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process every open step across every phase of a roadmap until the file is fully closed. Largest execution scope of the /roadmap cluster — runs continuously across phase boundaries.
+argument-hint: "[roadmap]"
 suggestion:
   eligible: true
   trigger_description: "process the whole roadmap, finish the roadmap, komplette roadmap abarbeiten"

package/dist/agent-src/commands/roadmap/process-phase.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: process-phase
 skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process every open step in the next or current phase of a roadmap, then stop. Default execution scope of the /roadmap cluster.
+argument-hint: "[roadmap]"
 suggestion:
   eligible: true
   trigger_description: "process the next phase, finish this phase autonomously, eine phase abarbeiten"

package/dist/agent-src/commands/roadmap/process-step.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: process-step
 skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /roadmap cluster — one step in, one step out.
+argument-hint: "[roadmap]"
 suggestion:
   eligible: true
   trigger_description: "process the next step, do the next roadmap step, einen schritt abarbeiten"

package/dist/agent-src/commands/roadmap.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: roadmap
 disable-model-invocation: true
+argument-hint: "[create|ai-council|process-step|process-phase|process-full] [args]"
 pack: product-basic
 intent: "Roadmap dispatcher — create, process-step, process-phase, process-full, ai-council"
 routes_to: [roadmap-create, roadmap-process-step, roadmap-process-phase, roadmap-process-full]

package/dist/agent-src/commands/security-audit-config.md

@@ -6,6 +6,7 @@ tier: 2
 visibility: internal
 skills: [judge-security-auditor, threat-modeling, security-audit]
 description: Audit an assembled agent config (CLAUDE.md, .cursor/rules, settings, MCP, hooks, skills) for prompt-injection / supply-chain risk — A–F score per category, mapped to OWASP Agentic Top 10
+argument-hint: "[repo-root]"
 council_depth: deep
 suggestion:
   eligible: true
@@ -35,7 +36,7 @@ suite's own `lint_agent_security` self-audit gate.
 
 (omit `--root` to audit the current repo). The script reuses the Phase-1
 detection library under the false-positive containment convention
-([`security-lint-containment`](../../../docs/guidelines/agent-infra/security-lint-containment.md)),
+([`security-lint-containment`](../../docs/guidelines/agent-infra/security-lint-containment.md)),
 so doc/example files do not tank the score. It scans instruction files
 (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.github/copilot-instructions.md`,
 `.clinerules`, `.windsurfrules`), MCP configs (`.mcp.json`, `.cursor/mcp.json`,

package/dist/agent-src/commands/skill/preview.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: skill
 sub: preview
 description: Non-destructive preview of a skill — its declared steps, execution type, allowed tools, and file/command targets — before you run it. Read-only, no execution.
+argument-hint: "<skill-name> [--technical]"
 skills: [file-editor]
 suggestion:
   eligible: true

package/dist/agent-src/commands/skill.md

@@ -5,6 +5,7 @@ pack: meta
 tier: 2
 visibility: internal
 description: Single-skill orchestrator — routes to preview. Non-destructive "what will this skill do?" before you run it.
+argument-hint: "[preview] <skill-name>"
 cluster: skill
 type: orchestrator
 suggestion:

package/dist/agent-src/commands/skills/discover.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: skills
 sub: discover
 description: Recommend skills for a role — ranked by four explained classes (most-useful-for-role, related-to-current-task, recently-adopted, popular-in-role). Local-only; every result carries a why.
+argument-hint: "[role]"
 skills: [file-editor]
 suggestion:
   eligible: true

package/dist/agent-src/commands/skills.md

@@ -5,6 +5,7 @@ pack: meta
 tier: 2
 visibility: internal
 description: Skill discovery orchestrator — routes to discover. Local, explained skill recommendations over the catalog + role shortlists + optional local analytics.
+argument-hint: "[discover] [role]"
 cluster: skills
 type: orchestrator
 suggestion:

package/dist/agent-src/commands/sync/agent-settings.md

@@ -8,6 +8,7 @@ sub: agent-settings
 cluster: sync
 skills: [sync-agent-settings]
 description: Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing
+argument-hint: "[--path <file>] [--profile minimal|balanced|full] [--check]"
 suggestion:
   eligible: false
   rationale: "Settings sync — must be deliberate."

package/dist/agent-src/commands/sync.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: sync
 disable-model-invocation: true
+argument-hint: "[agent-settings|gitignore|gitignore-fix]"
 pack: meta
 intent: "Sync dispatcher — agent settings or the managed .gitignore block"
 routes_to: [sync-agent-settings, sync-gitignore, sync-gitignore-fix]
@@ -34,7 +35,7 @@ managed files in step with the package templates.
 | `/sync gitignore-fix` | `commands/sync/gitignore/fix.md` | Scrub legacy pre-`/agents/` patterns anywhere in the `.gitignore`, then re-sync the canonical entries |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/dist/agent-src/commands/team/adversarial.md

@@ -0,0 +1,97 @@
+---
+model_tier: inherit
+name: team-adversarial
+disable-model-invocation: true
+argument-hint: "<focus>"
+pack: meta
+tier: 2
+visibility: internal
+skills: [adversarial-review]
+description: Thin wrapper — adversarial cross-model review on a named focus via the official plugin (/codex:adversarial-review). Escalation rung above the single-model adversarial-review skill.
+cluster: team
+sub: adversarial
+suggestion:
+  eligible: true
+  trigger_description: "adversarial cross-model review, attack this change with a second model, stress-test the diff with GPT, hostile review by another model"
+  trigger_context: "ai_team.enabled is true AND single-model self-review found nothing or the stakes are high — escalate the Attack-Defend-Revise frame to a second strong model"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /team adversarial
+
+## Instructions
+
+Thin wrapper: adversarial cross-model review on a named focus. Same
+Attack-Defend-Revise frame as the `adversarial-review` skill, different
+attacker — a second strong model with repo access instead of the host model
+critiquing itself. Use it as the **escalation rung**: single-model
+self-review found nothing, or the stakes are high.
+
+### 1. Gate — `ai_team.enabled`
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing or `false` →
+print the enable pointer from `/team` (master) § "Default-off gate" and
+**STOP**.
+
+### 2. Gate — plugin presence (fail closed)
+
+On a Claude Code host, verify the official plugin is installed. Absent →
+print the fail-closed block from `/team` (master) § "Fail-closed contract"
+(`agent-config doctor --check team`) and **STOP**. Never reimplement the
+adversarial review inline; never silently no-op.
+
+On a non-Claude-Code host: state that the cross-model adversarial path
+currently requires the Claude Code plugin, offer the single-model
+`adversarial-review` skill as the available rung, and stop.
+
+### 3. Resolve the focus
+
+The user invoked `/team adversarial <focus>` — e.g. `security`,
+`error handling`, `the tenant-scope change in UserService`. If no focus was
+supplied, ask (one question per turn, per `ask-when-uncertain`):
+
+> What should the adversarial review attack?
+>
+> 1. A named surface (e.g. security, error handling, concurrency)
+> 2. A specific file / change (name it)
+> 3. Cancel
+
+### 4. Delegate
+
+Invoke the plugin with the focus passed through unchanged:
+
+- `/team adversarial <focus>` → `/codex:adversarial-review <focus>`
+
+### 5. Return the findings verbatim
+
+Render the plugin's findings unchanged — do not soften, dedupe, or re-rank.
+The call counts into the `cli_call_budget.max_calls_per_day.openai` quota;
+on quota exhaustion surface the transport's refusal, do not retry.
+
+## Output format
+
+- The plugin's adversarial findings, verbatim.
+- Gate failures print exactly one block (enable pointer or fail-closed
+  block) and stop.
+
+## Do NOT
+
+- Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
+- Do NOT reimplement the adversarial pass inline when the plugin is absent —
+  fail closed with the doctor pointer.
+- Do NOT skip the free first rung reflexively — the single-model
+  `adversarial-review` skill costs nothing; escalate when it finds nothing
+  or the stakes justify a second model.
+- Do NOT edit files, commit, push, or open a PR — read-only.
+- Do NOT claim a defect-finding lift; the benchmark verdict is pending (see
+  `/team` master § "No-claims note").
+
+## See also
+
+- `adversarial-review` skill — the single-model Attack-Defend-Revise frame
+  this escalates.
+- `/team review` — the non-adversarial cross-model review.
+- `/team` — master orchestrator: gates, boundary table vs `/council`.

package/dist/agent-src/commands/team/delegate.md

@@ -0,0 +1,110 @@
+---
+model_tier: inherit
+name: team-delegate
+disable-model-invocation: true
+argument-hint: "<task>"
+pack: meta
+tier: 2
+visibility: internal
+description: Thin wrapper — hand a task to the second model as a native worker via the official plugin (/codex:rescue). The only write-access wrapper; double-gated behind ai_team.allow_delegate.
+cluster: team
+sub: delegate
+suggestion:
+  eligible: false
+  rationale: "Only write-access wrapper in the family; delegation of write access must be explicitly typed by the user, never suggested."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /team delegate
+
+## Instructions
+
+Thin wrapper: hand a task to the second model as a **native worker** in the
+repo. On Claude Code hosts it delegates to the official plugin's
+`/codex:rescue`. This is the **only wrapper that delegates write access**,
+so it carries a second opt-in on top of the family gate.
+
+### 1. Gate — `ai_team.enabled`
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing or `false` →
+print the enable pointer from `/team` (master) § "Default-off gate" and
+**STOP**.
+
+### 2. Gate — `ai_team.allow_delegate` (second opt-in)
+
+Read `ai_team.allow_delegate`. Missing or `false` (the shipped default) →
+refuse with the enable pointer and **STOP**:
+
+> `/team delegate` is disabled (`ai_team.allow_delegate: false`, the
+> default). It is the only team-mode wrapper that hands **write access** to
+> the second model, so it needs its own opt-in:
+>
+> ```yaml
+> ai_team:
+>   enabled: true
+>   allow_delegate: true
+> ```
+>
+> Key reference: `docs/contracts/ai-team-config.md`.
+
+### 3. Gate — plugin presence (fail closed)
+
+On a Claude Code host, verify the official plugin is installed. Absent →
+print the fail-closed block from `/team` (master) § "Fail-closed contract"
+(`agent-config doctor --check team`) and **STOP**. Never reimplement the
+worker inline; never silently no-op.
+
+On a non-Claude-Code host: there is **no** delegate fallback — the
+worker-via-bundle path is deferred by a recorded internal null. State that
+delegation requires the Claude Code plugin and stop.
+
+### 4. Resolve the task
+
+The user invoked `/team delegate <task>`. If the task text is missing, ask
+(one question per turn, per `ask-when-uncertain`) for a one-line task
+description; do not invent scope.
+
+### 5. Delegate
+
+Invoke the plugin with the task passed through unchanged:
+
+- `/team delegate <task>` → `/codex:rescue <task>`
+
+The Codex worker runs natively in the working tree under the user's
+subscription. The call counts into the
+`cli_call_budget.max_calls_per_day.openai` quota; on exhaustion surface the
+transport's refusal, do not retry.
+
+### 6. Return the result verbatim
+
+Render the plugin's result unchanged. Any edits the worker made are in the
+working tree for the user to review — this wrapper never commits, pushes, or
+opens a PR on top of them.
+
+## Output format
+
+- The plugin's rescue/delegation result, verbatim.
+- Gate failures print exactly one block (enable pointer, allow_delegate
+  refusal, or fail-closed block) and stop.
+
+## Do NOT
+
+- Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
+- Do NOT run when `ai_team.allow_delegate` is false — refusal block, stop.
+  Never treat `enabled: true` alone as delegate authorization.
+- Do NOT reimplement the worker inline when the plugin is absent — fail
+  closed with the doctor pointer.
+- Do NOT commit, push, or open a PR over the worker's edits — review is the
+  user's call.
+- Do NOT claim a productivity or quality lift; the benchmark verdict is
+  pending (see `/team` master § "No-claims note").
+
+## See also
+
+- `/team` — master orchestrator: gates, boundary table vs `/council`.
+- `/team review` — the read-only default lens; prefer it unless the user
+  explicitly wants the second model to do the work.
+- `docs/contracts/ai-team-config.md` — `ai_team.allow_delegate` semantics.

package/dist/agent-src/commands/team/review.md

@@ -0,0 +1,85 @@
+---
+model_tier: inherit
+name: team-review
+disable-model-invocation: true
+argument-hint: "[--background]"
+pack: meta
+tier: 2
+visibility: internal
+description: Thin wrapper — cross-model review of the current diff via the official plugin (/codex:review). Gated on ai_team.enabled; fails closed when the plugin is absent.
+cluster: team
+sub: review
+suggestion:
+  eligible: true
+  trigger_description: "team review, second model review, cross-model review of my changes, GPT drüberschauen lassen, review the diff with another strong model"
+  trigger_context: "ai_team.enabled is true AND there is an uncommitted / staged diff the user wants a second strong model to review with repo access"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /team review
+
+## Instructions
+
+Thin wrapper: cross-model review of the current change. On Claude Code hosts
+it delegates verbatim to the official plugin's `/codex:review` — this wrapper
+owns only the governance gates around it.
+
+### 1. Gate — `ai_team.enabled`
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing or `false` →
+print the enable pointer from `/team` (master) § "Default-off gate" and
+**STOP**. No plugin probe, no partial run.
+
+### 2. Gate — plugin presence (fail closed)
+
+On a Claude Code host, verify the official plugin is installed (its
+`/codex:*` commands are available). Absent → print the fail-closed block
+from `/team` (master) § "Fail-closed contract" — the remediation path is
+`agent-config doctor --check team` — and **STOP**. Never reimplement the
+review inline; never silently no-op.
+
+On a non-Claude-Code host: the repo-diff-bundle fallback is a later phase.
+State that team review currently requires the Claude Code plugin, point to
+`agent-config doctor --check team`, and stop.
+
+### 3. Delegate
+
+Invoke the plugin:
+
+- `/team review` → `/codex:review`
+- `/team review --background` → `/codex:review --background`
+
+Pass the flag through unchanged. Scope resolution (what counts as "the
+diff") is the plugin's job — do not pre-compute or filter the diff here.
+
+### 4. Return the review verbatim
+
+Render the plugin's review output unchanged. Do not summarize, re-rank, or
+soften findings. The call counts into the
+`cli_call_budget.max_calls_per_day.openai` quota (one subscription, one
+counter); if the quota is exhausted the transport refuses — surface that
+refusal, do not retry.
+
+## Output format
+
+- The plugin's review, verbatim.
+- Nothing else on success; gate failures print exactly one block (enable
+  pointer or fail-closed block) and stop.
+
+## Do NOT
+
+- Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
+- Do NOT reimplement the review inline when the plugin is absent — fail
+  closed with the doctor pointer.
+- Do NOT edit files, commit, push, or open a PR — this wrapper is read-only.
+- Do NOT claim a review-quality lift; the benchmark verdict is pending (see
+  `/team` master § "No-claims note").
+
+## See also
+
+- `/team` — master orchestrator: gates, boundary table vs `/council`.
+- `/team adversarial` — focused adversarial variant.
+- `adversarial-review` skill — single-model self-review, the free first rung.

package/dist/agent-src/commands/team/status.md

@@ -0,0 +1,123 @@
+---
+model_tier: inherit
+name: team-status
+disable-model-invocation: true
+pack: meta
+tier: 2
+visibility: internal
+description: Thin wrapper — plugin job status via /codex:status plus a quota block (shared openai counter vs team + council ceilings). Gated on ai_team.enabled; fails closed without the plugin.
+cluster: team
+sub: status
+suggestion:
+  eligible: false
+  rationale: "Read-only state query; users invoke it explicitly when they want job or quota status — suggesting it adds noise."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /team status
+
+## Instructions
+
+Thin wrapper: team-mode status. On Claude Code hosts it delegates to the
+official plugin's `/codex:status` and appends **our** quota block —
+the one piece of state the plugin does not know about.
+
+### 1. Gate — `ai_team.enabled`
+
+Read `ai_team.enabled` from `.agent-settings.yml`. Missing or `false` →
+print the enable pointer from `/team` (master) § "Default-off gate" and
+**STOP**.
+
+### 2. Gate — plugin presence (fail closed)
+
+On a Claude Code host, verify the official plugin is installed. Absent →
+print the fail-closed block from `/team` (master) § "Fail-closed contract"
+(`agent-config doctor --check team`) and **STOP** — never a silent no-op.
+
+On a non-Claude-Code host: state that plugin job status requires the Claude
+Code plugin, then still print the quota block (Step 4) — the quota counter
+is ours and host-independent.
+
+### 3. Delegate
+
+Invoke the plugin:
+
+- `/team status` → `/codex:status`
+
+Render its job/status output verbatim.
+
+### 4. Append the quota block — two ceilings, one counter
+
+Team mode and the council share **one** daily counter but enforce **two
+independent ceilings** against it. The status output must show all three
+live numbers and say which path — if any — is currently blocked:
+
+1. **Counter** — today's openai CLI-call count from the shared counter
+   state at `~/.event4u/agent-config/cli-calls.json` (daily UTC reset —
+   the same file the council's CLI transport maintains). `0` when the
+   file or today's entry is absent.
+2. **Team ceiling** — `ai_team.max_calls_per_day` from
+   `.agent-settings.yml` (`unset` when absent).
+3. **Council ceiling** — `cli_call_budget.max_calls_per_day.openai` from
+   the council config (`unset` when absent).
+
+Render:
+
+```
+Quota: <N> openai CLI calls today (UTC) — one shared counter
+  team ceiling (ai_team.max_calls_per_day):                <T or "unset"> → <OPEN | BLOCKED>
+  council ceiling (cli_call_budget.max_calls_per_day.openai): <C or "unset"> → <OPEN | BLOCKED>
+```
+
+- A path is `BLOCKED` when the counter has reached its ceiling
+  (`N >= ceiling`); an `unset` ceiling is `OPEN`.
+- The two paths block **independently** — always name WHICH path is
+  blocked, never a bare "quota exhausted".
+- One counter, one subscription — never introduce a parallel team-only
+  counting file.
+
+**Worked example.** Council ceiling 100, team ceiling 50, counter at 45:
+both paths are open. Five team calls later the shared counter reads 50 —
+team calls are now `BLOCKED` (50 >= 50) while council CLI calls continue
+until the counter reaches 100. Whichever path fires a call, the same
+counter moves; each surface only enforces its own ceiling against that
+shared count.
+
+### 5. Review-gate ledger lines (when present)
+
+When the council events ledger contains review-gate lines of the form
+`team.gate: BLOCK n/N`, render them verbatim after the quota block — they
+record how often the plugin's Stop-hook Review Gate blocked, out of N gate
+evaluations. Absent lines are not an error: print nothing (the review-gate
+envelope is a later team-mode phase; this step is read-only forward
+compatibility).
+
+## Output format
+
+- The plugin's status output, verbatim.
+- Exactly one trailing `Quota:` block in the format above (counter + both
+  ceilings + per-path OPEN/BLOCKED verdict).
+- Any `team.gate: BLOCK n/N` ledger lines, verbatim, after the quota
+  block — only when present.
+- Gate failures print exactly one block (enable pointer or fail-closed
+  block) and stop.
+
+## Do NOT
+
+- Do NOT run when `ai_team.enabled` is false — enable pointer, stop.
+- Do NOT fabricate a count when the counter file is unreadable — print
+  `Quota: unavailable (<reason>)` instead of a guessed number.
+- Do NOT write to `cli-calls.json` — the transport owns the counter; this
+  wrapper is read-only.
+- Do NOT reimplement job tracking inline when the plugin is absent — fail
+  closed with the doctor pointer (the quota block alone is still printed on
+  non-Claude-Code hosts, per Step 2).
+
+## See also
+
+- `/team` — master orchestrator: gates, boundary table vs `/council`.
+- `docs/contracts/ai-team-config.md` — `ai_team.max_calls_per_day`.
+- `ai-council` skill — the shared CLI transport that maintains the counter.

package/dist/agent-src/commands/team-knowledge.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: team-knowledge
 disable-model-invocation: true
+argument-hint: "[consolidate|bootstrap]"
 pack: meta
 intent: "Manage the repo-tracked team-knowledge layer — consolidate typed observation events into agents/knowledge/ pages, bootstrap a project baseline"
 routes_to: [team-knowledge-consolidate, team-knowledge-bootstrap]
@@ -26,13 +27,14 @@ packs:
 Top-level orchestrator for the `/team-knowledge` family — the
 consolidation gate over the typed knowledge-observation events
 captured during normal task work (see
-[`knowledge-pages`](../templates/contexts/knowledge-pages.md) and the
-event schema in `src/scripts/_lib/knowledge_events.ts`).
+[`knowledge-pages`](../../agent-src/templates/contexts/knowledge-pages.md)
+and the event schema in `src/scripts/_lib/knowledge_events.ts`).
 
-Not to be confused with the pre-existing `/knowledge` cluster (local
-file ingestion into `agents/memory/knowledge/`) — different concern
-(arbitrary local documents), unrelated to this repo-tracked,
-lifecycle-typed team-knowledge layer under `agents/knowledge/`.
+Not to be confused with the pre-existing [`/knowledge`](../../product-discovery/knowledge/command.md)
+cluster (local file ingestion into `agents/memory/knowledge/`) — that
+is a different concern (arbitrary local documents), unrelated to this
+repo-tracked, lifecycle-typed team-knowledge layer under
+`agents/knowledge/`.
 
 ## Sub-commands