@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/scripts/archive_completed_roadmaps.ts

@@ -58,7 +58,11 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import { collect } from './update_roadmap_progress.js';
+import {
+    blocker_is_resolved,
+    collect,
+    parse_blockers,
+} from './update_roadmap_progress.js';
 import { guardedBaselineProblems, parseGuardedBaselines } from './guarded_baseline.js';
 
 import { isCliEntry } from './_cli_entry.js';
@@ -265,6 +269,80 @@ function _git_mv(root: string, src_rel: string, dst_rel: string, dry_run: boolea
     }
 }
 
+// ---------------------------------------------------------------------
+// The index/working-tree blocker divergence check (1b) + staging (1a)
+// ---------------------------------------------------------------------
+//
+// The open-blocker refusal below reads the file with `fs.readFileSync`, i.e.
+// the WORKING TREE. `git mv` then moves the INDEX ENTRY, which still carries
+// whatever was staged. When the two disagree the commit ships the index
+// content — content this gate never read.
+//
+// Measured, once, at full cost (2026-09-08): an edit removing a roadmap's
+// blocker was made and never staged; `git mv` moved the stale index entry; the
+// archived file shipped a blocker declared `Status: open` that had already been
+// relocated to an active roadmap. The same blocker was open in two files at
+// once, one of them archived, and it was caught by a human reading
+// `git status` rather than by any gate.
+//
+// The check is scoped to blocker id → status and deliberately NOT to whole-file
+// equality. An unstaged typo fix in a roadmap title has nothing to do with the
+// defect, and refusing archival for it trains `git add -A`, which destroys the
+// staging discipline this check depends on. AI council 2026-09-08, 2/2 present
+// (anthropic/claude-sonnet-4-5 + openai/gpt-4o), on that scoping specifically:
+// broad scoping is "user-hostile, trains developers to `git add -A`
+// reflexively, defeating staging discipline".
+
+/** Blocker id → status, as the archive-transition check compares them. */
+function _blockerStatuses(text: string): Map<string, string> {
+    const out = new Map<string, string>();
+    for (const b of parse_blockers(text)) {
+        out.set(b.id, blocker_is_resolved(b) ? 'resolved' : 'open');
+    }
+    return out;
+}
+
+/**
+ * `git show :<rel>` — the STAGED content of a path, or null when the path has
+ * no index entry.
+ *
+ * Null is the untracked / pre-first-commit case, which `_git_mv` already
+ * handles by falling back to a plain rename. There is no index entry to
+ * disagree with, so the divergence check has nothing to assert and says so by
+ * returning null rather than by guessing at an empty string — an empty staged
+ * file and an absent one differ, and only the second is legitimate here.
+ */
+function _indexContent(root: string, rel: string): string | null {
+    const cp = _run(['git', 'show', `:${rel}`], root);
+    return cp.returncode === 0 ? cp.stdout : null;
+}
+
+/**
+ * Human-readable disagreements between the staged and working-tree blocker
+ * maps of one path. Empty array = the two agree, or there is no index entry.
+ */
+function _blockerDivergence(root: string, rel: string, workTreeText: string): string[] {
+    const staged = _indexContent(root, rel);
+    if (staged === null) {
+        return [];
+    }
+    const wt = _blockerStatuses(workTreeText);
+    const idx = _blockerStatuses(staged);
+    const ids = [...new Set([...wt.keys(), ...idx.keys()])].sort();
+    const out: string[] = [];
+    for (const id of ids) {
+        const a = idx.get(id);
+        const b = wt.get(id);
+        if (a === b) {
+            continue;
+        }
+        out.push(
+            `blocker '${id}': staged=${a ?? 'absent'} vs working tree=${b ?? 'absent'}`,
+        );
+    }
+    return out;
+}
+
 /**
  * Repo-relative paths of files containing `needle`, by walking the filesystem.
  *
@@ -547,9 +625,8 @@ function archive_completed(
         // and invisible in a sweep that only reports what it moved; a MALFORMED
         // one on `[x]` would otherwise archive with an annotation claiming the
         // opposite. Both are named here instead.
-        const guarded = parseGuardedBaselines(
-            fs.readFileSync(path.join(roadmap_root, stats.rel), 'utf-8'),
-        );
+        const roadmapText = fs.readFileSync(path.join(roadmap_root, stats.rel), 'utf-8');
+        const guarded = parseGuardedBaselines(roadmapText);
         if (guarded.length > 0) {
             process.stderr.write(
                 `  ⚠️  ${stats.rel}: ${guarded.length} guarded-baseline step(s) — ` +
@@ -603,12 +680,37 @@ function archive_completed(
         if (changed_only && !(touched as Set<string>).has(old_rel)) {
             continue; // complete, but not this branch's work
         }
+        // The gate above validated the WORKING TREE; `git mv` ships the INDEX.
+        // When they disagree about a blocker, the validated content is not the
+        // content that gets committed — see § the index/working-tree blocker
+        // divergence check above for the measured failure.
+        const divergence = _blockerDivergence(root, old_rel, roadmapText);
+        if (divergence.length > 0) {
+            process.stderr.write(
+                `  ⚠️  ${stats.rel}: staged and working-tree blockers disagree ` +
+                    `(${divergence.length}) — not archived. \`git mv\` would commit ` +
+                    'the staged content, which this sweep never validated. Stage or ' +
+                    'discard the change, then re-run.\n',
+            );
+            for (const d of divergence) {
+                process.stderr.write(`        · ${d}\n`);
+            }
+            continue;
+        }
         const new_rel = `agents/roadmaps/archive/${stats.rel}`;
         const mv = _git_mv(root, old_rel, new_rel, dry_run);
         if (!mv.ok) {
             process.stderr.write(`  ⚠️  could not archive ${old_rel} (mv failed)\n`);
             continue;
         }
+        // `git mv` moved the index ENTRY, not the working-tree content. Staging
+        // the destination makes what gets committed identical to what the checks
+        // above read — the divergence check refuses a disagreement that exists
+        // BEFORE the move, and this closes one created by an edit between the
+        // move and the commit.
+        if (!dry_run && mv.tracked) {
+            _run(['git', 'add', '--', new_rel], root);
+        }
         const refs = _inbound_ref_rewrite(root, old_rel, new_rel, dry_run, mv.tracked);
         // Stage rewritten refs only in a tracked repo; an untracked consumer's
         // files are not in the index, so the filesystem rewrite is the whole job.

package/dist/agent-src/skills/activation-design/SKILL.md

@@ -37,7 +37,7 @@ diagnosis (route to `funnel-analysis`).
   vs \<base\>"* is a falsifiable claim with evidence. *"E feels
   important"* is not. Pick the event that survives the
   hypothesis test. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 9.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 9.
 - **Mental model 16 — Leading vs. lagging indicators.** Paid is
   lagging; the activation event must be leading — observable
   *before* the user has paid, and correlated with the lagging
@@ -54,7 +54,7 @@ diagnosis (route to `funnel-analysis`).
   segment's switch-event (the aha moment is the segment's job
   done once), and the **funnel-stage** slot for activation's
   position relative to signup and paid. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/adr-create/SKILL.md

@@ -90,7 +90,7 @@ needing an architecture supersession.
 ## Preconditions
 
 - An ADR directory exists. Two layouts coexist (see
-  [`docs/contracts/adr-layout.md`](../../../docs/contracts/adr-layout.md)):
+  [`docs/contracts/adr-layout.md`](../../docs/contracts/adr-layout.md)):
   - **Flat** — `docs/decisions/` (or `docs/adr/` alias): cross-cutting
     governance ADRs, 3-digit numbering (`ADR-NNN-<slug>.md`).
   - **Per-area** — `docs/adrs/<area>/`: sub-area ADRs, 4-digit
@@ -181,7 +181,7 @@ gets a logged correction block, never a silent edit.
 
 **Three descriptive axes ship on a new record** — `provenance`, `evidence`,
 `authority_basis`. Vocabulary, defaults and the mutation policy are owned by
-[`adr-layout § Provenance and evidence`](../../../docs/contracts/adr-layout.md);
+[`adr-layout § Provenance and evidence`](../../docs/contracts/adr-layout.md);
 `check_adr_frontmatter.ts` validates the shape. What the author has to get
 right while drafting:
 
@@ -207,7 +207,7 @@ right while drafting:
   comes from owning the purpose.
 - **A grade prices review burden, never authority.** Nothing about writing
   `E0` makes the record cheaper to overturn *by whom* — see
-  [`adr-layout § The reopen record`](../../../docs/contracts/adr-layout.md).
+  [`adr-layout § The reopen record`](../../docs/contracts/adr-layout.md).
 
 **Flat-surface template** (`docs/decisions/ADR-NNN-<slug>.md`):
 
@@ -287,7 +287,7 @@ authority_basis: evidence | owner_intent      # optional; absent → evidence
 ```
 
 The frontmatter block is the same shape as the flat surface — the contract
-says so ([`adr-layout § Frontmatter`](../../../docs/contracts/adr-layout.md):
+says so ([`adr-layout § Frontmatter`](../../docs/contracts/adr-layout.md):
 "identical across both surfaces"), and `audit_adr_coverage.ts`'s parser reads
 it when present. The quote-style header stays as the human-readable banner,
 and every existing per-area record now carries frontmatter beside it, so their
@@ -359,7 +359,7 @@ completeness check — not on every ADR by default.
   alone does not stop someone quoting the reversed sentence.
 - **Who may reopen it is recorded, not assumed** — `reopen_policy` /
   `protected_dimensions`, both optional, absent meaning `unclassified`
-  ([`adr-layout § Reopen authority`](../../../docs/contracts/adr-layout.md)).
+  ([`adr-layout § Reopen authority`](../../docs/contracts/adr-layout.md)).
   Reach for `owner` only when EVERY future transition is genuinely reserved;
   `directional` is the normal answer, and no answer is a fine answer.
 

package/dist/agent-src/skills/ai-council/SKILL.md

@@ -136,7 +136,7 @@ explicit absolute path for tests / power users — still not a project search.
 ## When NOT to invoke — necessity self-check
 
 The Phase 6 necessity classifier (see
-[`ai-council-config § Necessity classifier`](../../../docs/contracts/ai-council-config.md))
+[`ai-council-config § Necessity classifier`](../../docs/contracts/ai-council-config.md))
 runs as a pre-flight gate inside the CLI and skips the council when
 the prompt looks like routine work. Route around it BEFORE the gate
 fires so the user never pays the classifier-pause cost on a request

package/dist/agent-src/skills/ai-council/references/advanced-modes.md

@@ -289,7 +289,7 @@ fast-path only activates when:
 Default route for `low_impact` is **`agent`** — nothing reaches the
 council without an explicit two-knob opt-in (flip the class to
 `council` *and* mark at least one member `participate_low_impact: true`).
-See [`ai-council-config § Low-impact council opt-in`](../../../../../docs/contracts/ai-council-config.md#low-impact-council-opt-in)
+See [`ai-council-config § Low-impact council opt-in`](../../../docs/contracts/ai-council-config.md#low-impact-council-opt-in)
 for the worked YAML example, validation behaviour, and unavailable-marker
 contract.
 

package/dist/agent-src/skills/blade-ui/SKILL.md

@@ -141,7 +141,7 @@ When `DESIGN.md` declares `## Taste Dials`, honour them: Variance → layout-fam
 ## Anti-slop
 
 Before shipping a Blade view, pull
-[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
+[`docs/guidelines/design-antipatterns.md`](../../guidelines/design-antipatterns.md)
 and scan Visual / Typography / Layout — the Blade markup is where side-stripe
 accents (V1), icon-tile feature cards (T3), and the centered-hero + 3-column
 template (L1/L2) concretely land. Stack-specific Tailwind class/hex bans live in

package/dist/agent-src/skills/blast-radius-analyzer/SKILL.md

@@ -88,7 +88,7 @@ For every dependency, mark:
 
 ### 5. Consult engineering memory
 
-Via [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
+Via [`memory-access`](../../guidelines/agent-infra/memory-access.md) call
 `retrieve(types=["ownership"],
 keys=<changed paths + changed symbol>, limit=5)`. Surface:
 

package/dist/agent-src/skills/brand-to-tokens/SKILL.md

@@ -27,7 +27,28 @@ execution:
 > hands it to the [`design-tokens`](../design-tokens/SKILL.md) toolchain to emit
 > CSS vars + Tailwind. The same `.tokens.json` is the export that pack-ai-image
 > brand-asset generation and the greenfield scaffold seed consume (B → A;
-> contract: [`brand-token-consumption`](../../../docs/contracts/brand-token-consumption.md)).
+> contract: [`brand-token-consumption`](../../docs/contracts/brand-token-consumption.md)).
+
+## Known contradiction — the filename this skill authors is not the one the resolver reads
+
+**Recorded, not resolved.** This skill's prose says to author `.tokens.json`,
+and the only resolver in the tree reads `tokens.json` — `BRAND_TOKEN_PATHS`
+searches `tokens.json`, `assets/tokens.json`, `resources/tokens.json` and
+`agents/settings/brand/tokens.json` <!-- ref-ignore -->, none of them
+dot-prefixed. A consumer
+following this skill literally therefore produces a file nothing loads.
+
+The authoring name is a consumer-visible decision and is deliberately not
+changed here. What closes the gap in the meantime is
+`agent-config brand:status`, which reports which of the four paths holds a file
+— and separately flags a dot-prefixed `.tokens.json`, which is exactly the file
+a reader of this skill would plausibly have created.
+
+Moved here from [`brand-source-of-truth`](../../rules/brand-source-of-truth.md)
+on 2026-09-09: it is a note about this skill, and its 6 lines in a standing rule
+were paid for on every subagent spawn. The substitution funded that rule's
+artifact-versus-brand pointer, per the council verdict on
+`blocker: standing-payload-headroom`.
 
 ## When to use
 
@@ -98,9 +119,9 @@ execution:
 
 ## See also
 
-- [`design-canon.md`](../../../docs/guidelines/design-canon.md) § Colour references — culturally-situated palettes + a11y-contrast grounding when deriving brand colour tokens.
+- [`design-canon.md`](../../guidelines/design-canon.md) § Colour references — culturally-situated palettes + a11y-contrast grounding when deriving brand colour tokens.
 - [`brand-identity`](../brand-identity/SKILL.md) — supplies the constraint set this skill derives tokens from.
 - [`design-tokens`](../design-tokens/SKILL.md) — the DTCG toolchain that emits CSS/Tailwind from `.tokens.json`.
 - [`typography-system`](../typography-system/SKILL.md) — brand-aware stage-2 supplies the type tokens.
-- [`brand-token-consumption`](../../../docs/contracts/brand-token-consumption.md) — the read contract pack-ai-image and greenfield scaffold consume.
+- [`brand-token-consumption`](../../docs/contracts/brand-token-consumption.md) — the read contract pack-ai-image and greenfield scaffold consume.
 - [`brand-consistency`](../../rules/brand-consistency.md) — validates emitted artifacts against this token source of truth.

package/dist/agent-src/skills/bug-analyzer/SKILL.md

@@ -96,7 +96,7 @@ Gather all available evidence before forming any hypothesis:
 - Read each file in the call chain to understand the data flow.
 - Check existing context docs (`agents/settings/contexts/`) for the affected area.
 - **Consult engineering memory.** Via
-  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md) call
+  [`memory-access`](../../guidelines/agent-infra/memory-access.md) call
   `retrieve(types=["historical-patterns", "incident-learnings"],
   keys=[<error class>, <affected file paths>], limit=3)`. A prior
   matching pattern or incident is the single most reliable accelerator

package/dist/agent-src/skills/build-buy-partner/SKILL.md

@@ -27,7 +27,7 @@ Do NOT use for vendor selection within a "buy" decision (different skill), marke
 
 ## Cognition cluster
 
-- **Mental model 28 — Inversion.** *"What would force us to undo this choice in 18 months?"* Inversion surfaces the dependency-risk and integration-cost that the forward case understates. See [`mental-models.md`](../../../docs/contracts/mental-models.md) § 28.
+- **Mental model 28 — Inversion.** *"What would force us to undo this choice in 18 months?"* Inversion surfaces the dependency-risk and integration-cost that the forward case understates. See [`mental-models.md`](../../docs/contracts/mental-models.md) § 28.
 - **Mental model 21 — Second-order thinking.** Each option chains: build → ongoing maintenance + opportunity cost; buy → integration + lock-in; partner → dependency + boundary management. Single-order *"build is cheaper"* fails on the second-order. See `mental-models.md` § 21.
 - **Mental model 26 — Optionality.** Read each option by which choices it preserves (switch costs, re-build optionality, re-negotiation power) vs forecloses. The option with bounded foreclosure usually wins. See `mental-models.md` § 26.
 - **Context-spine — org-stage + product + customer-segment.** Read **org-stage** for capacity (pre-seed should buy almost everything non-core; growth-stage can build deeper). Read **product** for whether the capability is core-differentiation (build) or commodity (buy). Read **customer-segment** for whether enterprise-segment buyers require a build-it-yourself story.

package/dist/agent-src/skills/churn-prevention/SKILL.md

@@ -34,7 +34,7 @@ to `retention-loops`).
 - **Mental model 30 — Inversion.** Do not ask *"how do we keep this
   account?"* — ask *"name the reason this account will leave."* The
   inversion forces a cause; the cause picks the move. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 30.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 30.
 - **Mental model 16 — Leading vs. lagging indicators.** Cancellation
   is lagging; usage-decay, relationship-decay, and fit-mismatch
   signals are leading. A health score built on lagging signals can
@@ -50,7 +50,7 @@ to `retention-loops`).
   the **customer-segment** slot for the segment's switch-event
   patterns — fit-churn shows up early in segments whose switch
   event differs from the ICP. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/code-intelligence/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: code-intelligence
-description: "Route codebase-structure questions (who calls X, where is this used, what imports, change-impact) to an existing code-graph first: cheaper, never more precise; grep stays routine. Also 'call graph'."
+description: "Route codebase-structure questions (who calls X, where used, change-impact) to an existing code-graph first: impact, tests-for, dead cheaper, never more precise; grep routine. Also 'call graph'."
 domain: engineering
 workspaces:
   - engineering
@@ -204,6 +204,62 @@ refresh` first, or use grep and say so. This is a freshness obligation, not an
 ordering claim; the rule's query-first ordering still governs which source to
 reach for.
 
+## The four gate verbs — a diff, not a symbol (2026-09-08)
+
+`query` / `affected` / `path` / `explain` answer a question about a SYMBOL.
+Four more answer a question about a DIFF, and they are documented here rather
+than in § Procedure for a mechanical reason worth stating: step 4.3 of
+`road-to-a-graph-that-is-shipped` verifies that this file's line 164 — the
+**No class is graph-first** sentence — is unchanged, and inserting anything
+above it moves that line. So the ordering claim K5 protects stays byte-fixed
+and the new material sits below it.
+
+Each of the four walks only edges whose resolution mechanism is a stated fact
+(never a repo-wide same-name guess, never an untyped receiver), and each prints
+the mechanisms it accepted, the mechanisms it refused, and the graph's
+staleness — so a narrow answer is distinguishable from a decoupled one:
+
+- `agent-config code-graph impact --diff <rev>` — callers, dependents and test
+  files reachable from the changed symbols, plus the producing edges and a
+  minimal read set.
+- `agent-config code-graph tests-for <symbol>` — the test files that import it.
+  An empty list is a finding, not an error.
+- `agent-config code-graph untested --diff <rev>` — changed symbols that no test
+  file imports.
+- `agent-config code-graph dead [--entry-points F | --accept-missing-exports]` —
+  symbols with no accepted reference that no declared entry point names. It
+  **refuses** rather than answering while an entry-point source cannot be read:
+  this engine records no exportedness, so without a supplied list an
+  exported-but-unimported symbol is indistinguishable from a dead one, and a
+  confident false "dead" invites a deletion the graph cannot justify. Nothing it
+  lists is a deletion recommendation.
+
+These answers reach an agent over MCP without shelling out, and the mapping is
+**not** one tool per verb — corrected after an independent review found this
+paragraph claiming "the same five answers" directly after a list of four:
+
+| MCP tool | answers |
+|---|---|
+| `graph_impact` | `impact --diff`, **and** `untested --diff` via `untested_only: true` |
+| `graph_tests_for` | `tests-for` |
+| `graph_dead` | `dead` |
+| `graph_query` | `query` |
+| `graph_path` | `path` |
+
+`untested` has no tool of its own; it is a flag on `graph_impact`, because the
+two answer the same question over the same diff and a sixth tool would have cost
+standing context for a boolean. `graph_impact` is the only one that is not
+read-only — it runs `git diff --name-only` to resolve its rev — and
+`graph_dead`'s refusal arrives as `status: "refused"`, never as `status: "ok"`
+with an empty list.
+
+**No ordering claim is added here, and no measurement claim either.** These
+verbs are cheaper than reconstructing the same relationship by hand — that is a
+claim about the ALTERNATIVE being a manual reconstruction, not about grep.
+Nothing on this page says they beat grep, none of the four appears in the v2
+benchmark corpus (which measures `callers`, `transitive-impact`, `path-between`
+and `references`), and § Measured twice still governs that question.
+
 ## Do NOT
 
 - Do NOT rebuild a **fresh** consumer-shipped index — query it (interop

package/dist/agent-src/skills/code-refactoring/SKILL.md

@@ -34,7 +34,7 @@ Do NOT use when:
    well (`switch` / `match` / if-chains over it, lookup tables keyed by it,
    validators, serializers, schemas, fixtures, translation keys) and classify each
    as exhaustive, deliberate fallback, or missing case. Procedure:
-   [`downstream-changes-mechanics`](../../../docs/guidelines/agent-infra/downstream-changes-mechanics.md).
+   [`downstream-changes-mechanics`](../../guidelines/agent-infra/downstream-changes-mechanics.md).
 4. **Map the impact** — create a list of all files that will need changes.
 5. **Decide the verdict, if the refactor is a de-duplication** — see the
    safe-abstraction gate below. An extraction with no recorded verdict is a
@@ -66,13 +66,13 @@ read identically can encode different assumptions, and merging them changes
 behaviour silently.
 
 The class names and the full verdict list are in
-[`redundancy-taxonomy`](../../../docs/guidelines/redundancy-taxonomy.md).
+[`redundancy-taxonomy`](../../guidelines/redundancy-taxonomy.md).
 
 When the refactor goes the other way and **creates** a new unit, the reuse
 question comes first: does an existing class or component already cover this, and
 what does composing or extending it cost against a new one? Thresholds per
 artifact class:
-[`component-oriented-and-oop-development`](../../../docs/guidelines/component-oriented-and-oop-development.md).
+[`component-oriented-and-oop-development`](../../guidelines/component-oriented-and-oop-development.md).
 
 ## Procedure: Refactor code
 

package/dist/agent-src/skills/code-review/SKILL.md

@@ -52,7 +52,7 @@ principle, not a decision, and it has no answer for the case where two copies
 should stay. Replace it with a verdict.
 
 Classify the finding against
-[`redundancy-taxonomy`](../../../docs/guidelines/redundancy-taxonomy.md) —
+[`redundancy-taxonomy`](../../guidelines/redundancy-taxonomy.md) —
 implementation, knowledge, or representation — and record one verdict from that
 document's list. `keep-duplicated` and `de-abstract` are successful outcomes; a
 finding with no recorded verdict stays open. Knowledge, policy, contract and
@@ -85,7 +85,7 @@ consumers and their status — every `switch` / `match` / if-chain over the type
 every lookup table keyed by it, every validator, serializer, schema, fixture and
 translation key. A `default` branch that silently absorbs the new member is a
 missing case, not a handled one. Procedure:
-[`downstream-changes-mechanics`](../../../docs/guidelines/agent-infra/downstream-changes-mechanics.md).
+[`downstream-changes-mechanics`](../../guidelines/agent-infra/downstream-changes-mechanics.md).
 
 **A shared behaviour moved and its siblings did not.** A defect fixed in one
 place is presumed to recur until searched: name the exact wrong construct, grep
@@ -100,7 +100,7 @@ changing one, the question is whether it needed to exist: what was searched,
 what was found, and why composing or extending the incumbent was rejected. An
 answer, not a ceremony — and the thresholds for when repetition actually earns
 an abstraction are in
-[`component-oriented-and-oop-development`](../../../docs/guidelines/component-oriented-and-oop-development.md).
+[`component-oriented-and-oop-development`](../../guidelines/component-oriented-and-oop-development.md).
 
 ## Change-type routing — load only the checklist the diff needs
 

package/dist/agent-src/skills/command-writing/SKILL.md

@@ -39,7 +39,7 @@ author as a skill and add a thin command that delegates to it.
 
 **A command must EARN a top-level slot.** Only three justifications qualify:
 **flow-entry**, **state-query**, or **product-surface** — everything else is a
-skill. Check before authoring: [`command-clusters` § Command justification](../../../docs/contracts/command-clusters.md#command-justification--a-command-must-earn-a-top-level-slot)
+skill. Check before authoring: [`command-clusters` § Command justification](../../docs/contracts/command-clusters.md#command-justification--a-command-must-earn-a-top-level-slot)
 ([ADR-048](../../../docs/decisions/ADR-048-command-justification-rule.md)).
 
 **Categorize at creation (checklist).** When you author a NEW top-level command,
@@ -56,7 +56,7 @@ is `flow-entry | state-query | product-surface`:
 
 Sub-commands (`council:debate`) inherit the parent cluster's category — leave
 `category:` off them. Why optional + not yet a blocking lint, and what triggers
-the upgrade: [`command-category-governance`](../../../docs/contracts/command-category-governance.md).
+the upgrade: [`command-category-governance`](../../docs/contracts/command-category-governance.md).
 
 ## Commands ARE Claude skills (projection reality)
 
@@ -346,4 +346,4 @@ Workflow sequencing, preconditions, ID/output provenance ("copy ids verbatim,
 never from memory"), a mandatory "why" intent field, and turn-end contracts
 belong INSIDE this artifact's description/frontmatter — where they fire at the
 decision point — not in always-on prose. See
-[`tool-description-as-policy`](../../../docs/guidelines/agent-infra/tool-description-as-policy.md).
+[`tool-description-as-policy`](../../guidelines/agent-infra/tool-description-as-policy.md).

package/dist/agent-src/skills/comp-banding/SKILL.md

@@ -28,7 +28,7 @@ Do NOT use as a payroll / equity-administration substitute (this skill produces
 
 ## Cognition cluster
 
-- **Mental model 1 — First principles.** Strip every comp question to: *what behavior are we paying for, over what horizon, with what risk-bearing?* Cash pays for present effort; equity pays for future co-built value with risk; bonus pays for outcome-linked behavior. Mixing the levers without first-principles intent produces confusion. See [`mental-models.md`](../../../docs/contracts/mental-models.md) § 1.
+- **Mental model 1 — First principles.** Strip every comp question to: *what behavior are we paying for, over what horizon, with what risk-bearing?* Cash pays for present effort; equity pays for future co-built value with risk; bonus pays for outcome-linked behavior. Mixing the levers without first-principles intent produces confusion. See [`mental-models.md`](../../docs/contracts/mental-models.md) § 1.
 - **Mental model 28 — Inversion.** *"What comp shape would force our best people to leave?"* Inversion surfaces the load-bearing risks (condensation at senior levels, equity refresh gaps, geo arbitrage that punishes loyalty).
 - **Mental model 26 — Optionality.** Each comp lever preserves or forecloses future options. Above-band offers preserve hire optionality but foreclose internal-equity optionality. Equity-heavy mix preserves cash runway but forecloses people who need liquidity. Read every move as an optionality trade.
 - **Mental model 21 — Second-order thinking.** A raise to one person ripples (perceived parity, retention pressure on peers, expectation-setting for next cycle). A band shift ripples (new-hire offers anchor higher, internal expectations re-anchor). Comp moves rarely stay isolated.

package/dist/agent-src/skills/competitive-moat-analysis/SKILL.md

@@ -27,7 +27,7 @@ Do NOT use for narrative / messaging surface (route to Wing-3 `positioning-strat
 
 ## Cognition cluster
 
-- **Mental model 18 — Where to play, where not to play.** A moat is read as much from *what we refuse to do* as from what we do. Trying to win everywhere = winning nowhere. See [`mental-models.md`](../../../docs/contracts/mental-models.md) § 18.
+- **Mental model 18 — Where to play, where not to play.** A moat is read as much from *what we refuse to do* as from what we do. Trying to win everywhere = winning nowhere. See [`mental-models.md`](../../docs/contracts/mental-models.md) § 18.
 - **Mental model 28 — Inversion.** *"What would force a customer to leave us for an incumbent?"* The inversion answer surfaces the load-bearing moat assumption. If the answer is *"nothing"*, the moat is wishful; if the answer is concrete, that's the real fragility. See `mental-models.md` § 28.
 - **Mental model 21 — Second-order thinking.** Moats compound or decay; *"feature parity today"* says nothing about *"feature parity in 18 months"*. Read each moat by its compounding rate, not its current state. See `mental-models.md` § 21.
 - **Context-spine — customer-segment + product + org-stage.** Read **customer-segment** for which incumbent matters in which segment (the enterprise incumbent is rarely the SMB incumbent). Read **product** for which moats are real vs roadmap. Read **org-stage** for moat realism (pre-revenue moats are claims; growth-stage moats are evidence).

package/dist/agent-src/skills/competitive-positioning/SKILL.md

@@ -35,7 +35,7 @@ DCF-style valuation work (route to `dcf-modeling`).
   outcome each package promises its user, not the feature lists. Two
   packages with overlapping features can promise different outcomes
   and therefore are not direct competitors. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 1.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 1.
 - **Mental model 24 — Optionality.** A pattern that costs little to
   adopt and preserves exit value beats a "better" pattern that locks
   the package in. Score adoption cost AND exit cost on every row. See
@@ -46,7 +46,7 @@ DCF-style valuation work (route to `dcf-modeling`).
 - **Product context-spine slot.** Read the **product** slot for
   segment / focal job / non-goals before picking axes; the comparison
   is only legitimate inside our own scope. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/complexity-first-planning/SKILL.md

@@ -44,7 +44,7 @@ unknown to resolve), or when the user has already fixed the sequence.
 
 1. **Inspect and name the unknowns.** Read the affected components first
    (start from the **repo** slot of the
-   [context-spine](../../../docs/contracts/context-spine.md) when present),
+   [context-spine](../../docs/contracts/context-spine.md) when present),
    then list which carry real uncertainty (technical feasibility, an
    unverified integration, an ambiguous requirement) — analyze the existing
    system before planning any change.

package/dist/agent-src/skills/condense-memory/SKILL.md

@@ -125,5 +125,5 @@ A future `telegraph-v2.md` will tabulate the realised input-token saving against
 - [`src/scripts/validate_safe_paths.ts`](../../../src/scripts/validate_safe_paths.ts) — Phase 0 gate; ported from upstream Telegraph `63a91ec`.
 - [`src/scripts/condense_memory.ts`](../../../src/scripts/condense_memory.ts) — implementation.
 - [`tests/scripts/condense_memory.test.ts`](../../../tests/scripts/condense_memory.test.ts) — regression locks for each carve-out + idempotency + denylist.
-- [`docs/contracts/condensation-default-kill-criterion.md`](../../../docs/contracts/condensation-default-kill-criterion.md) — v1 verdict (output-side; informs but does not gate this skill).
+- [`docs/contracts/condensation-default-kill-criterion.md`](../../docs/contracts/condensation-default-kill-criterion.md) — v1 verdict (output-side; informs but does not gate this skill).
 - [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) — caps the consumer-shipped `templates/AGENTS.md`; this skill is one tool to land under the cap.

package/dist/agent-src/skills/content-funnel-design/SKILL.md

@@ -37,7 +37,7 @@ draft the asset itself (downstream of this skill).
   funnel design is the discipline of placing the heaviest content
   investment at the structural leverage point, not the parameter
   one. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 14.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 14.
 - **Mental model 6 — Theory of constraints.** The slow funnel stage
   caps the whole pipeline. Adding content elsewhere does not loosen
   the constraint. See `mental-models.md` § 6.
@@ -52,7 +52,7 @@ draft the asset itself (downstream of this skill).
   the asset, **customer-segment** for whose questions the asset
   answers, and **product** for the proofs the asset can actually
   back. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/contracts-cognition/SKILL.md

@@ -29,7 +29,7 @@ Do NOT use as a substitute for actual legal counsel (this skill produces the *no
 
 ## Cognition cluster
 
-- **Mental model 28 — Inversion.** *"What would force us to invoke this clause? What would force the counterparty to invoke it?"* Inversion surfaces which clauses are dormant boilerplate vs which are loaded triggers. See [`mental-models.md`](../../../docs/contracts/mental-models.md) § 28.
+- **Mental model 28 — Inversion.** *"What would force us to invoke this clause? What would force the counterparty to invoke it?"* Inversion surfaces which clauses are dormant boilerplate vs which are loaded triggers. See [`mental-models.md`](../../docs/contracts/mental-models.md) § 28.
 - **Mental model 21 — Second-order thinking.** Each clause has a second-order shape: indemnity caps interact with insurance coverage; SLAs interact with operating-cost; auto-renewal interacts with switching cost. Reading clauses in isolation misses the load-bearing combinations. See `mental-models.md` § 21.
 - **Mental model 26 — Optionality.** Each clause either preserves or forecloses future choices (terminate-for-convenience preserves; auto-renewal forecloses; exclusivity forecloses; MFN forecloses). The cost of a clause is the optionality it removes. See `mental-models.md` § 26.
 - **Context-spine — regulatory-regime + customer-segment + org-stage.** Read **regulatory-regime** (J1) for floor-bound clauses (GDPR DPA terms, HIPAA BAA, SOC 2 audit). Read **customer-segment** for risk sizing (enterprise SLA terms ≠ SMB SLA terms). Read **org-stage** for what's affordable (early-stage = avoid uncapped indemnities; growth = can absorb tighter SLAs).

package/dist/agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -130,7 +130,7 @@ both. Instead, reference with a table:
 | What | Where |
 |---|---|
 | PHP coding rules | `.augment/rules/php-coding.md` |
-| Controller guidelines | `../../../docs/guidelines/php/controllers.md` |
+| Controller guidelines | `../../guidelines/php/controllers.md` |
 ```
 
 ## Line Budget Enforcement
@@ -192,7 +192,7 @@ broken. When optimizing, **keep that section intact** — never delete
 it as "redundant" and never trim its bullets. The patterns it covers:
 
 - Relative cross-references inside `.augment/` rules / skills
-  (`../docs/guidelines/foo.md`, `../contexts/bar.md`) — paths resolve
+  (`../../guidelines/foo.md`, `../contexts/bar.md`) — paths resolve
   from the file's delivered location, not from the symlink in
   `.claude/rules/` etc. (per `road-to-path-fixes.md` Strategy A).
 - `path_prefix:` triggers containing `src/` —

package/dist/agent-src/skills/corpus-grounding/SKILL.md

@@ -63,7 +63,7 @@ frontend-hardcoded axis moved into the manifest. Full license obligations:
 ### Invocation (consumer runtime)
 
 Scripts resolve all paths **skill-relative** (per
-[`docs/contracts/skill-bundled-assets.md`](../../../docs/contracts/skill-bundled-assets.md))
+[`docs/contracts/skill-bundled-assets.md`](../../docs/contracts/skill-bundled-assets.md))
 — they work from any cwd:
 
 ```bash
@@ -226,5 +226,5 @@ the skill shipping the manifest, and its containment is `resolve_data_path`.
   (frontend corpus + manifest).
 - [ADR-061](../../../docs/decisions/ADR-061-corpus-grounding-layer.md) —
   architecture, qualification rubric, fork resolutions.
-- [`docs/contracts/skill-bundled-assets.md`](../../../docs/contracts/skill-bundled-assets.md)
+- [`docs/contracts/skill-bundled-assets.md`](../../docs/contracts/skill-bundled-assets.md)
   — how bundled `scripts/` + `data/` reach consumer runtime.

package/dist/agent-src/skills/customer-research/SKILL.md

@@ -33,7 +33,7 @@ this skill is about depth-5-to-10 interviews, not statistics.
 
 - **Mental model 2 — Jobs-to-be-Done.** Frames every question against
   the **switch event**: what caused the user to fire the previous
-  solution? See [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 2.
+  solution? See [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 2.
 - **Mental model 3 — Pareto principle.** A research week that
   produces 12 distinct insights is usually re-discovering the same
   three. See `mental-models.md` § 3.
@@ -43,7 +43,7 @@ this skill is about depth-5-to-10 interviews, not statistics.
 ### Step 0: Frame the job
 
 1. Write one sentence: *"Users hire \<thing\> to make progress in \<situation\>, when motivated by \<pressure\>, expecting \<outcome\>."* If you cannot finish the sentence, the discovery slice is not yet shaped — stop and route to `po-discovery`.
-2. Read the **product** slot of the [context-spine](../../../docs/contracts/context-spine.md) (if the consumer project has filled it) for bounded scope, and the **team** slot for the senior PO / researcher handoff target. Skip if absent — note in the brief.
+2. Read the **product** slot of the [context-spine](../../docs/contracts/context-spine.md) (if the consumer project has filled it) for bounded scope, and the **team** slot for the senior PO / researcher handoff target. Skip if absent — note in the brief.
 3. Identify **one** competing solution the user might fire. Multiple competitors per session blurs the switch event.
 
 ### Step 1: Recruit the right 5–8