@event4u/agent-config 7.5.0 → 8.0.0

package/dist/agent-src/commands/analyze/incident.md

@@ -94,11 +94,11 @@ type, affected paths) per
 
 Surface the draft and ask:
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 ### Rules
 

package/dist/agent-src/commands/analyze/near-miss.md

@@ -90,11 +90,11 @@ draft an `incident-learnings` candidate via `/memory propose`:
 
 ### 5. Surface the candidate to the user
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 ### Rules
 

package/dist/agent-src/commands/analyze/postmortem.md

@@ -108,11 +108,11 @@ update an existing one.
 
 Present the draft candidate and ask:
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 ### Rules
 

package/dist/agent-src/commands/analyze/premortem.md

@@ -82,11 +82,11 @@ If the analysis surfaces a pattern worth preserving for future plans:
 
 3. Surface the candidate to the user and ask:
 
-> 1. Propose this candidate to `/memory propose` (recommended)
+> 1. Propose this candidate to `/memory propose`
 > 2. Refine before proposing — suggest changes
 > 3. Skip memory candidate for now
 
-**Empfehlung:** 1
+**Recommendation:** 1
 
 ### Rules
 

package/dist/agent-src/commands/cost-report.md

@@ -100,6 +100,31 @@ BUDGET_PERIOD=week node scripts/cost/budget.mjs check
 
 Allowed values: `today`, `week`, `month`, `all` (default).
 
+### 6. Orchestration telemetry summary (when telemetry exists)
+
+Read the current-month JSONL from `agents/runtime/state/audit/YYYY-MM.jsonl`
+(`YYYY-MM` = current UTC month). If it exists and has lines with `input_kind:
+"orchestration"`, surface an orchestration summary via `readOrchestrationMetrics`
+from `src/scripts/_lib/subagent_steering.ts`:
+
+```
+Orchestration telemetry (YYYY-MM, N dispatches):
+  avg token_delta:     ±NNN  (positive = cost more; negative = saved)
+  spawn_failure_rate:  N.N%  (threshold: 10%)
+  verify_skip_rate:    N.N%  (threshold: 1%)
+  guardrail breaches:  [token_blowup | spawn_failure | verify_skip | none]
+```
+
+No orchestration lines yet (capture not running or no delegated dispatches this
+month) → surface:
+
+> No orchestration telemetry yet — subagent dispatches begin writing to
+> `agents/runtime/state/audit/YYYY-MM.jsonl` once `subagents.enabled: true`
+> and a dispatch runs.
+
+Skip this step entirely if the user did not ask about orchestration telemetry and
+there is no `agents/runtime/state/audit/` directory.
+
 ## Rules
 
 - **Local-only.** Never persist cost data to remote stores. The

package/dist/agent-src/commands/evals/analyze.json

@@ -0,0 +1,30 @@
+{
+  "command": "analyze",
+  "intent": "Analysis dispatcher — classify input by keywords, propose a weighted framework path, let the user pick",
+  "cases": [
+    {
+      "prompt": "analyze what went wrong in yesterday's deploy",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "run a post-mortem on the checkout outage",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "we're about to launch — do a pre-mortem on the migration plan",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "review the decision we made about the queue architecture last quarter",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "that was almost a data-loss incident — analyze the near miss",
+      "expected": "analyze"
+    },
+    {
+      "prompt": "walk me through a structured incident analysis for the API downtime",
+      "expected": "analyze"
+    }
+  ]
+}

package/dist/agent-src/commands/evals/mission-upgrade.json

@@ -0,0 +1,30 @@
+{
+  "command": "mission-upgrade",
+  "intent": "Upgrade a Laravel application one major version (10→11, 11→12) via the gated /work engine with a structured breaking-change catalog",
+  "cases": [
+    {
+      "prompt": "upgrade our Laravel app from 10 to 11",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "bump laravel/framework to the next major version",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "run the Laravel 11 to 12 upgrade with the breaking-change catalog",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "plan and execute the framework major-version upgrade for this Laravel project",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "migrate this app to the new Laravel major release",
+      "expected": "mission-upgrade"
+    },
+    {
+      "prompt": "our composer.json pins laravel 10 — take it to 11 safely",
+      "expected": "mission-upgrade"
+    }
+  ]
+}

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

@@ -61,7 +61,7 @@ engine — they make a `lite`-tier build safe (per
   `done`. If a dependency is open, STOP and surface it — never build
   out of order.
 - **Pre-build staleness gate.** Run
-  `python3 src/scripts/lint_ticket_buildable.ts` on the bundle. An
+  `./scripts-run src/scripts/lint_ticket_buildable` on the bundle. An
   `adr_refs` SHA drift is a **hard** stop ("re-emit the bundle"); a
   `source_refs` SHA drift only **warns** and proceeds (split severity).
 - **Boundary guard.** Carry the ticket's `boundaries`

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

@@ -46,7 +46,7 @@ If the prefix is missing → print the usage line above and stop. Do
 ### 2. Run the implementation
 
 ```bash
-python3 packages/core/installer/python/knowledge_ingest.py \
+./agent-config knowledge \
     forget <ingest-id-prefix>
 ```
 

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

@@ -55,7 +55,7 @@ Run before any file is touched:
 ### 3. Run the implementation
 
 ```bash
-python3 packages/core/installer/python/knowledge_ingest.py \
+./agent-config knowledge \
     ingest <path> [--no-redact] [--markitdown=<bin>]
 ```
 

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

@@ -46,7 +46,7 @@ sorted by `created_at` ascending. Read-only by default; `--pin` and
 ### 2. Run the implementation
 
 ```bash
-python3 packages/core/installer/python/knowledge_ingest.py \
+./agent-config knowledge \
     list [--format=...] [--pin <id-prefix>] [--unpin <id-prefix>]
 ```
 

package/dist/agent-src/commands/memory/load.md

@@ -66,15 +66,16 @@ If the lookup helper does not yet support `--priority`, fall back to a
 file-only sweep:
 
 ```bash
-python3 - <<'PY'
-import pathlib, yaml
-for f in sorted(pathlib.Path("agents/memory").rglob("*.yml")):
-    data = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
-    for e in data.get("entries", []) or []:
-        if e.get("priority") == "critical" and e.get("status") == "active":
-            print(f"--- {f.parent.name}/{e.get('id')}")
-            print(yaml.safe_dump(e, sort_keys=False), end="")
-PY
+node -e '
+const fs = require("fs"), path = require("path"), yaml = require("js-yaml");
+const glob = (dir) => fs.readdirSync(dir, {recursive: true}).filter(f => f.endsWith(".yml")).map(f => path.join(dir, f));
+for (const f of glob("agents/memory").sort()) {
+    const data = yaml.load(fs.readFileSync(f, "utf8")) || {};
+    for (const e of data.entries || [])
+        if (e.priority === "critical" && e.status === "active")
+            console.log("---", path.basename(path.dirname(f)) + "/" + e.id, "\n" + yaml.dump(e, {sortKeys: false}));
+}
+'
 ```
 
 The Tier-0 slice is surfaced once per `/memory:load` invocation, even
@@ -88,7 +89,7 @@ Before loading, count the entries:
 
 ```bash
 ./agent-config memory:lookup --types <type> --format json | \
-  python3 -c "import sys, json; print(len(json.load(sys.stdin)))"
+  node -e "const d = []; process.stdin.on('data', c => d.push(c)); process.stdin.on('end', () => console.log(JSON.parse(d.join('')).length))"
 ```
 
 If the count exceeds 25, warn:
@@ -131,7 +132,7 @@ After step 4, count unreviewed intake entries for the same type:
 
 ```bash
 ./agent-config memory:lookup --types <type> --intake-only --format json | \
-  python3 -c "import sys, json; print(len(json.load(sys.stdin)))"
+  node -e "const d = []; process.stdin.on('data', c => d.push(c)); process.stdin.on('end', () => console.log(JSON.parse(d.join('')).length))"
 ```
 
 Read `memory.review_threshold` from `.agent-settings.yml` (default 10).

package/dist/agent-src/commands/memory/promote.md

@@ -116,6 +116,36 @@ schema to write to and record the override in the `source:` block.
 
 Show the YAML draft and ask for confirmation before writing.
 
+### 3b. Contradiction check — durable types only
+
+For the behaviorally load-bearing durable types (`incident-learnings`,
+`product-rules`, `domain-invariants`), run the mechanical contradiction
+detector before writing (same primary key + Jaccard body similarity
+< 0.3 → same topic, different claim):
+
+```bash
+./scripts-run src/scripts/check_memory_contradiction \
+    --type <type> --key <curated id or key field> --body "<draft body>"
+```
+
+- Exit `0` → proceed to Step 4.
+- Exit `1` → a potential contradiction pair was surfaced. **Never
+  auto-resolve** (council REJECT list). Ask the human via the contested
+  flow:
+
+  ```
+  > ⚠️ The draft may contradict an existing durable entry (same key, low similarity).
+  >
+  > 1. Approve new + mark the existing entry `contested` (with provenance: what changed, which session)
+  > 2. Revise the new draft — the existing entry stands
+  > 3. Both are valid in different scopes — narrow the new entry's key and re-check
+  ```
+
+Warning surface, not a gate — the human's pick resolves it; the
+detector never blocks a promote on its own. Non-durable types
+(`sessions`-style exploratory content, `recurring-patterns`, …) are
+deliberately not checked — they evolve legitimately.
+
 ### 4. Write the curated entry (content-addressed)
 
 Compute the content hash and write a **one-entry file** at

package/dist/agent-src/commands/memory/propose.md

@@ -75,7 +75,21 @@ Ask once, numbered. If the user picks `skip`, proceed without them:
   primary tag picks the intake JSONL file, the promoter resolves the
   curated target via tag intersection.
 
-### 4. Emit via the shared helper
+### 4. Check for a near-duplicate (advisory)
+
+```bash
+./scripts-run src/scripts/check_memory_similarity --type <type> --body "<body>"
+```
+
+Token-Jaccard similarity against existing intake signals of the same
+type — advisory, additive, never touches the exact-match dedup in
+Step 5. Exit 1 (≥ 80% similar) → surface the matched signal id and ask
+whether to reuse/update it instead of creating a new one; proceed to
+Step 5 only if the user confirms this is a genuinely distinct finding.
+Exit 0 with a "nearest match" note (40–79% similar) → mention it, then
+proceed. Exit 0 with no match → proceed silently.
+
+### 5. Emit via the shared helper
 
 ```bash
 ./agent-config memory:signal \
@@ -95,7 +109,7 @@ automatically — re-running the command on the same finding will
 silently skip the write. Add `--force` only when deliberate duplication
 is intended (rarely).
 
-### 5. Confirm and close
+### 6. Confirm and close
 
 ```
 > ✅ Signal queued as id=<sig-xxxxxx> in <file>.

package/dist/agent-src/commands/mission/upgrade.md

@@ -42,7 +42,7 @@ Before starting, confirm:
 Any fail → surface the conflict and stop. Run:
 
 ```bash
-python3 src/scripts/lint_missions.ts --check-precondition upgrade .
+./scripts-run src/scripts/lint_missions --check-precondition upgrade .
 ```
 
 (Currently a documented stub — full live-repo check lands in Phase 1 PoC.)

package/dist/agent-src/commands/module/explore.md

@@ -41,11 +41,15 @@ unset):
 - **Node / TS monorepo**: Check `packages/`, `apps/`, or `modules/`.
 - **Python**: Check top-level package dirs under `src/<package>/` or flat `<package>/`.
 - **Go**: Check `internal/<domain>/` or `cmd/<service>/`.
-- If none of the above exists:
-  ```
-  ⚠️  No module system found (no Modules/, src/<Domain>/, packages/, internal/, or equivalent directory).
-  ```
-  Stop.
+
+If both the `modules:` block and the fallback table yield nothing:
+
+```
+⚠️  No module system found (no Modules/, src/<Domain>/, packages/, internal/, or equivalent directory).
+   Run `./scripts-run src/scripts/propose_modules_config` to surface candidates.
+```
+
+Stop.
 
 ### 2. List available modules
 
@@ -82,8 +86,8 @@ Let `{module_dir}` be the selected module's `module_path` from
 
 **Structure:**
 - List all directories and files (2 levels deep)
-- Count PHP files per directory (Controllers, Services, Models, Jobs, Commands, etc.)
-- List route files and their contents
+- Count source files per directory (Controllers, Services, Models, Jobs, Commands, etc. — adapt to the configured stack)
+- List route / entry-point files and their contents
 
 **Code:**
 - Use `codebase-retrieval` to understand the module's purpose and key classes

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

@@ -0,0 +1,243 @@
+---
+model_tier: high
+name: optimize-project
+pack: engineering-base
+tier: 2
+visibility: internal
+skills: [project-analyzer, decision-review, roadmap-writing]
+description: "Project-wide optimization sweep — inventory roadmaps, ADRs, agent folders (incl. modules), challenge stale decisions with the user in the loop, emit new roadmap(s). E.g. 'optimize this project'."
+suggestion:
+  eligible: true
+  trigger_description: "optimize this project, optimize the project, what should we improve based on current state, challenge our old decisions, are our roadmaps and ADRs still right, optimiere das Projekt, hinterfrag unsere alten Entscheidungen"
+  trigger_context: "user wants a project-wide review that questions existing state (roadmaps, ADRs, decisions, structures) and ends in new roadmap(s) — NOT a bug fix, NOT a single-decision audit (/analyze:decision), NOT agent-layer tooling (/optimize)"
+workspaces:
+  - engineering
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /optimize-project
+
+Project-wide optimization loop: **inventory → challenge → interview →
+roadmap(s)**. Analyzes project it runs in (package or consumer),
+questions existing state — roadmaps, ADRs, decisions, structures, in
+this package e.g. token consumption, memory, learnings — asks user
+when flipping old decision would be real improvement, ends by emitting
+one or more NEW roadmaps via `/roadmap:create`.
+
+**Coordinator** over existing primitives — composes, never
+reimplements: `/project-health`-style inventory, `/challenge-me`
+interview mechanics, `/analyze:decision`-style decision challenge,
+`/roadmap:create` output.
+
+> Looking for agent-layer tooling (skills, agents-dir, augmentignore,
+> rtk filters)? That is the [`/optimize`](optimize.md) cluster —
+> different surface. This command optimizes the **project**, not the
+> agent layer.
+
+## When to invoke
+
+- "Optimize this project" / "optimiere das Projekt".
+- "What should we improve based on the current state?"
+- "Challenge our old decisions" / "are our roadmaps and ADRs still right?"
+- Periodic hygiene: roadmaps accumulated, decisions feel stale,
+  structures grew organically, nobody questioned them.
+
+Do NOT invoke for: single named bug ("fix this"), single decision
+audit (route to `/analyze:decision`), code-only analysis
+(`/project-analyze`), AGENTS.md / agent-layer work (`/agents`,
+`/optimize`).
+
+## Steps
+
+### Step 0 — Scope detection (read-only)
+
+1. Detect target type:
+   - **Package mode** — repo IS `event4u/agent-config` (marker:
+     `src/config/budgets.yml` + `dist/agent-src/` present). Optimization
+     surface additionally: token budget, memory index,
+     learnings/knowledge corpus, lint debt.
+   - **Consumer mode** — any other project with `agents/` tree and/or
+     installed agent layer. Surface = workflows, structures, docs,
+     roadmaps, decisions.
+2. Resolve module roots via
+   `scripts/_lib/agent_settings.py::enumerate_modules()` (Laravel shape:
+   `app/Modules/*/agents/`); fallback `modules.root_paths` in
+   `.agent-settings.yml`.
+3. Exclusions hard: never analyze `vendor/`, `node_modules/`, `dist/`,
+   any generated projection (`.augment/`, `.claude/`, `.cursor/`).
+
+### Step 1 — Inventory (read-only, parallel)
+
+Gather without creating or modifying anything:
+
+- **Roadmaps** — `agents/roadmaps/` (+ per-module roadmap dirs): counts
+  per disposition (active / `later/` / `skipped/` / `archive/`),
+  per-roadmap open/done/deferred checkbox counts, staleness
+  (mtime > 60 days with open items), complete-but-unarchived.
+- **Decisions** — ADR dirs (`docs/adr/`, `docs/decisions/`,
+  `agents/decisions/`): count, age distribution, `status:` fields,
+  superseded chains.
+- **Agent folders** — `agents/` root + every module `agents/` folder:
+  docs, features, contexts; orphaned or stale files (referencing
+  deleted code).
+- **Memory / learnings** (if present) — memory index size, knowledge
+  cards, low-impact decisions corpus; entries whose subject no longer
+  exists in repo.
+- **Package mode only** — budget usage vs cap
+  (`src/config/budgets.yml`), kernel share, corpus size trends, known
+  lint debt, honest-null / don't-relitigate lock inventory (memory
+  index + `agents/settings/contexts/`).
+
+Emit compact inventory report (counts + flagged items), in user's
+language. Present findings incrementally, not one dump.
+
+### Step 2 — Findings & challenge candidates
+
+Classify everything flagged in Step 1 into three buckets:
+
+1. **Mechanical optimizations** — no decision needed, just work: stale
+   roadmap cleanup, complete-but-unarchived roadmaps, dead references,
+   missing module docs, memory entries pointing at deleted code.
+2. **Decision-challenge candidates** — existing decision (ADR, lock,
+   council verdict, structural convention) whose original assumptions
+   may no longer hold. Per candidate record: *the decision · original
+   assumption · what changed since · expected gain from flipping · flip
+   cost/blast radius*. Candidate without concrete "what changed" is not
+   a candidate — drop it.
+3. **Structural / process improvements** — recurring friction visible
+   in inventory (e.g. roadmap sprawl, duplicate contexts, token
+   hot-spots in package mode).
+
+Rank by expected impact vs. effort. **Cap decision-challenge list at
+top 5** (override: `--max-questions=N`). Everything below cap carries
+into Step 4 as "further candidates" — never silently dropped.
+
+Before a candidate built on a claim about current state enters the
+interview, verify the claim against the real source (grep, file read,
+live git/CI state) per
+[`source-discovery-gate`](../rules/source-discovery-gate.md) —
+never challenge a decision from a remembered or assumed fact.
+
+### Step 3 — Challenge interview (user-gated, budgeted)
+
+One question per turn, numbered options with recommendation —
+`/challenge-me` mechanics, per
+[`ask-when-uncertain`](../rules/ask-when-uncertain.md) and
+[`user-interaction`](../rules/user-interaction.md).
+
+Per candidate, present:
+
+```
+> **Decision:** <what was decided, where it is recorded>
+> **Then:** <original assumption>
+> **Now:** <what changed — with evidence source>
+> **Gain if flipped:** <expected improvement> · **Cost:** <blast radius>
+>
+> 1. Keep — assumptions still hold
+> 2. Flip — schedule the change in the output roadmap
+> 3. Re-evaluate via council — genuinely contested, worth a multi-model pass
+> 4. Defer — park as "further candidate"
+```
+
+Hard rules for this step:
+
+- **Locked decisions are never silently flipped.** Honest-null verdict,
+  "don't relitigate" note, budget-canon line, or locked council
+  convergence follows
+  [`decision-revisit-gate`](../rules/decision-revisit-gate.md):
+  check the lock's mechanism/scope actually matches the proposed change
+  and its recorded revisit-conditions first; if it truly blocks, the
+  only flip path offered is option 3 (council re-eval) — "Flip" is not
+  offered for locks.
+- **Session budget:** max 5 interview questions by default
+  (`--max-questions=N` to override). Budget exhausted → remaining
+  candidates go to Step 4 as "further candidates".
+- Interview answers adopted immediately; never re-argue a settled
+  answer.
+
+### Step 4 — Synthesize → roadmap(s)
+
+1. Group accepted work — mechanical optimizations + flipped decisions +
+   structural improvements — into **one or more roadmaps by concern**
+   (keep k small; one roadmap per coherent theme, not one per finding).
+2. For each group, route to [`/roadmap:create`](roadmap/create.md)
+   with structured seed: goal, findings (with evidence), accepted
+   interview decisions, "further candidates" section for uninterviewed
+   remainder.
+3. Council re-evals chosen in interview (option 3) land as explicit
+   first step in the matching roadmap — do NOT auto-run the council
+   from here.
+4. Regenerate roadmap dashboard in same reply
+   (`./agent-config roadmap:progress`) per
+   [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md).
+5. **Hand back and stop.** Per
+   [`scope-control § Authoring vs. implementation`](../rules/scope-control.md)
+   the roadmap is the deliverable — never auto-offer
+   `/roadmap:process-*` or start executing.
+
+## Output
+
+1. **Inventory report** (Step 1) — compact counts + flagged items.
+2. **Findings report** (Step 2) — three buckets, ranked, with
+   challenge-candidate cards.
+3. **Interview** (Step 3) — one question per turn, ≤ budget.
+4. **Roadmap file(s)** (Step 4) — the only files this command creates,
+   via `/roadmap:create`, plus dashboard regen.
+
+## Rules
+
+- **Read-only until Step 4.** Only writes: new roadmap file(s) +
+  dashboard regen. No code edits, no doc rewrites, no deletion —
+  cleanup work becomes roadmap steps, not inline actions.
+- **Never edit or delete existing roadmaps / ADRs / decisions** —
+  flipped decision becomes a roadmap step ("supersede ADR-NNN with …"),
+  never an in-place edit from this command.
+- **No commits, no push, no PR** — [`commit-policy`](../rules/commit-policy.md).
+- **Never silently flip a lock** — [`decision-revisit-gate`](../rules/decision-revisit-gate.md).
+- **One question per turn**, recommendation line under every options
+  block.
+- Mirror user's language in all reports and questions.
+
+## Gotchas
+
+- **Unbounded interview** — without question budget the decision-flip
+  loop can eat the session. Cap is load-bearing; don't lift silently.
+- **Re-litigating without new evidence** — challenge candidate needs
+  concrete "what changed". "I would decide differently today" is not
+  evidence; check the lock's recorded revisit-conditions first.
+- **Scope bleed into `/optimize`** — token/skill/agents-dir tooling
+  findings in package mode are reported, but their execution routes to
+  `/optimize` cluster sub-commands inside the output roadmap.
+- **Roadmap sprawl as output** — five roadmaps for one theme recreates
+  the problem this command fixes. Group by concern.
+- **Vendor noise** — module enumeration comes from
+  `enumerate_modules()`, never a bare glob that catches `vendor/`.
+
+## Do NOT
+
+- Do NOT execute any found optimization in this command's turn — the
+  roadmap is the deliverable.
+- Do NOT auto-run a council session; record it as a roadmap step.
+- Do NOT offer "Flip" on locked decisions — council re-eval only.
+- Do NOT create analysis files (that is `/project-analyze`); this
+  command creates roadmaps only.
+- Do NOT re-ask a settled interview answer.
+
+## See also
+
+- [`/optimize`](optimize.md) — agent-layer tooling cluster (skills,
+  agents-dir, augmentignore, rtk); cross-linked on purpose — closest
+  name, different surface.
+- [`/project-analyze`](project-analyze.md) — deep code/stack analysis
+  with analysis-file output.
+- [`/project-health`](project-health.md) — quick read-only counts, no
+  challenge loop.
+- [`/analyze:decision`](analyze/decision.md) — single-decision audit;
+  this command sweeps and hands hot ones to the interview.
+- [`/challenge-me with-docs`](challenge-me/with-docs.md) — interview
+  mechanics this command borrows, applied to a seed instead of the
+  project state.
+- [`decision-revisit-gate`](../rules/decision-revisit-gate.md) —
+  lock-flip discipline Step 3 enforces.

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

@@ -27,6 +27,11 @@ Top-level orchestrator for the `/optimize` family.
 
 > Looking for `AGENTS.md` operations (init, refactor, audit)? Those
 > live under [`/agents`](agents.md) (`init / optimize / audit`).
+>
+> Looking for **project-wide** optimization (roadmaps, ADRs, decisions,
+> structures — challenge-and-roadmap loop)? That is the standalone
+> [`/optimize-project`](optimize-project.md) — this cluster only covers
+> the agent layer.
 
 ## Sub-commands