@event4u/agent-config 1.16.0 → 1.17.0

package/docs/contracts/artifact-engagement-flow.md

@@ -4,15 +4,13 @@ stability: beta
 
 # Artifact Engagement — Flow & Recording Contract
 
-> Cross-cutting reference for the artifact-engagement telemetry system
-> shipped under
-> [`road-to-artifact-engagement-telemetry.md`](../../agents/roadmaps/road-to-artifact-engagement-telemetry.md).
-> Phase 1 + 2 ship the schema, CLI, and engine. Phase 3 ships the
-> agent-side hooks (this document).
+> Cross-cutting reference for the artifact-engagement telemetry system.
+> The schema, CLI, and engine ship first; the agent-side hooks (this
+> document) ship after.
 >
 > - **Created:** 2026-04-30
-> - **Status:** Phase 5 — schema, engine, recording, aggregator, renderer,
->   and redaction validator are in place. Phase 6 (dogfooding) next.
+> - **Status:** schema, engine, recording, aggregator, renderer, and
+>   redaction validator are in place. Dogfooding next.
 
 This document is the stable reference for **what gets recorded, when, and
 under which constraints**. The roadmap tracks phased delivery; the rule
@@ -255,8 +253,7 @@ layers reject.
 
 ## See also
 
-- [`road-to-artifact-engagement-telemetry`](../../agents/roadmaps/road-to-artifact-engagement-telemetry.md) — phased delivery
 - [`artifact-engagement-recording`](../../.agent-src.uncompressed/rules/artifact-engagement-recording.md) — agent-side trigger
 - [`implement-ticket-flow`](implement-ticket-flow.md) — the eight-step contract this rule observes
 - [`scripts/telemetry/`](../../.agent-src.uncompressed/templates/scripts/telemetry/) — schema, boundary session, settings reader
-- [`tests/telemetry/`](../../tests/telemetry/) — contract enforcement (104 cases through Phase 5: schema, settings, aggregator, renderer, CLI, cost-floor, redaction)
+- [`tests/telemetry/`](../../tests/telemetry/) — contract enforcement (schema, settings, aggregator, renderer, CLI, cost-floor, redaction)

package/docs/contracts/command-clusters.md

@@ -4,10 +4,9 @@ stability: beta
 
 # Command-cluster contract
 
-> **Status:** beta — locked for `1.15.0` Phase 1 (top-3 clusters).
-> Phase 2 (remaining 12 clusters) waits one deprecation cycle.
-> Source roadmap: [`agents/roadmaps/archive/road-to-governance-cleanup.md`](../../agents/roadmaps/archive/road-to-governance-cleanup.md)
-> § F2.
+> **Status:** beta — Phase 1 locked for `1.15.0` (top-3 clusters);
+> Phase 2 locked for `1.17.0` (the remaining 12 clusters);
+> Phase 3 locked for `1.17.0` (`council` cluster).
 
 The agent-config command surface collapses related atomic commands
 into **verb clusters**. A cluster is a single top-level command
@@ -21,35 +20,36 @@ linter (`scripts/lint_no_new_atomic_commands.py`) reads this file;
 new atomic commands without a `cluster:` field pointing to an
 entry below fail CI.
 
-## Phase 1 clusters (locked, ship in 1.15.0)
-
-| Cluster | Sub-commands | Replaces |
-|---|---|---|
-| `fix` | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder` |
-| `optimize` | `agents` · `augmentignore` · `rtk` · `skills` | `optimize-agents` · `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` |
-| `feature` | `explore` · `plan` · `refactor` · `roadmap` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` |
-
-**Net Phase 1:** 15 atomic commands → 3 cluster commands.
-
-## Phase 2 clusters (deferred to next minor release)
-
-Listed in `road-to-governance-cleanup.md` § Finding 2. Not yet locked
-into the linter; new atomic commands matching these prefixes still
-fail CI without a `cluster:` field once a Phase 2 entry is added
-here.
-
-- `chat-history` (`show` · `resume` · `clear` · `checkpoint`)
-- `agents` (`audit` · `cleanup` · `prepare`)
-- `memory` (`add` · `load` · `promote` · `propose`)
-- `roadmap` (`create` · `execute`)
-- `module` (`create` · `explore`)
-- `tests` (`create` · `execute`)
-- `context` (`create` · `refactor`)
-- `override` (`create` · `manage`)
-- `copilot-agents` (`init` · `optimize`)
-- `commit` (flag: `--in-chunks`)
-- `judge` (`solo` · `steps` · `on-diff`) + standalone `/review`
-- `create-pr` (flag: `--description-only`)
+## Locked clusters
+
+The full set, both phases. Linter parses every backticked name in
+column 1 of this table.
+
+| Cluster | Phase | Sub-commands | Replaces |
+|---|:-:|---|---|
+| `fix` | 1 | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder` |
+| `optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `optimize-agents` · `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` |
+| `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
+| `chat-history` | 2 | `show` · `resume` · `clear` · `checkpoint` | `chat-history` (legacy status) · `chat-history-resume` · `chat-history-clear` · `chat-history-checkpoint` |
+| `agents` | 2 | `audit` · `cleanup` · `prepare` | `agents-audit` · `agents-cleanup` · `agents-prepare` |
+| `memory` | 2 | `add` · `load` · `promote` · `propose` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory` |
+| `roadmap` | 2 | `create` · `execute` | `roadmap-create` · `roadmap-execute` |
+| `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
+| `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
+| `context` | 2 | `create` · `refactor` | `context-create` · `context-refactor` |
+| `override` | 2 | `create` · `manage` | `override-create` · `override-manage` |
+| `copilot-agents` | 2 | `init` · `optimize` | `copilot-agents-init` · `copilot-agents-optimize` |
+| `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` |
+
+**Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
+collapses 26 atomics → 11 sub-command clusters. Sub-commands use
+colon syntax (`/cluster:sub`) so Claude Code's command palette can
+autocomplete them. The standalone `/review` surface that mirrors
+`judge solo` lives at
+[`commands/review-changes.md`](../../.agent-src.uncompressed/commands/review-changes.md).
 
 ## Frontmatter contract
 
@@ -70,7 +70,7 @@ The linter only flags **newly-added** files under `commands/`
 (git status `A`). Pre-existing commands without `cluster:` are
 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 Phase 1 cluster.
+not to retro-fit every legacy command into a cluster.
 
 ## Deprecation shim contract
 
@@ -92,22 +92,24 @@ file with `superseded_by:` set.
 
 ## Removal cycle
 
-| State | Release |
-|---|---|
-| Cluster command shipped, shim active | `1.15.0` |
-| Shim emits warning, both work | `1.15.x` (one minor cycle) |
-| Shim removed, only cluster works | `1.16.0` |
+| State | Phase 1 | Phase 2 |
+|---|---|---|
+| Cluster command shipped, shim active | `1.15.0` | `1.17.0` |
+| Shim emits warning, both work | `1.15.x` / `1.16.x` (≥ one minor cycle) | `1.17.x` (one minor cycle) |
+| Shim removed, only cluster works | `1.17.0` (Phase 1 atomics removed alongside Phase 2 lock-in) | next minor after `1.17.x` |
 
-No permanent aliases. Consumers who pin a 1.15 minor get a full
-release window of warnings; the 1.16 release notes call out the
-removal explicitly.
+No permanent aliases. Consumers who pin a 1.17 minor get a full
+release window of warnings; the next-minor release notes call out
+the removal explicitly. The 1.17.0 release ships Phase 2 cluster
+locks **and** drops the seven Phase 1 atomic shims at the end of
+their deprecation cycle.
 
 ## Linter behavior
 
 `scripts/lint_no_new_atomic_commands.py`:
 
 - Reads the locked cluster names from this file (parsed from the
-  Phase 1 table above).
+  "Locked clusters" table above — column 1 backticks).
 - Finds every command file **added** since `--baseline`
   (default: `main`) — modifications to existing files are ignored.
 - For each new file, requires `cluster:` to be set to one of the
@@ -116,11 +118,19 @@ removal explicitly.
 
 `--all` mode (manual audit only, not in CI) lints every command
 file and surfaces grandfathered ones — useful when planning a
-Phase 2 cluster expansion.
+future cluster expansion.
+
+`scripts/check_cluster_patterns.py` (Phase 2 onward):
+
+- Compares each cluster dispatcher's structure against the Phase 1
+  reference patterns (`commands/fix.md`, `commands/optimize.md`,
+  `commands/feature.md`).
+- Required sections: top-of-file `# /<cluster>`, `## Sub-commands`
+  table with `Sub-command | Routes to | Purpose` columns, `## Dispatch`
+  steps, `## Migration` notice, `## Rules` block.
+- Fails CI if a new cluster invents a different dispatch shape.
 
 ## See also
 
-- [`agents/roadmaps/archive/road-to-governance-cleanup.md`](../../agents/roadmaps/archive/road-to-governance-cleanup.md) — F2 phased-collapse decision.
-- [`agents/roadmaps/road-to-post-pr29-optimize.md`](../../agents/roadmaps/road-to-post-pr29-optimize.md) — P0.8 anchors this contract in 1.15.0.
 - [`docs/migrations/commands-1.15.0.md`](../migrations/commands-1.15.0.md) — user-facing migration notes.
 - [`docs/contracts/STABILITY.md`](STABILITY.md) — `beta` level rules apply.

package/docs/contracts/command-suggestion-flow.md

@@ -4,8 +4,7 @@ stability: beta
 
 # Command Suggestion — Flow & Scoring Contract
 
-> Cross-cutting reference for the suggestion layer shipped under
-> [`road-to-context-aware-command-suggestion.md`](../../agents/roadmaps/road-to-context-aware-command-suggestion.md).
+> Cross-cutting reference for the suggestion layer.
 > The runtime rule is [`command-suggestion`](../../.agent-src.uncompressed/rules/command-suggestion-policy.md);
 > the architectural decision lives in [`adr-command-suggestion.md`](adr-command-suggestion.md).
 >
@@ -144,5 +143,4 @@ Cursor, Cline, Windsurf) get the engine via `scripts/`.
 - [`command-suggestion`](../../.agent-src.uncompressed/rules/command-suggestion-policy.md) — runtime rule
 - [`adr-command-suggestion.md`](adr-command-suggestion.md) — architectural decision
 - [`command-suggestion-eligibility.md`](command-suggestion-eligibility.md) — locked eligibility table
-- [`road-to-context-aware-command-suggestion.md`](../../agents/roadmaps/road-to-context-aware-command-suggestion.md) — phased delivery
 - [`agent-settings`](../../.agent-src.uncompressed/templates/agent-settings.md) — `commands.suggestion.*` reference

package/docs/contracts/context-paths.md

@@ -0,0 +1,99 @@
+---
+stability: beta
+---
+
+# Context-file path conventions
+
+> **Audience:** rule, skill, and command authors who need to extract
+> reasoning material into a `contexts/` file.
+> **Linter:** `scripts/check_context_paths.py`
+> (run via `task check-context-paths`).
+> **Companion:** [`load-context-schema.md`](load-context-schema.md) —
+> frontmatter contract for citing a context from a rule.
+
+This contract defines **where** a context file is allowed to live under
+`.agent-src.uncompressed/contexts/` (the source-of-truth tree). It is the
+DAG root of `road-to-structural-optimization` Phase 0: the file-ownership
+matrix (Phase 0.1) greps for context-file fan-out at the locked tree, and
+several later phases (2A, 2B, 3a/b/c, 6) extract material into specific
+sub-trees named here. Locking the layout up-front keeps the matrix
+deterministic and prevents naming drift across phases.
+
+**Status:** internal-locked. Changes require a contract version bump and
+a roadmap revision (per `road-to-structural-optimization.md` § Definitions).
+
+## Locked path tree
+
+| Sub-tree | Owner phase | Naming convention |
+|---|---|---|
+| `contexts/communication/rules-always/` | Phase 2A | `<rule-name>-mechanics.md` |
+| `contexts/communication/rules-auto/` | Phase 2B | `<rule-name>-mechanics.md` |
+| `contexts/judges/` | Phase 3a | `judge-shared-procedure.md`, `persona-voice-rubric.md`, `no-consolidate-rationale.md` |
+| `contexts/analysis/` | Phase 3b | `project-analysis-core-procedure.md` (+ future siblings) |
+| `contexts/skills/` | Phase 3c | `skill-quality-rules.md` (+ future siblings) |
+| `contexts/chat-history/` | Phase 6 | `cadence.md`, `ownership.md`, `visibility.md` |
+| `contexts/execution/` | PR #34 (existing) | `<topic>-mechanics.md`, `<topic>-detection.md`, `<topic>-examples.md` |
+| `contexts/authority/` | PR #34 (existing) | `<topic>-mechanics.md` |
+
+## Grandfathered files
+
+The six root-level files below predate this contract and stay where they
+are. **No new files at the contexts root** — every new context must live
+in a sub-tree above.
+
+```
+contexts/augment-infrastructure.md
+contexts/documentation-hierarchy.md
+contexts/model-recommendations.md
+contexts/override-system.md
+contexts/skills-and-commands.md
+contexts/subagent-configuration.md
+```
+
+## Rules enforced by `check_context_paths.py`
+
+1. **Sub-tree allow-list.** Every `*.md` under
+   `.agent-src.uncompressed/contexts/` must be either (a) in one of the
+   eight locked sub-trees above, or (b) one of the six grandfathered
+   root-level files. Anything else fails CI.
+2. **No collisions.** No two context files may share the same basename
+   across sub-trees. `judges/persona-voice-rubric.md` and
+   `analysis/persona-voice-rubric.md` are mutually exclusive.
+3. **No orphans.** Every context file must be referenced from at least
+   one rule, skill, command, or other context. References count as either
+   a frontmatter `load_context:` / `load_context_eager:` entry, **or** a
+   markdown body mention of the relative path
+   (`contexts/<sub-tree>/<file>.md` or
+   `.agent-src.uncompressed/contexts/<sub-tree>/<file>.md`).
+
+The linter exits non-zero on any violation and prints a one-line
+diagnostic per offence.
+
+## Adding a new sub-tree
+
+1. Open a roadmap revision proposing the new sub-tree (owner phase,
+   naming convention, expected first-mover file).
+2. Council-review under the same gate as a `load_context:` schema change.
+3. Bump this contract's version line in the roadmap (G2 fan-out: the
+   ownership matrix re-runs after the bump and new cells must remain
+   `READ_ONLY` only).
+4. Update `LOCKED_SUBTREES` in `scripts/check_context_paths.py` and
+   the table above in the same PR.
+
+## Why `check_context_paths.py` carries the orphan check
+
+`road-to-structural-optimization.md` 0.6.3 specified extending
+`scripts/docs-sync.py` for the orphan check. That script does not exist
+in this repo (the cross-reference checker lives in
+`scripts/check_references.py`, scoped to broken refs rather than orphan
+detection). Folding the orphan check into `check_context_paths.py` keeps
+all context-file invariants in one linter and avoids inventing a new
+sync tool. Functionally equivalent to the roadmap intent; the roadmap
+itself is annotated with this deviation.
+
+## See also
+
+- [`load-context-schema.md`](load-context-schema.md) — how a rule cites
+  one of these paths in frontmatter.
+- [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) — which rule
+  wins when several fire on the same turn (independent of context paths).