@event4u/agent-config 14.12.0 → 14.14.0

package/docs/guidelines/php/database.md

@@ -7,34 +7,77 @@
 
 ## Indexing
 
+Three separate things get conflated here, and keeping them apart is what makes
+the rest of this section decidable:
+
+1. **Declaring an integrity constraint** — a uniqueness or foreign-key
+   constraint. This is a correctness decision about the data model.
+2. **Indexing the referencing column** — the child side of a foreign key, which
+   is what makes the lookup and the constraint check fast.
+3. **Adding an optional query-performance index** — everything else.
+
+The row-count guidance below governs **(3) only**. It has never governed (1),
+and it must not be read as governing (2).
+
 ### When to add indexes
 
 - Columns in `WHERE` clauses
 - Columns in `JOIN` conditions
 - Columns in `ORDER BY` (especially with pagination)
 - Foreign key columns (Laravel adds with `foreignId()`)
+- Columns carrying a declared uniqueness constraint
 
 ### When NOT to add indexes
 
+These apply to **optional performance indexes** — category (3) above:
+
 - Boolean columns with low selectivity (99% same value)
-- Small tables (< 1000 rows)
+- Tables that are both small (< 1000 rows) **and rarely accessed**
 - Frequently updated columns (indexes slow writes)
 
+**Row count decides nothing on its own.** A 40-row lookup table joined in every
+report query and a 40-row config table read twice a week are the same size and
+not the same decision — index the first on its observed access pattern, leave
+the second alone. "Small" without "rarely accessed" is the folklore half of this
+rule.
+
+**Foreign-key and uniqueness indexes are created regardless of table size.**
+They serve integrity and lookup latency, and a row count bears on neither. A
+40-row child table pointing at a customers table gets its foreign-key column
+indexed like any other. Omit one only on the strength of inspected schema
+behavior plus a representative workload measurement showing it serves no access
+path — never on an anticipated write cost.
+
 ### Composite indexes
 
-Order matters — most selective column first:
+Order matters, and what decides it is the **predicate shape**, not selectivity:
+
+1. Columns compared with **equality** (`=`, `IN`) come first.
+2. Then the column compared with a **range** (`<`, `>`, `BETWEEN`, `LIKE 'x%'`).
+3. Then columns the query only **orders by**.
+
+Selectivity is a tie-break *within* a group, never the primary key of the
+decision. An index cannot use any column after the first range predicate for
+lookup, so a highly selective range column placed first throws away every column
+behind it.
 
 ```php
+// WHERE customer_id = ? AND created_at > ?  ORDER BY created_at
 $table->index(['customer_id', 'created_at']);
 ```
 
+`customer_id` leads because it is the **equality** predicate — not because it is
+more selective. Reverse the order and the equality column sits behind a range,
+where the index can no longer seek on it. That holds even when `created_at` is
+the more selective of the two, which is exactly the case the folklore rule gets
+wrong.
+
 ## Query Optimization
 
 ### EXPLAIN analysis
 
-| Column | Bad value | Meaning |
+| Column | Value worth a second look | The question it raises |
 |---|---|---|
-| `type` | `ALL` | Full table scan — needs index |
 | `rows` | High number | Too many rows examined |
 | `Extra` | `Using filesort` | Sorting without index |
 | `Extra` | `Using temporary` | Temp table — optimize GROUP BY/DISTINCT |
@@ -42,6 +85,22 @@ $table->index(['customer_id', 'created_at']);
 
 Good values: `type` = `ref`, `eq_ref`, `const`; `Extra` = `Using index`.
 
+**`type = ALL` is a full table scan, and a full table scan is often the correct
+plan.** It belongs in no "bad value" column, because the row itself does not
+decide:
+
+- On a table small enough to sit in a page or two, the scan is **cheaper** than
+  an index lookup — the index costs a second read plus a row fetch per hit.
+- On a predicate that matches a large fraction of the table, the planner picks
+  the scan **on purpose**; forcing an index there is slower, and many planners
+  will ignore the hint.
+- On a table with hundreds of thousands of rows and a predicate matching a
+  handful, `ALL` is the defect.
+
+The question to answer is *how many rows the predicate matches, out of how
+many* — not whether `type` reads `ALL`. Compare the planner's `rows` estimate
+against the table's size before concluding anything.
+
 ### Anti-patterns
 
 | Anti-pattern | Fix |
@@ -49,9 +108,20 @@ Good values: `type` = `ref`, `eq_ref`, `const`; `Extra` = `Using index`.
 | `SELECT *` in production | Select only needed columns |
 | `LIKE '%search%'` | Fulltext search or `LIKE 'search%'` |
 | `OFFSET` on large tables | Cursor pagination |
-| Subquery in WHERE | Rewrite as JOIN |
 | `ORDER BY RAND()` | Application-level randomization |
 
+**Subqueries in `WHERE` are not on that list**, and the unconditional "rewrite
+as a JOIN" they used to carry here was wrong more often than it was right:
+
+| The subquery is | Do |
+|---|---|
+| **correlated** — it references the outer row, so it re-executes per row | rewrite as a JOIN, or as a derived table joined once. This is the case the folklore rule was built for |
+| an **uncorrelated `IN` / `EXISTS`** | leave it. Planners flatten these into a semi-join already, and the hand-written JOIN often introduces the duplicate rows a semi-join was avoiding |
+| a **bound on the driving set** — it produces a small list the outer query then filters on | leave it. Rewriting widens the driving set, which is the opposite of the intent |
+
+Check the plan before rewriting: if the subquery already shows as a semi-join or
+a materialized derived table executed once, the rewrite buys nothing and costs
+correctness.
 ### Pagination
 
 Always paginate list endpoints — never `get()` on unbounded queries:
@@ -68,10 +138,23 @@ $users = User::query()->orderBy('id')->cursorPaginate(15);
 
 - Use `php artisan make:migration` to generate.
 - Use `decimal` for money — never `float`.
-- Add foreign keys with `constrained()` + proper `onDelete()`.
+- Add foreign keys with `constrained()`, and **choose** the `onDelete()` action
+  rather than copying one: `cascade` when the child is expendable without its
+  parent, `restrict` when the child is a record in its own right (an invoice, an
+  audit row, a payment), `set null` when it survives the parent with the link
+  removed — which needs a nullable column. The decision table lives in
+  [`laravel-migration`](../../../src/skills/laravel-migration/SKILL.md)
+  § Referential action is a decision.
 - Always add indexes for searchable/filterable columns.
 - One logical change per migration.
-- Make reversible when possible (`down()` method).
+- **Declare recovery, always.** Either a `down()` that restores the prior state,
+  or — when restoration is genuinely impossible — a roll-forward plan written in
+  the migration file itself, naming why restoration is impossible with the
+  evidence, the ordered recovery steps and their inputs, the criteria that say
+  recovery succeeded, and the responsible owner. Silence is the violation, not
+  the absence of `down()`. Full contract:
+  [`laravel-migration`](../../../src/skills/laravel-migration/SKILL.md)
+  § The recovery contract.
 
 ### Multi-connection migrations
 

package/docs/guidelines/prompt-templates.md

@@ -1,8 +1,8 @@
 # Prompt Templates
 
-Reference catalogue of prompt structures the [`prompt-optimizer`](../../.agent-src.uncondensed/skills/prompt-optimizer/SKILL.md)
+Reference catalogue of prompt structures the [`prompt-optimizer`](../../src/skills/prompt-optimizer/SKILL.md)
 skill picks from during the **Develop** step of the 4-D methodology.
-Cited by the [`refine-prompt`](../../.agent-src.uncondensed/skills/refine-prompt/SKILL.md)
+Cited by the [`refine-prompt`](../../src/skills/refine-prompt/SKILL.md)
 skill in `mini` mode for stack-aware shaping.
 
 Templates are tools, not dogma. Pick by request type, not by upstream
@@ -108,7 +108,7 @@ warrants either reaction. The stance slot makes the honest-when-warranted
 contract explicit.
 
 **Package equivalents** — inside this agent-config, the
-[`adversarial-review`](../../.agent-src.uncondensed/skills/adversarial-review/SKILL.md)
+[`adversarial-review`](../../src/skills/adversarial-review/SKILL.md)
 skill implements the same stance via an Attack-Defend-Revise loop and is
 the right tool when the user submits finished work for a critical take.
 This template is for **end-users prompting their own LLM** (ChatGPT,
@@ -155,7 +155,7 @@ are slots the model cannot fill honestly.
 The catalogue's own position: a template earns its place by making a
 request *checkable*, not by making it sound authoritative. Where a rough
 prompt carries one of these three, the
-[`prompt-optimizer`](../../.agent-src.uncondensed/skills/prompt-optimizer/SKILL.md)
+[`prompt-optimizer`](../../src/skills/prompt-optimizer/SKILL.md)
 strips it in its de-inflation sub-step before any template is picked —
 and strips nothing else, because everything outside these three is a
 requirement the author meant. This section is own analysis; it records a
@@ -183,7 +183,7 @@ membership.
 
 ## See also
 
-- [`prompt-optimizer`](../../.agent-src.uncondensed/skills/prompt-optimizer/SKILL.md) — engine-outbound; cites this catalogue in its Develop step
-- [`refine-prompt`](../../.agent-src.uncondensed/skills/refine-prompt/SKILL.md) — engine-inbound; uses templates in `mini` mode for stack-aware shaping
-- [`prompt-engineering-patterns`](../../.agent-src.uncondensed/skills/prompt-engineering-patterns/SKILL.md) — production-LLM prompt patterns (sibling skill, not a catalogue)
+- [`prompt-optimizer`](../../src/skills/prompt-optimizer/SKILL.md) — engine-outbound; cites this catalogue in its Develop step
+- [`refine-prompt`](../../src/skills/refine-prompt/SKILL.md) — engine-inbound; uses templates in `mini` mode for stack-aware shaping
+- [`prompt-engineering-patterns`](../../src/skills/prompt-engineering-patterns/SKILL.md) — production-LLM prompt patterns (sibling skill, not a catalogue)
 - AI Council session: `agents/runtime/council/responses/prompt-master-mini.json` (2026-05-17) <!-- council-ref-allowed: ADR decision trace -->

package/llms.txt

@@ -281,9 +281,9 @@ technical-specification: Use when the user says \"write a spec\", \"create RFC\"
 terraform: Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform.
 terragrunt: Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt.
 test-case-discovery: Use BEFORE writing any test — enumerate cases per behavior (happy / boundary / error / abuse), prioritize by likelihood × impact, cross-check via subagent — even if the user just says 'add tests'.
-test-driven-development: Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'.
+test-driven-development: Use when implementing a feature, fixing a bug, or refactoring — write the failing test first, then the code, even on 'add this function'. Owns the ORDER; test shape is `testing-anti-patterns`.
 test-performance: Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives.
-testing-anti-patterns: Use BEFORE writing/changing tests, adding mocks, or test-only methods on production classes — vs mocking-the-mock, production pollution, partial mocks, and overfit/tautological assertions
+testing-anti-patterns: Use BEFORE writing/changing tests or adding mocks — mocking-the-mock, production pollution, overfit assertions — even on 'is this test any good?'. Test SHAPE; the order is `test-driven-development`.
 threat-modeling: Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation.
 throughput-vs-morale-tradeoff: Use when balancing eng-team velocity vs quality vs burnout — on-call load, focus fragmentation, reorg shock. Triggers on 'team is burning out', 'why is velocity dropping'.
 token-optimizer: Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — decision tree keyed by intent citing the canonical token-saving asset.

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "14.12.0",
-    "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
+    "version": "14.14.0",
+    "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including the counts in these badges.",
     "license": "MIT",
     "private": false,
     "type": "module",
@@ -52,8 +52,11 @@
         "AGENTS.md",
         "CHANGELOG.md",
         "CONTRIBUTING.md",
+        "CREDITS.md",
         "LICENSE",
         "MIGRATION.md",
+        "NOTICE",
+        "docs/THIRD-PARTY-NOTICES.md",
         "README.md",
         "llms.txt",
         "!dist/**/*.test.js",

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

@@ -12,8 +12,8 @@
  * `urp.collect()` completion criterion, and exit code 0. snake_case kept.
  *
  * A roadmap that has reached `count_open == 0` and `count_deferred == 0` is
- * **complete**. This sweep moves it to `agents/roadmaps/archive/`, rewrites
- * inbound references (`agents/roadmaps/<x>.md` → `agents/roadmaps/archive/<x>.md`)
+ * **complete**. This sweep moves it to `agents/roadmaps/archive/`, rewrites code-comment-allow provenance-comment -- the sweep's own operand
+ * inbound references (`agents/roadmaps/<x>.md` → `agents/roadmaps/archive/<x>.md`) code-comment-allow provenance-comment -- the rewrite this sweep performs
  * across tracked files so links never break, and regenerates the dashboard.
  *
  * It replaces the old **merge-gate** (keep one item open + a manual post-merge
@@ -59,6 +59,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { collect } from './update_roadmap_progress.js';
+import { guardedBaselineProblems, parseGuardedBaselines } from './guarded_baseline.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -135,7 +136,7 @@ function _branch_touched_paths(root: string, base: string): Set<string> | null {
  *
  * Two classes, and the second is why this predicate exists at all:
  *
- * - `agents/evidence/**` — a committed record of what was true, or of what a
+ * - `agents/evidence/**` — a committed record of what was true, or of what a code-comment-allow provenance-comment -- the predicate's operand set
  *   reviewer was shown, at one point in time. Retroactively editing it makes it
  *   claim something that did not happen, which is the failure
  *   `evaluator-independence` exists to prevent ("the prompt ships with the
@@ -144,8 +145,8 @@ function _branch_touched_paths(root: string, base: string): Set<string> | null {
  *   the payload. Rewriting them detaches the patch from the commit it records
  *   AND makes `git apply` target a path the diff never created.
  *
- * Measured 2026-08-11: archiving one roadmap rewrote four frozen artefacts
- * under `agents/evidence/reviews/`, including the `diff.patch` headers of a
+ * Measured 2026-08-11: archiving one roadmap rewrote four frozen artifacts
+ * under `agents/evidence/reviews/`, including the `diff.patch` headers of a code-comment-allow provenance-comment -- names what the predicate protects
  * recorded review input. Nothing caught it — the sweep reported it as
  * "4 ref(s) migrated", which reads like success.
  */
@@ -311,7 +312,202 @@ interface ArchiveRecord {
     refs_migrated: string[];
 }
 
-/** Archive every complete active roadmap (count_open==0, count_deferred==0). */
+
+/** One `[~]` step and whatever resolution annotation follows it. */
+export interface DeferredItem {
+    /** The step text, trimmed, for the operator message. */
+    text: string;
+    /** `carried-to` / `merged-into`, or `null` when no annotation was found. */
+    kind: 'carried-to' | 'merged-into' | null;
+    /** Destination roadmap slug, or `null`. */
+    destination: string | null;
+}
+
+/**
+ * `<!-- deferred-resolution: carried-to=<slug> -->` — the resolved-deferral
+ * annotation. `merged-into=<slug>` is the second accepted form.
+ */
+const DEFERRED_RESOLUTION_RE = /<!--\s*deferred-resolution:\s*(carried-to|merged-into)\s*=\s*([A-Za-z0-9._-]+)\s*-->/;
+
+/** `- [~] …` — a deferred step, at any indent, with `-` or `*`. */
+const DEFERRED_STEP_RE = /^[ \t]*[-*][ \t]+\[~\][ \t]*(.*)$/;
+/** Any other checkbox, or a heading — where a step's block ends. */
+const BLOCK_END_RE = /^[ \t]*[-*][ \t]+\[[ xX~-]\]|^#{1,6}[ \t]/;
+
+/** Escape a string for literal use inside a `RegExp`. */
+function _escapeRe(v: string): string {
+    return v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Does this frontmatter declare a `relates:` row naming `slug`?
+ *
+ * Structured, not textual: the slug has to appear as a `- slug: <name>` row or a
+ * bare `- <name>` item inside the `relates:` block, which is a declaration the
+ * author made deliberately. A mention anywhere else in the file does not count.
+ */
+export function _relatesTo(text: string, slug: string): boolean {
+    const lines = text.split('\n');
+    const start = lines.findIndex((l) => /^relates:/.test(l));
+    if (start === -1) return false;
+    const re = new RegExp(`^\\s*-\\s*(slug:\\s*)?${_escapeRe(slug)}\\s*$`);
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i] as string;
+        if (/^\S/.test(line)) break;
+        if (re.test(line)) return true;
+    }
+    return false;
+}
+
+/** Every `[~]` step in a roadmap, with the annotation that follows it (if any). */
+export function parseDeferredItems(text: string): DeferredItem[] {
+    const lines = text.split('\n');
+    const out: DeferredItem[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = DEFERRED_STEP_RE.exec(lines[i] as string);
+        if (m === null) continue;
+        // The annotation may sit on the step line itself or anywhere in the
+        // step's continuation block, which ends at the next checkbox or heading.
+        let block = lines[i] as string;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (BLOCK_END_RE.test(lines[j] as string)) break;
+            block += '\n' + (lines[j] as string);
+        }
+        const a = DEFERRED_RESOLUTION_RE.exec(block);
+        out.push({
+            text: (m[1] ?? '').trim().slice(0, 120),
+            kind: a === null ? null : (a[1] as 'carried-to' | 'merged-into'),
+            destination: a === null ? null : (a[2] as string),
+        });
+    }
+    return out;
+}
+
+/**
+ * Decide whether a roadmap's `[~]` items are RESOLVED, per the AI council of
+ * 2026-08-27 (2 seats, convergent on option (c)).
+ *
+ * Iron Law 3 says a deferral must be resolved before archival, and the
+ * preservation test routes four dispositions to the council — but three of them
+ * (carry to a follow-up, merge into existing work, restore to open) leave the
+ * `[~]` glyph in place, and this sweep used to require `deferred === 0`
+ * unconditionally. So a genuinely UNEXECUTABLE item — one needing elapsed time
+ * rather than effort — had no council-reachable path to an archived roadmap, and
+ * the only glyph that cleared the gate was `[-]`, which is owner-reserved AND
+ * pinned to mean "won't happen at all". Using it for a carried item would make
+ * cancellation and transfer indistinguishable to every later reader.
+ *
+ * **Fail-closed at every step**, which is the condition both seats attached to
+ * their verdict: a bare `[~]` blocks, a malformed annotation blocks, a
+ * destination that does not exist blocks, a destination that is itself archived
+ * or skipped blocks, and a missing back-link blocks. The annotation is cheap to
+ * write and must therefore be expensive to satisfy.
+ *
+ * NOT checked, and named rather than implied: that the destination's copy of the
+ * criterion is faithful. Both seats asked for stable item identity over verbatim
+ * text matching, and neither a text match nor an id exists today — the back-link
+ * plus the source-slug mention is the strongest link this sweep can verify
+ * without inventing an identity scheme. The reviewer of the carry still reads it.
+ *
+ * @returns `problems` empty ⇒ every deferral is resolved and archival may proceed.
+ */
+export function deferralProblems(
+    root: string,
+    rel: string,
+    text: string,
+    /**
+     * Slugs this same sweep is about to archive. A destination in this set is
+     * about to become dead, so accepting it would leave the carried item with no
+     * live receiver — the exact loss the annotation exists to prevent, produced
+     * by the mechanism meant to prevent it. Found by an independent review, with
+     * two reproducers: a roadmap naming ITSELF as destination, and two roadmaps
+     * both complete in one run where the parent carries to the child.
+     *
+     * Optional so the unit tests can call this with one roadmap in view; the
+     * sweep always passes the real set.
+     */
+    alsoArchiving: ReadonlySet<string> = new Set(),
+): string[] {
+    const sourceSlug = rel.replace(/\.md$/, '');
+    const problems: string[] = [];
+    for (const item of parseDeferredItems(text)) {
+        const label = item.text === '' ? '(unnamed step)' : item.text;
+        if (item.kind === null || item.destination === null) {
+            problems.push(
+                `deferred step ${JSON.stringify(label)} carries no ` +
+                    '`<!-- deferred-resolution: carried-to=<slug> -->` annotation',
+            );
+            continue;
+        }
+        // Active or parked are both live. Archived and skipped are not: carrying
+        // an item into a dead roadmap is the silent loss the annotation exists
+        // to prevent, and it is exactly the "broken promise" case one seat asked
+        // to be detectable.
+        const candidates = [
+            path.join(root, 'agents', 'roadmaps', `${item.destination}.md`),
+            path.join(root, 'agents', 'roadmaps', 'later', `${item.destination}.md`),
+        ];
+        // Self-reference is never a carry. It passes every other check — the
+        // file exists, and a `parent_roadmap:` naming itself would satisfy the
+        // back-link — and then the sweep archives it, so the destination is dead
+        // the moment the source is.
+        if (item.destination === sourceSlug) {
+            problems.push(
+                `deferred step ${JSON.stringify(label)} names its OWN roadmap as the destination — ` +
+                    'a carry needs a different receiver, or the item is not carried at all',
+            );
+            continue;
+        }
+        if (alsoArchiving.has(item.destination)) {
+            problems.push(
+                `destination \`${item.destination}\` is being archived by this same sweep, so it would be ` +
+                    'dead the moment the carry lands — archive it first and re-run, or carry to a roadmap that stays active',
+            );
+            continue;
+        }
+        const found = candidates.find((c) => fs.existsSync(c));
+        if (found === undefined) {
+            const dead = ['archive', 'skipped'].find((d) =>
+                fs.existsSync(path.join(root, 'agents', 'roadmaps', d, `${item.destination ?? ''}.md`)),
+            );
+            problems.push(
+                dead === undefined
+                    ? `deferred step ${JSON.stringify(label)} names destination \`${item.destination}\`, which does not exist`
+                    : `deferred step ${JSON.stringify(label)} names destination \`${item.destination}\`, which is in \`${dead}/\` — a dead roadmap cannot receive a carried item`,
+            );
+            continue;
+        }
+        const destText = fs.readFileSync(found, 'utf-8');
+        // ESCAPED. The slug was interpolated raw, so `road.parent` matched
+        // `roadXparent` and a slug containing `[` or `(` made `new RegExp` THROW
+        // and abort the whole sweep — in a function whose entire contract is
+        // failing closed. Found by an independent review; both seats named it.
+        const backlink = new RegExp(`^parent_roadmap:[ \t]*${_escapeRe(sourceSlug)}[ \t]*$`, 'm');
+        if (item.kind === 'carried-to' && !backlink.test(destText)) {
+            problems.push(
+                `destination \`${item.destination}\` carries no \`parent_roadmap: ${sourceSlug}\` back-link — ` +
+                    'the link must be verifiable from both ends',
+            );
+            continue;
+        }
+        // A STRUCTURED link, not a substring. `destText.includes(sourceSlug)` was
+        // satisfied by any incidental mention — a filename, an example, an HTML
+        // comment — so `merged-into` proved nothing about a merge. Both review
+        // seats called it trivially spoofable. The link now has to be a
+        // frontmatter declaration: a `relates:` row naming the source, or a
+        // `parent_roadmap:` back-link. Prose cannot satisfy it.
+        if (item.kind === 'merged-into' && !backlink.test(destText) && !_relatesTo(destText, sourceSlug)) {
+            problems.push(
+                `destination \`${item.destination}\` carries no structured link back to \`${sourceSlug}\` — ` +
+                    'add a `relates:` row naming it (with a `relation:`) or a `parent_roadmap:` line. A mention ' +
+                    'in prose is not a link: it is satisfied by a filename or an example.',
+            );
+        }
+    }
+    return problems;
+}
+
+/** Archive every complete active roadmap: no open steps, and every `[~]` resolved. */
 function archive_completed(
     root: string,
     opts: { changed_only: boolean; base: string; dry_run: boolean },
@@ -331,11 +527,59 @@ function archive_completed(
         return [];
     }
 
+    // Every slug this sweep will consider archiving, computed BEFORE any of them
+    // is judged. Without it, a deferral carried to another roadmap that is also
+    // complete passes validation and then loses its receiver in the same run.
+    const sweepSet = new Set(
+        collect(roadmap_root)
+            .filter((s2) => s2.open_ === 0)
+            .map((s2) => s2.rel.replace(/\.md$/, '')),
+    );
+
     const archived: ArchiveRecord[] = [];
     for (const stats of collect(roadmap_root)) {
-        if (stats.open_ !== 0 || stats.deferred !== 0) {
+        // `guarded-baseline` is INCOMPLETE by construction (council 2026-08-31,
+        // 2/2 convergent) — checked BEFORE the open-step test on purpose. A
+        // well-formed record keeps its box `[ ]` and would be skipped silently as
+        // "not complete", which is the right verdict reached for the wrong reason
+        // 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'),
+        );
+        if (guarded.length > 0) {
+            process.stderr.write(
+                `  ⚠️  ${stats.rel}: ${guarded.length} guarded-baseline step(s) — ` +
+                    'not archived. Verify against the real mechanism, then flip to ' +
+                    '`[x]`.\n',
+            );
+            for (const p of guardedBaselineProblems(guarded)) {
+                process.stderr.write(`        · ${p}\n`);
+            }
+            continue;
+        }
+        if (stats.open_ !== 0) {
             continue; // not complete
         }
+        // A `[~]` no longer blocks unconditionally: it blocks unless it carries a
+        // validated resolution annotation. See `deferralProblems` for why, and
+        // for every way that check fails closed.
+        if (stats.deferred !== 0) {
+            const abs = path.join(roadmap_root, stats.rel);
+            // The source's own slug is removed: it is trivially in `sweepSet`,
+            // and self-reference is reported by its own, clearer message.
+            const others = new Set(sweepSet);
+            others.delete(stats.rel.replace(/\.md$/, ''));
+            const problems = deferralProblems(root, stats.rel, fs.readFileSync(abs, 'utf-8'), others);
+            if (problems.length > 0) {
+                process.stderr.write(
+                    `  ⚠️  ${stats.rel}: ${problems.length} unresolved deferral(s) — not archived.\n`,
+                );
+                for (const p of problems) process.stderr.write(`        · ${p}\n`);
+                continue;
+            }
+        }
         // An unresolved blocker outlives its steps. Closing every box does not
         // answer a question the roadmap raised for a human, and archiving on
         // step-count alone is how `b-highlights-mechanism` left the active tree
@@ -410,7 +654,7 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
 /**
  * Rebuild the archive index after a move, when the builder is present.
  *
- * The sweep is the one operation that changes what `agents/roadmaps/archive/`
+ * The sweep is the one operation that changes what `agents/roadmaps/archive/` code-comment-allow provenance-comment -- the directory this function writes
  * contains, so it is the one operation that can leave the generated index
  * stale — and the drift gate on that index runs in the same PR the sweep runs
  * in. Regenerating here keeps the two from disagreeing by construction rather