@event4u/agent-config 2.12.0 → 2.14.0

package/docs/contracts/command-clusters.md

@@ -33,7 +33,7 @@ column 1 of this table.
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `init` · `optimize` · `audit` | AGENTS.md file family (high-frequency) — repurposed 2026-05-09: `init` (was `/copilot-agents init`) · `optimize` (merger of `/optimize agents-md` + `/copilot-agents optimize`) · `audit` (was `/optimize agents`, collapses old `audit` + `check` verbs); legacy folder ops (`prepare` / `cleanup` / folder-`audit`) moved to `/optimize agents-dir` |
-| `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from `road-to-dream-skill-adoption.md`, opt-in via `--confirm-transcript-access` per invocation |
+| `memory` | 2 | `add` · `load` · `promote` · `propose` · `mine-session` · `learn-low-impact` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory`; `mine-session` added 2026-05-10 — manual transcript-mining sub-command from `road-to-dream-skill-adoption.md`, opt-in via `--confirm-transcript-access` per invocation; `learn-low-impact` added 2026-05-15 — upstreams `## Validated` entries from `agents/low-impact-decisions.md` to the package seed via a DRAFT PR (re-runs the privacy-floor redactor as a second gate per `low-impact-corpus-privacy-floor`) |
 | `roadmap` | 2 | `create` · `ai-council` · `process-step` · `process-phase` · `process-full` | `roadmap-create` · `roadmap-execute` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope); `ai-council` added 2026-05-07 — wraps `/council default` with `--input-mode roadmap --depth deep` |
 | `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
 | `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
@@ -42,7 +42,7 @@ column 1 of this table.
 | `judge` | 2 | `solo` · `on-diff` · `steps` | `judge` (legacy standalone) · `do-and-judge` · `do-in-steps` |
 | `commit` | 2 | `in-chunks` | `commit-in-chunks` |
 | `create-pr` | 2 | `description-only` | `create-pr-description` |
-| `council` | 3 | `default` · `pr` · `design` · `optimize` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize` |
+| `council` | 3 | `default` · `pr` · `design` · `optimize` · `analysis` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize`; `analysis` added 2026-05-14 — wrapper for local analysis outputs with a Top-N consensus tail block consumed by `/roadmap create` |
 | `challenge-me` | — | `vision` · `with-docs` | new — Pocock-inspired one-question-at-a-time interview; `vision` is the standard 95%-confidence variant, `with-docs` adds doc/glossary awareness with a session-scoped glossary and load-bearing claim-vs-code verification |
 | `research` | 2 | `deep` · `report` | preliminary-research scaffolder ported from `Weizhena/Deep-Research-skills` (cluster head emits `outline.yaml` + `fields.yaml` against the `research-schema` contract). `:deep` populates per-item JSON in batches with native web-search + JSON-Schema self-validation (no Python runtime); `:report` renders `report.md` directly + optionally emits a `jq` template for deterministic regeneration. `add-items` / `add-fields` intentionally **not** ported — re-run `/research <topic>` to extend the field framework. |
 | `orchestrate` | — | _(none yet — cluster head only)_ | new — runtime executor for YAML pipelines under `.agent-config/orchestrations/` per the [`orchestration-dsl-v1`](orchestration-dsl-v1.md) contract; chains personas / skills / commands / sub-agents deterministically. Single cluster head; sub-commands deferred until a second verb is needed. |
@@ -119,6 +119,62 @@ grandfathered indefinitely; modifying them does NOT require adding
 the field. The goal is to stop the atomic surface from growing,
 not to retro-fit every legacy command into a cluster.
 
+## Master / wrapper sub-command shape (`council` cluster)
+
+The `council` cluster uses a **master / wrapper** shape within the flat
+ADR-003 dispatch — the only cluster currently shaped this way. It does
+not break ADR-003 (still one level of sub-commands) and is documented
+here so future lens additions follow the same shape.
+
+- **Master:** `/council default` owns the full orchestration — Step 1
+  (resolve target + capture `original_ask`), Step 2 (configure check +
+  price-table freshness), Step 3 (cost confirmation), Step 4 (run CLI),
+  Step 5 / 5a / 5b (render → critical-evaluation lens → user options),
+  Step 6 (hard floor). See [`commands/council.md` → `## Architecture`](../../.agent-src.uncompressed/commands/council.md).
+- **Wrappers:** `/council pr` · `/council design` · `/council optimize`
+  resolve lens-specific input (PR target / design artefact / optimization
+  target + metric), capture a wrapper-specific `original_ask`, then
+  delegate to `/council default` with `mode_override=<lens>`. They MUST
+  NOT re-implement cost-gate, CLI invocation, render, or host-verdict;
+  those flow through the master verbatim. Wrapper step references anchor
+  to the master (e.g. "cost gate from `/council default` Step 3",
+  "render via Step 5/5a/5b of `/council default`"), not the wrapper.
+- **Single source of lens addendums:** lens-specific neutrality
+  addendums live in [`scripts/ai_council/prompts.py:_MODE_TABLE`](../../scripts/ai_council/prompts.py)
+  and are selected by `mode_override`. A new lens = a new `_MODE_TABLE`
+  entry **plus** a new wrapper file mirroring the `pr.md` / `design.md` /
+  `optimize.md` shape (~100–130 lines). No new master.
+- **Behavioural changes** to the orchestration (e.g. a new render step)
+  land in `default.md` + `_MODE_TABLE` only; wrappers inherit
+  automatically. This invariant is what makes the shape safe under the
+  flat ADR-003 contract — the wrapper is text-only delegation.
+
+Cluster-table names are unchanged: `/council default` is the master,
+the other wrappers (`pr`, `design`, `optimize`, `analysis`) follow the
+same shape. The deprecation shims for the four legacy slugs (`/council`,
+`/council-pr`, `/council-design`, `/council-optimize`) continue to
+follow the standard shim contract below.
+
+### Wrapper output shapes (consumer contract)
+
+Each wrapper renders the standard stacked + Convergence/Divergence
+layout from `/council default` Step 5/5a/5b. Wrappers MAY append a
+**lens-specific tail block** when their output is the input to a
+downstream command — locking the tail shape avoids brittle scraping.
+
+| Wrapper | Tail block | Downstream consumer |
+|---|---|---|
+| `pr` | (optional) one-line PR header at top; no structured tail | `gh pr comment` (opt-in single comment) |
+| `design` | (none — open-ended prose) | Human reader; `/feature plan` / `/feature refactor` |
+| `optimize` | (none — open-ended prose) | Human reader |
+| `analysis` | `## Top-N consensus findings (roadmap-ready first)` — numbered list, each finding with `evidence-grade` (confirmed / inferred / speculative), `roadmap-ready` (yes / needs-discovery), `cited by`, `supporting citation` | `/roadmap create` |
+
+The `analysis` Top-N block is the only structured tail shipped today.
+Its fields are normative — `/roadmap create` parses them to draft a
+roadmap; renaming or reordering them is a breaking change for the
+council → roadmap pipeline. Cap at N=10 unless the upstream analysis
+has fewer findings.
+
 ## Deprecation shim contract
 
 A shim is a one-file stub that:

package/docs/contracts/command-surface-tiers.md

@@ -12,7 +12,8 @@ keep-beta-until: 2026-08-12
 > - **CLI commands** rendered by `./agent-config --help`.
 > - **Slash commands** under `.agent-src.uncompressed/commands/**`.
 >
-> Per Phase 4 of `agents/roadmaps/road-to-distribution-maturity.md`.
+> Per Phase 4 of the distribution-maturity roadmap (see
+> `agents/roadmaps/` for current status).
 
 ## Why tiering
 
@@ -157,6 +158,6 @@ Hooked into `task lint-skills` so it runs in CI.
 
 ## See also
 
-- `agents/roadmaps/road-to-distribution-maturity.md` — Phase 4.
+- The distribution-maturity roadmap — Phase 4 (under `agents/roadmaps/`).
 - `docs/contracts/command-clusters.md` — orchestrator → child wiring.
 - `docs/contracts/STABILITY.md` — surface-stability commitments.

package/docs/contracts/cost-profile-defaults.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
 # Cost-Profile Defaults — Contract
 
 > **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-05-14

package/docs/contracts/decision-engine-gates.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
 # Decision-engine gates (v1)
 
 **Status:** beta — landed 2026-05-14 via `road-to-productization.md` Phase 2.

package/docs/contracts/decision-trace-v1.md

@@ -119,8 +119,8 @@ is `low`.
 **Purpose.** Bound the surface area where a memory hit can be said
 to have *changed* an outcome. Closed list, not open — without this
 bound, every memory call risks the "memory affected everything"
-failure mode (Risk register row 2 of
-[`agents/roadmaps/road-to-proof-not-features.md`](../../agents/roadmaps/road-to-proof-not-features.md)).
+failure mode (Risk register row 2 of the `road-to-proof-not-features`
+roadmap; see `agents/roadmaps/` or `agents/roadmaps/archive/`).
 
 **Closed list (v1).** Exactly four keys. Adding a fifth requires a
 schema bump + entry under `### Breaking` in `CHANGELOG.md`.