@event4u/agent-config 1.16.0 → 1.18.0

package/docs/contracts/file-ownership-matrix.md

@@ -0,0 +1,134 @@
+---
+stability: beta
+---
+
+# File-ownership matrix
+
+> **Audience:** roadmap authors, phase reviewers, and CI gate writers
+> who need to know which artefact reads which, and whether two phases
+> can run concurrently without colliding.
+> **Generator:** `scripts/generate_ownership_matrix.py`
+> (run via `task generate-ownership-matrix`).
+> **Validator:** `task check-ownership-matrix` (fails if the JSON drifts
+> from a fresh regeneration).
+> **Companion contracts:** [`load-context-schema.md`](load-context-schema.md),
+> [`context-paths.md`](context-paths.md).
+
+This contract defines the **schema** of the file-ownership matrix: the
+machine-readable JSON at `docs/contracts/file-ownership-matrix.json` and
+the human-readable mirror at
+`agents/contexts/structural/file-ownership-matrix.md`. Both are
+regenerated from `.agent-src.uncompressed/` by the generator and locked
+by CI.
+
+**Status:** internal-locked (`stability: beta`). Schema bumps require a
+contract version increment plus a roadmap revision (per
+`road-to-structural-optimization.md` § 0.1).
+
+## Why the matrix exists
+
+`road-to-structural-optimization` Phase 0.1 (CRITICAL) is the DAG
+successor of Phase 0.6 (path conventions). Subsequent phases (1, 2A,
+2B, 3, 6) extract material into context files, slim rules, and reorder
+command surface. The matrix is the substrate that lets later phases
+ask three questions deterministically:
+
+1. **Which files does my edit reach transitively?** Answered by the
+   `READ_ONLY` edges plus their depth-2 closure.
+2. **Can Phase X and Phase Y land in either order?** Answered by
+   intersecting per-phase `WRITE` sets — empty intersection = safe.
+3. **Has the matrix drifted since the last green CI run?** Answered by
+   the `check-ownership-matrix` consistency gate.
+
+## Schema (v1)
+
+The JSON document is a single object:
+
+```json
+{
+  "version": 1,
+  "generated_by": "scripts/generate_ownership_matrix.py",
+  "source_of_truth": ".agent-src.uncompressed/",
+  "files": {
+    "<repo-root-relative path>": {
+      "kind": "rule | skill | command | context | persona",
+      "rule_type": "always | auto | manual | null",
+      "load_context": ["<path>", ...],
+      "load_context_eager": ["<path>", ...]
+    }
+  },
+  "edges": [
+    {
+      "source": "<path>",
+      "target": "<path>",
+      "type": "READ_ONLY | WRITE | BLOCKS_IF_CONCURRENT",
+      "via": "load_context | load_context_eager | load_context_transitive | body_link",
+      "depth": 1
+    }
+  ]
+}
+```
+
+**Edge types**
+
+| Type | Meaning | Populated in v1 |
+|---|---|:-:|
+| `READ_ONLY` | Source file reads target (frontmatter declaration or body markdown link). | ✅ |
+| `WRITE` | Source file owns target. Self-edge for every file (`source == target`). | ✅ |
+| `BLOCKS_IF_CONCURRENT` | Two phases would write the same file. Derived later from a phase manifest; reserved in v1. | ⏳ |
+
+**Edge `via` values**
+
+- `load_context` — frontmatter `load_context:` entry (lazy).
+- `load_context_eager` — frontmatter `load_context_eager:` entry.
+- `load_context_transitive` — depth-2 hop reached by following a target's own
+  `load_context*` declarations one level deeper.
+- `body_link` — markdown link in body to a path inside one of the
+  scanned roots.
+
+## Depth invariant (G2 — v3.1)
+
+The generator computes the transitive closure of `load_context` /
+`load_context_eager` edges **up to depth 2**. Any chain
+`R → A → B → C` where every hop is a `load_context*` edge **fails the
+build** with exit code 2. This duplicates the same nesting cap that
+Phase 0.2.4 will enforce in `scripts/check_always_budget.py` — two
+enforcement points, one invariant.
+
+## Regeneration policy
+
+| Trigger | What runs | What fails |
+|---|---|---|
+| `task generate-ownership-matrix` | Regenerates JSON + MD in place. | Depth-3 chain → exit 2. |
+| `task check-ownership-matrix` (CI) | Regenerates to memory, diffs against committed JSON. | Diff non-empty → exit 1. Depth-3 → exit 2. |
+| Pre-commit hook (Phase 2A — A1 fix) | Future: regenerate and diff on commits that touch contexts. | Same as `check-ownership-matrix`. |
+
+Any commit that adds, moves, or modifies a context, rule, skill, or
+command MUST regenerate the matrix in the same commit. CI is the
+backstop; the consistency gate fails if regeneration drifts.
+
+## Scope notes (v1)
+
+- **Greppable surface:** `rules/`, `skills/`, `commands/`, `contexts/`,
+  `personas/` under `.agent-src.uncompressed/`. Generated tool
+  projections (`.augment/`, `.claude/`, `.cursor/`, …) are intentionally
+  ignored — they are downstream of the source of truth.
+- **`skill:` frontmatter in rules** (named in roadmap 0.1.2) is reserved.
+  No rules currently declare it; the generator scans for it but emits
+  zero edges of that kind in v1.
+- **Body link parser** is conservative: it only recognises markdown
+  link targets ending in `.md` whose path resolves under one of the
+  scanned roots. Bare backtick-name references (e.g., `` `skill-quality` ``)
+  are **not** edges in v1; they are too ambiguous to attribute.
+- **Cycles** are not the matrix's concern — the existing
+  `lint_load_context.py` rejects them. The matrix generator follows
+  edges with a visited-set so a cycle, if one slipped through, cannot
+  loop forever; it would surface as a depth-3 abort.
+
+## Versioning
+
+`version: 1` is the initial lock. Schema-breaking changes (renaming a
+field, removing an edge type, changing semantics of an existing
+`via`) require a version bump and a roadmap revision. Additive changes
+(new `via` values, new optional file fields) MAY land at the current
+version with a `CHANGELOG.md` entry under `### Beta`.

package/docs/contracts/implement-ticket-flow.md

@@ -4,10 +4,9 @@ stability: beta
 
 # `/implement-ticket` — Flow Contract
 
-> Technical contracts for the delivery orchestrator shipped under
-> [`road-to-implement-ticket.md`](../../agents/roadmaps/road-to-implement-ticket.md).
-> This document is the stable reference; the roadmap tracks phased
-> delivery.
+> Technical contracts for the `/implement-ticket` delivery orchestrator.
+> This document is the stable reference for engine boundaries, state
+> schema, and replay protocol.
 >
 > - **Created:** 2026-04-22
 > - **Status:** Phase 1 shipped 2026-04-23 — `DeliveryState` +
@@ -133,9 +132,9 @@ against actual engine output rather than synthetic fixtures.
 Prompt envelopes (`input.kind="prompt"`) carry a free-form goal
 instead of a refined ticket. The `refine` step routes on shape
 (presence of `raw` key) and on the first pass emits an
-`@agent-directive: refine-prompt` halt — the agent runs the
-matching skill, which reconstructs `acceptance_criteria` +
-`assumptions`. On the rebound, `scoring/confidence.py` produces a
+`@agent-directive: refine-prompt` halt — the host agent is
+instructed to run the matching skill, which reconstructs
+`acceptance_criteria` + `assumptions`. On the rebound, `scoring/confidence.py` produces a
 frozen `ConfidenceScore(band, score, dimensions, reasons,
 ui_intent)` and the dispatcher branches on `band`:
 
@@ -616,8 +615,6 @@ are blocked by `freeze-guard.yml::manifest-integrity` at PR time.
 
 ## See also
 
-- [`agents/roadmaps/road-to-implement-ticket.md`](../../agents/roadmaps/road-to-implement-ticket.md)
-- [`agents/roadmaps/road-to-universal-execution-engine.md`](../../agents/roadmaps/road-to-universal-execution-engine.md)
 - `tests/golden/` — capture sandbox, recipes, and Capture Packs
 - [`../../tests/golden/harness.py`](../../tests/golden/harness.py) — Strict-Verb replay harness
 - [`../../.github/workflows/freeze-guard.yml`](../../.github/workflows/freeze-guard.yml) — manifest-integrity + live-replay gates

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -4,7 +4,6 @@ stability: beta
 
 # Linear AI — rules inclusion list
 
-> Phase 3 Step 1 deliverable for [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md).
 > Per-rule decision for the Linear AI rules digest. The digest is a
 > Markdown blob the user pastes into Linear's `Settings → Agents →
 > Additional guidance` (workspace / team / personal). The third-party

package/docs/contracts/linear-ai-three-layers.md

@@ -4,7 +4,6 @@ stability: beta
 
 # Linear AI — three-layer split rationale
 
-> Phase 3 Step 3 deliverable for [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md).
 > Per-rule routing is in [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md);
 > this file documents *why* the split is workspace / team / personal and
 > what belongs in each.
@@ -128,4 +127,3 @@ does not maintain `event4u/agent-config`.
 - Per-rule decision: [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md)
 - Builder script: [`scripts/build_linear_digest.py`](../../scripts/build_linear_digest.py)
 - Generated digests: `dist/linear/{workspace,team,personal}.md` (gitignored)
-- Roadmap: [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md) Phase 3

package/docs/contracts/load-context-budget-model.md

@@ -0,0 +1,258 @@
+---
+stability: beta
+---
+
+# `load_context:` Budget Accounting Model
+
+> **Audience:** maintainers of `type: "always"` rules and the budget
+> linter who need a single, deterministic answer to "how many chars
+> does this rule cost the always-budget?".
+> **Linter:** `scripts/check_always_budget.py`
+> (run via `task check-always-budget`).
+> **Companion:** [`load-context-schema.md`](load-context-schema.md) —
+> frontmatter contract for citing a context from a rule.
+> [`STABILITY.md § Budget contracts`](STABILITY.md#budget-contracts) —
+> the numeric caps this model enforces.
+
+This contract locks the **accounting model** by which a `type: "always"`
+rule's `load_context:` declarations contribute to the always-rule
+budget. It resolves the "is the rule its file size or its file size
+plus everything it loads?" ambiguity surfaced by Round-2 council on
+`road-to-structural-optimization` (Finding 7, CRITICAL).
+
+**Status:** internal-locked. Changes require a contract version bump
+and a roadmap revision (per
+`road-to-structural-optimization.md` § Definitions). The 2 % tolerance
+band on the retroactive test (G3 in v3.1) is the only legal way to
+adjust the model parameters without a roadmap revision; an overshoot
+above the band rejects the model and escalates to the council.
+
+## The locked model — Model (b) literal
+
+For any rule with frontmatter `type: "always"`:
+
+```
+EffectiveSize(rule) = RawSize(rule)
+                    + Σ RawSize(c) for every c in transitive_closure(rule.load_context*)
+```
+
+Where:
+
+- `load_context*` is the union of `load_context:` (lazy) **and**
+  `load_context_eager:` entries declared in frontmatter
+  (per [`load-context-schema.md`](load-context-schema.md)).
+- `transitive_closure` walks `load_context:` declarations on
+  context files **up to depth 2** — see § Nesting cap below.
+- `RawSize` is the byte size of the compressed file
+  (`.agent-src/...`), measured by `os.path.getsize()`. The
+  uncompressed source paths in frontmatter are mapped to their
+  compressed counterparts before sizing.
+- A context loaded by N always-rules counts **N times** (once per
+  loading rule). Rationale: the always-budget protects context-window
+  utilization at activation time; if rule A and rule B both fire on
+  the same turn, the agent pays both costs.
+
+### Why model (b) and not (a) or (c)
+
+| Model | Definition | Why rejected |
+|---|---|---|
+| (a) rule chars only | `EffectiveSize = RawSize(rule)` | Ignores the cost of declared contexts. Phase-2A obligation extraction would *appear* free, allowing unbounded context bloat. |
+| (b) literal *(this contract)* | `EffectiveSize = RawSize(rule) + Σ contexts` | Simplest invariant. Aligns with how the agent actually pays the cost when both rule and context fire on a turn. |
+| (c) shared-divisor | `EffectiveSize = RawSize(rule) + Σ (RawSize(c) / N_loaders)` | Tempting for shared `commit-mechanics`-style contexts but breaks the "what does each rule cost in isolation" question. Reserved as the **first refinement step** if the 2 % tolerance band is exceeded. |
+
+Council Round 3 converged A/A/A on the **separate-skills + shared-context**
+extraction pattern (Q1) and the **one-rule + three-contexts** consolidation
+(Q2); model (b) literal is the accounting that makes both patterns
+honest about their cost.
+
+## Load order (Q1) — file order in frontmatter
+
+Locked by Phase 1.2 of `road-to-context-layer-maturity` (council
+session `2026-05-03T17-56-21Z`, v2 lock).
+
+When a rule declares multiple `load_context:` and / or
+`load_context_eager:` entries, the agent processes them in the order
+they appear in the YAML list, top to bottom. `load_context_eager:`
+entries are concatenated into the active context in declaration
+order; `load_context:` entries are available for lazy retrieval in
+the same order, surfaced first-listed-first when the rule body cites
+them in prose.
+
+**Rejected alternatives:**
+
+- *Citation order in prose* — non-machine-readable; would force every
+  rule to embed a sort hint and the linter to parse rule body text.
+- *Priority field per entry* — adds frontmatter surface area without
+  observable benefit. The current rule with the most contexts
+  (`autonomous-execution`, 3 contexts) reads each in declaration
+  order without ambiguity.
+
+This contract treats list order as the canonical signal. Authors
+must order their `load_context:` entries from "load this first" to
+"load this last" so prose citations and frontmatter agree.
+
+## Per-rule context-count cap (Q2) — ≤ 3 contexts per rule
+
+Locked by Phase 1.3 of `road-to-context-layer-maturity` (council
+session `2026-05-03T17-56-21Z`, v2 lock). Enforced by
+`scripts/check_always_budget.py` as `MAX_CONTEXTS_PER_RULE = 3`.
+
+A rule's combined count of `load_context:` + `load_context_eager:`
+top-level entries must not exceed **3**. The cap is on *declared*
+entries (depth 1 from the rule), not transitive closure — depth-2
+context citations are governed by the depth-2 nesting cap below.
+
+**Rationale:**
+
+- Empirical max in the current rule set is 3
+  (`autonomous-execution`); the cap locks the ceiling without forcing
+  any rewrite.
+- A 4th declared context is the structural signal that the rule
+  should split (one rule, one obligation surface), not load more.
+- Cross-platform mechanical: a count check is O(N), no semantic
+  analysis, identical observable on Augment and Claude Code.
+
+The cap applies to **all rule types** (`always` and `auto`) — Q2 is
+a structural constraint on rule shape, not a budget concern.
+
+## Cross-rule sharing (Q3) — Model (b) literal locked
+
+Locked by Phase 1.4 of `road-to-context-layer-maturity` (decision
+3a). The accounting model in § The locked model above stands without
+shared-context discount.
+
+**Decision:** when context X is loaded by N rules, each rule pays
+the full `RawSize(X)` under Model (b). No `chars(X) / N` discount.
+
+**Rationale (3a over 3b):**
+
+- The linter is correct as-is — `RECOVERY_BAND_ENABLED` plus the
+  per-rule allowlist is already a working ratchet to drive total
+  utilization below 100 %.
+- 3b would require a linter rewrite plus a new failure-mode test
+  family (cross-rule attribution, divisor-stability invariants).
+  Phase 1.4a's 4-hour / 200-LOC feasibility cap was structured to
+  reject 3b on cost; with no current shared-context patterns
+  exceeding 1 loader per context (verified Phase 1.1 inventory), 3b
+  has no measurable upside.
+- Phase 4c (shared-context discount) becomes a no-op under 3a.
+  Phase 4 leverage shifts to 4a (demote), 4b (merge), and 4d
+  (hard-compress) — see `road-to-context-layer-maturity` Phase 4
+  inputs gate.
+
+**Reopener:** if a future inventory shows ≥ 3 shared-context loaders
+and total utilization re-enters the 95–100 % zone after Phase 4
+completes, run the Phase 1.4a feasibility spike and propose 3b via
+contract version bump.
+
+## Nesting cap — depth 2
+
+A rule's `load_context:` may cite a context (depth 1). A context may
+cite further contexts in its own frontmatter (depth 2). A depth-2
+context citing a third context (depth 3) **aborts the build**.
+
+Rationale: bounded recursion makes the linter terminate in O(N) and
+prevents accidental cycles. Council Round-2 finding 9 (HIGH).
+
+The check is enforced by `scripts/check_always_budget.py` as a
+separate exit-code-1 condition (independent of the budget caps), so
+that a depth violation surfaces with the violating chain, not as a
+budget-cap breach.
+
+## Known-breach allowlist (transitional)
+
+Phase 2A targets `non-destructive-by-default` and `scope-control`
+for slimming. Both rules currently exceed the **6,000-char per-rule
+cap** under model (b) literal — this is expected and intentional:
+Phase 0.2 lands the model and its measurement; Phase 2A brings the
+breaches under the cap.
+
+To keep CI green during the transition, the linter and the test
+suite carry an explicit `KNOWN_PER_RULE_BREACHES` allowlist with the
+**measured ceiling** for each entry. Each entry must:
+
+- Be referenced by the Phase 2A roadmap step that will retire it.
+- Have a documented expected-removal date or roadmap milestone.
+- Fail the build the moment the breach **grows** above the recorded
+  ceiling (regression guard).
+
+Phase 2A's success criterion (`budget delta ≥ −5 %`) is the trigger
+to remove entries from the allowlist. The allowlist must be **empty**
+before Phase 2A is marked complete.
+
+## Retroactive test result (Phase 0.2.3)
+
+PR #34's `autonomous-execution` split moved mechanics into three
+contexts under `contexts/execution/`. Re-measuring under model (b)
+literal:
+
+| Metric | Value | Cap | Utilization |
+|---|---:|---:|---:|
+| Total extended budget | 49,311 chars | 49,000 | **100.6 %** |
+| Top-3 extended | 22,248 chars | 24,500 | 90.8 % |
+| Per-rule breaches | 2 of 9 | 0 | `non-destructive-by-default` (7,887), `scope-control` (8,529) |
+
+The total sits **0.6 % over** the cap — within the 2 % tolerance band
+(G3) which permits parameter refinement before model rejection. Per
+the contract, the model is **accepted**; the per-rule breaches are
+recorded in the transitional allowlist for Phase 2A.
+
+`autonomous-execution` itself is `type: "auto"` and does not enter
+the always-budget. Its own extended size (rule 5,196 + three contexts
+8,453) = 13,649 chars is reported by the linter for Phase 2B
+diagnostics but does not gate the always-budget cap.
+
+## Linter contract
+
+`scripts/check_always_budget.py` enforces:
+
+1. `EffectiveSize` per always-rule against the per-rule cap (with
+   the transitional allowlist).
+2. Sum of `EffectiveSize` across all always-rules against the total
+   cap (warn at 80 %, fail at ≥ 90 % — unchanged from PR #34).
+3. Top-3 sum against the top-3 cap.
+4. Depth ≤ 2 on every `load_context:` chain reachable from an
+   always-rule.
+
+### Recovery band (Phase 2A → Phase 5 transitional)
+
+Locked by AI Council session `2026-05-03T12-02-42Z` (verdict A1)
+after Phase 2A was attempted and reverted: the 1:1 rule-to-context
+split was uneconomical under Model (b) literal because the
+frontmatter and citation-line tax on the new context file outweighed
+the chars removed from the rule. Reverting Phase 2A left the budget
+at 96.8 % — strictly better than the `main` baseline at 100.6 % but
+inside the 90–100 % gap zone the linter rejects.
+
+While `RECOVERY_BAND_ENABLED = True`, the linter accepts a branch in
+the gap zone iff:
+
+- `total_ext < baseline` (read from `.github/budget-baseline.txt`,
+  the chars at last-green `main`), AND
+- every per-rule cap holds (allowlisted entries unchanged), AND
+- top-3 cap holds, AND
+- depth-2 cap holds.
+
+A branch passing only the recovery band reports
+`⚠️  WARN (recovery band, baseline N)`. The band is a one-way ratchet:
+once a smaller branch lands on `main`, the baseline file must be
+updated to the new total in the same commit. Phase 5 of
+`road-to-structural-optimization` flips `RECOVERY_BAND_ENABLED` to
+`False` and removes both the band and the G3 tolerance — the gate
+collapses to `total < TOTAL_CAP` strict.
+
+Exit codes: 0 = pass (or warn, including recovery band), 1 = any cap
+breach or depth violation, 3 = internal error.
+
+## What this contract intentionally does **not** promise
+
+- **No claim about runtime cost.** The model treats every context
+  as if it were active when its rule fires. The agent may cache or
+  short-circuit lazy loads at runtime; the budget is the **upper
+  bound**, not the realised cost.
+- **No claim about `type: "auto"` rules.** Auto rules enter the
+  agent's context only when their description matches; they have
+  their own per-rule LOC targets in Phase 2B (not a global budget).
+- **No claim about commands or skills.** Commands and skills load
+  on user invocation. Their token cost is accounted by the
+  command-cluster and skill-family contracts, not here.

package/docs/contracts/load-context-schema.md

@@ -85,6 +85,26 @@ Single-rule contexts that don't fit one of the canonical topics live
 directly under `contexts/` (see `contexts/model-recommendations.md`,
 `contexts/skills-and-commands.md`).
 
+## Per-rule context-count cap (Q2)
+
+A rule's combined count of `load_context:` + `load_context_eager:`
+top-level entries MUST be ≤ **3**. Enforced by
+`scripts/check_always_budget.py` (`MAX_CONTEXTS_PER_RULE`); see
+[`load-context-budget-model.md § Per-rule context-count cap (Q2)`](load-context-budget-model.md#per-rule-context-count-cap-q2--3-contexts-per-rule)
+for the locking contract.
+
+A 4th context is the structural signal that the rule should split,
+not load more. Authors hitting the cap should extract a sibling rule
+with its own obligation surface, not stretch the existing one.
+
+## Load order
+
+Entries load in **frontmatter list order**, top-to-bottom. Author
+your list in "first read" order so prose citations and frontmatter
+agree. See
+[`load-context-budget-model.md § Load order (Q1)`](load-context-budget-model.md#load-order-q1--file-order-in-frontmatter)
+for the locking rationale.
+
 ## Combined char-budget guard
 
 `load_context_eager:` triggers a budget check:
@@ -93,9 +113,7 @@ directly under `contexts/` (see `contexts/model-recommendations.md`,
 chars(rule.md) + sum(chars(eager_target.md) for each entry) ≤ rule_cap
 ```
 
-`rule_cap` is the per-rule budget from
-[`road-to-rebalancing.md`](../../agents/roadmaps/road-to-rebalancing.md)
-§ Target architecture:
+`rule_cap` is the per-rule budget:
 
 - Always rule: 2,500
 - Auto rule: 4,000

package/docs/contracts/roadmap-complexity-standard.md

@@ -0,0 +1,137 @@
+---
+stability: beta
+---
+
+# Roadmap Complexity Standard
+
+> **Audience:** roadmap authors and reviewers in `agents/roadmaps/`.
+> **Linter:** `scripts/lint_roadmap_complexity.py` (run via
+> `task lint-roadmap-complexity`).
+> **Source:** Phase 5 of the `road-to-context-layer-maturity` work
+> (now archived); reviewer-flagged drift after the
+> structural-optimization roadmap proved that "heavy" is correct for
+> structural work but wrong for normal feature work.
+
+Roadmaps drift toward heavyweight whenever the previous one was
+heavyweight. This contract pins **two tiers**, names exemplars, and
+hard-fails the lint on tier mismatch.
+
+## Tiers
+
+### Lightweight (default)
+
+Almost every roadmap is lightweight. The shape:
+
+- **≤ 6 phases** total
+- **≤ 1 page per phase** (≈ 60 source lines including header + steps
+  + exit gate; the linter doesn't enforce per-phase line budgets, but
+  reviewers do)
+- **No nested council debates** inside the roadmap (no
+  `## Council Round 1`, `## Council Round 2`, `### Verdict` sections)
+- **No 178-step backlogs** — phases are delivery-shaped, not
+  task-shaped
+- **≤ 600 lines total** (frontmatter + body, blank lines counted)
+- Frontmatter declares `complexity: lightweight`
+
+**Exemplars:**
+
+- `road-to-context-layer-maturity.md` (archived) — six phases,
+  ~376 lines, no nested council; the seed roadmap that triggered this
+  standard. Self-tagged as `lightweight`.
+- `road-to-rule-hardening.md` (archived) — five phases, ~263 lines;
+  mechanized the rule layer; sibling of the seed, also lightweight.
+
+**Typical use:** feature work, follow-ups, bounded refactors,
+mechanization passes, telemetry plumbing.
+
+### Structural (rare)
+
+Triggered only when the work changes a contract layer or a budget
+invariant. The shape:
+
+- Multi-round council, locked decisions, file-ownership matrix,
+  gating contracts on phase boundaries
+- **> 600 lines** total (typical: 800 – 1500)
+- May include `## Council Round N` / `### Verdict` blocks, ADR
+  cross-links, decision matrices
+- Frontmatter declares `complexity: structural`
+
+**Exemplars:**
+
+- Archived `agents/roadmaps/_archived/road-to-structural-optimization.md`
+  (closed 2026-05-03 after 6 phases of council-driven budget work).
+  ~1.5k lines, multi-round council, file-ownership matrix.
+
+**Triggered by:** changes to a public contract surface in
+`docs/contracts/`, a budget invariant in
+[`load-context-budget-model.md`](load-context-budget-model.md), or a
+priority hierarchy in
+[`rule-priority-hierarchy.md`](rule-priority-hierarchy.md).
+**Requires:** explicit user opt-in on creation. The agent must not
+upgrade a lightweight roadmap to structural mid-flight without that
+opt-in.
+
+## Anti-game clause
+
+The trigger is **contract-layer change**, not line count alone. A
+heavy roadmap split into two lightweights to dodge the gate is a
+linter-defeat — reviewers flag it on PR review. Conversely, a
+roadmap that legitimately needs the structural shape but tries to
+hide as `lightweight` to skip council overhead is the same defeat in
+the other direction.
+
+## Frontmatter
+
+Every roadmap in `agents/roadmaps/` (including draft and archived
+ones) declares its tier:
+
+```yaml
+---
+complexity: lightweight
+---
+```
+
+or
+
+```yaml
+---
+complexity: structural
+status: draft
+---
+```
+
+Other frontmatter keys (`status:`, `owner:`, `target_release:`) are
+permitted alongside but not required by this contract.
+
+## Linter contract
+
+`scripts/lint_roadmap_complexity.py` (≤ 150 LOC, stdlib only)
+enforces the **measurable** subset of this standard:
+
+| Check | Lightweight | Structural |
+|---|---|---|
+| `complexity:` frontmatter declared | required | required |
+| Total line count | ≤ 600 | > 0 (no upper cap) |
+| `## Phase N` heading count | ≤ 6 | no cap |
+| `## Council Round N` / `### Verdict` blocks | forbidden | allowed |
+| Council session cross-links (`agents/sessions/.../council-…`) | warn | allowed |
+
+The linter runs on every roadmap file under `agents/roadmaps/` and
+exits non-zero on any violation. Hooked into `task ci` via
+`task lint-roadmap-complexity`.
+
+**Out of scope for the linter** (reviewer judgment only): step count,
+per-phase length, the contract-layer-change trigger for the
+structural tier.
+
+## Migration
+
+Phase 5.3 of `road-to-context-layer-maturity` applies the standard
+retroactively to all open roadmaps in `agents/roadmaps/`: each gets
+a `complexity:` tag based on the rules above. No content rewrites
+land in that step — only the tag.
+
+Roadmaps that exceed the lightweight cap but plausibly should be
+lightweight (e.g. they accumulated drift) are tagged `structural`
+for now and may be split or trimmed in a follow-up. The migration
+records existing reality, not aspirational reality.

package/docs/contracts/rule-interactions.md

@@ -104,4 +104,3 @@ junior (yields). For `complements`, ordering is documentary only.
 
 - [`docs/contracts/STABILITY.md`](STABILITY.md) — public-surface stability tiers.
 - [`docs/contracts/adr-chat-history-split.md`](adr-chat-history-split.md) — ADR pattern for major rule structural changes.
-- [`agents/roadmaps/archive/road-to-post-pr29-optimize.md`](../../agents/roadmaps/archive/road-to-post-pr29-optimize.md) § P2.2 — anchor for this matrix.

package/docs/contracts/rule-priority-hierarchy.md

@@ -64,7 +64,7 @@ which one's Iron Law gets the final say.
 | Situation | Bands that fire | Winner | Why |
 |---|---|---|---|
 | Standing autonomy + roadmap step says "merge to `main`" | 1, 7 | **1** | Hard Floor predates and outranks autonomy; surface the merge, ask. |
-| `/commit-in-chunks` on a diff that removes a directory | 1, 5 | **1** | Commit exception authorizes *commits*, not *bulk deletions*. Confirm diff this turn. |
+| `/commit:in-chunks` on a diff that removes a directory | 1, 5 | **1** | Commit exception authorizes *commits*, not *bulk deletions*. Confirm diff this turn. |
 | User asks "improve this" with no metric named | 4, 7 | **4** | Vague-request trigger fires before any autonomy decision; ask the one clarifying question. |
 | Editing `app/Auth/PasswordReset.php` mid-feature | 2, 7 | **2** | Security-sensitive surface stops the edit until threat-model is recorded. |
 | Agent about to claim "ready to merge" with no fresh test output | 5, 6 | **6** | Verification gate fires before the commit/push question is even valid. |