@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/run_lifecycle_suite.ts

@@ -0,0 +1,208 @@
+/**
+ * run_lifecycle_suite — run the process-level lifecycle suite and write the
+ * evidence artifact `check_supervision_claim_atomicity` reads
+ * (`road-to-supervised-telemetry-collector` steps 5.1 and 5.2).
+ *
+ * ## Why a producer script and not just `vitest run`
+ *
+ * The atomicity gate refuses a present-tense supervision claim unless
+ * `internal/reports/supervision-lifecycle.json` records a suite that ran on THIS
+ * revision, exercised real processes, and was not empty or mostly skipped. That
+ * artifact has to be written by something that knows all four facts. A test file
+ * knows whether it ran; only the runner knows the revision and the counts.
+ *
+ * ## Every field here is observed, not asserted
+ *
+ * - `revision` — `git rev-parse HEAD`, read at run time. Never a constant.
+ * - `cases_run` / `cases_skipped` — parsed out of vitest's own JSON report,
+ *   never counted by hand from the source.
+ * - `processes_exercised` — true only when the suite ACTUALLY spawned daemons,
+ *   established by re-reading the report for the property names that can only
+ *   pass against real processes. A hardcoded `true` here would defeat the entire
+ *   point of the gate, which exists because a mocked suite can demonstrate all
+ *   five properties and prove none of them.
+ *
+ * ## A skip is a failure
+ *
+ * AC-8: *"a suite that skips on a platform is a failure on that platform, not an
+ * absence."* So a run whose cases were skipped writes the artifact with the
+ * honest counts and exits non-zero, rather than writing nothing — a missing
+ * artifact and a skipped suite need different remediation and the gate
+ * distinguishes them.
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, '..', '..');
+
+/** The suite, by path. Named once so the artifact and the runner cannot drift. */
+export const SUITE_REL = 'tests/scripts/collector_lifecycle.test.ts';
+export const SUITE_NAME = 'supervision-lifecycle';
+export const EVIDENCE_REL = path.join('internal', 'reports', 'supervision-lifecycle.json');
+
+/**
+ * The five property names the suite must have RUN for the artifact to claim
+ * real processes were exercised.
+ *
+ * Matched against the report's test names rather than counted, because a count
+ * cannot tell five properties from five repeats of one.
+ */
+export const REQUIRED_PROPERTIES = [
+    'PROPERTY 1',
+    'PROPERTY 2',
+    'PROPERTY 3',
+    'PROPERTY 4',
+    'PROPERTY 5',
+] as const;
+
+export interface SuiteCounts {
+    readonly run: number;
+    readonly skipped: number;
+    readonly passedNames: readonly string[];
+}
+
+export function countsFromReport(reportJson: string): SuiteCounts {
+    const raw = JSON.parse(reportJson) as {
+        testResults?: { assertionResults?: { fullName?: string; status?: string }[] }[];
+    };
+    let run = 0;
+    let skipped = 0;
+    const passedNames: string[] = [];
+    for (const suite of raw.testResults ?? []) {
+        for (const assertion of suite.assertionResults ?? []) {
+            const status = assertion.status ?? 'unknown';
+            if (status === 'pending' || status === 'skipped' || status === 'todo') {
+                skipped += 1;
+                continue;
+            }
+            run += 1;
+            if (status === 'passed') passedNames.push(assertion.fullName ?? '');
+        }
+    }
+    return { run, skipped, passedNames };
+}
+
+/**
+ * Did the run exercise real processes?
+ *
+ * True only when every one of the five named properties PASSED. Anything less —
+ * a skipped property, a renamed one, a suite that never collected — leaves this
+ * false, and the gate then refuses the capability claim rather than accepting a
+ * partial demonstration as a whole one.
+ */
+export function processesExercised(counts: SuiteCounts): boolean {
+    return REQUIRED_PROPERTIES.every((property) =>
+        counts.passedNames.some((name) => name.includes(property)),
+    );
+}
+
+export function headRevision(repo: string = REPO): string {
+    try {
+        return execFileSync('git', ['-C', repo, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+    } catch {
+        return '';
+    }
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const dryRun = argv.includes('--dry-run');
+    const report = path.join(os.tmpdir(), `lifecycle-report-${process.pid}.json`);
+    fs.rmSync(report, { force: true });
+
+    // Clear the parity gate's alias switch, the same guard its sibling spawner
+    // takes (R2 round-5 finding 10). An ambient `AGENT_CONFIG_COLLECTOR_ABSENT`
+    // stubs the collector away for this run too, so `enableCollector` becomes a
+    // no-op and every daemon refuses with `not-enabled`. It fails loudly rather
+    // than silently — but the asymmetry between two spawners in one change is
+    // the shape the earlier finding was about.
+    const env = { ...process.env };
+    delete env.AGENT_CONFIG_COLLECTOR_ABSENT;
+
+    const result = spawnSync(
+        path.join(REPO, 'node_modules', '.bin', 'vitest'),
+        ['run', SUITE_REL, '--reporter=json', `--outputFile=${report}`],
+        { cwd: REPO, encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+
+    if (!fs.existsSync(report)) {
+        process.stderr.write(
+            `run_lifecycle_suite: no report produced.\n${result.stdout ?? ''}\n${result.stderr ?? ''}\n`,
+        );
+        return 1;
+    }
+    const counts = countsFromReport(fs.readFileSync(report, 'utf8'));
+    fs.rmSync(report, { force: true });
+
+    const revision = headRevision();
+    const suiteGreen = result.status === 0;
+    // A red suite is a THIRD state, and the artifact used to record neither it
+    // nor anything that implied it: `processes_exercised` depends only on the
+    // five named properties, so a run where all five passed and a sixth case
+    // failed wrote `processes_exercised: true, cases_skipped: 0` and then exited
+    // 1 — a pass-shaped artifact left on disk by a failing run (R2 finding 18).
+    //
+    // Two changes close it. The flag itself is conjoined with the suite's exit
+    // status, so a red run can never claim the processes were exercised; and
+    // `suite_exit_status` is recorded outright, so the state is readable rather
+    // than inferred. The gate's own contract is unchanged — it reads
+    // `processes_exercised`, which is now false on a red run.
+    const exercised = processesExercised(counts) && suiteGreen;
+    const evidence = {
+        suite: SUITE_NAME,
+        revision,
+        processes_exercised: exercised,
+        cases_run: counts.run,
+        cases_skipped: counts.skipped,
+        suite_exit_status: result.status ?? null,
+        platform: `${process.platform}-${process.arch}`,
+        recorded_at: new Date().toISOString(),
+    };
+
+    process.stdout.write(
+        `run_lifecycle_suite: ${counts.run} run, ${counts.skipped} skipped, `
+            + `suite_exit=${String(result.status ?? 'null')}, `
+            + `processes_exercised=${String(exercised)}, revision=${revision || '(unknown)'}\n`,
+    );
+
+    if (dryRun) {
+        process.stdout.write(`${JSON.stringify(evidence, null, 2)}\n`);
+        return suiteGreen && exercised && counts.skipped === 0 ? 0 : 1;
+    }
+
+    const target = path.join(REPO, EVIDENCE_REL);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${JSON.stringify(evidence, null, 2)}\n`);
+    process.stdout.write(`run_lifecycle_suite: wrote ${EVIDENCE_REL}\n`);
+
+    if (result.status !== 0) {
+        process.stderr.write('run_lifecycle_suite: the suite is RED\n');
+        return 1;
+    }
+    if (counts.skipped > 0) {
+        // AC-8 makes a skip a failure on that platform rather than an absence.
+        process.stderr.write(
+            `run_lifecycle_suite: ${counts.skipped} case(s) SKIPPED — on a declared platform a `
+                + 'skip is a failure, not an absence\n',
+        );
+        return 1;
+    }
+    if (!exercised) {
+        process.stderr.write(
+            'run_lifecycle_suite: not every named property passed — the artifact records '
+                + '`processes_exercised: false` and the capability claim stays prohibited\n',
+        );
+        return 1;
+    }
+    return 0;
+}
+
+const invokedDirectly =
+    process.argv[1] !== undefined && process.argv[1].includes('run_lifecycle_suite');
+if (invokedDirectly) {
+    process.exitCode = main();
+}

package/src/scripts/run_skill_evals.ts

@@ -153,6 +153,24 @@ export function _load_tool_trace(run_dir: string): string[] | null {
     return raw.map((e) => (typeof e === 'string' ? e : (e.tool ?? ''))).filter((s) => s !== '');
 }
 
+/**
+ * Load the recorded EVENT trace, or `null` when the run did not record one.
+ *
+ * Sibling of {@link _load_tool_trace}, and deliberately a separate file rather
+ * than a widened tool trace: a tool call is something the agent did, an event
+ * is something the harness observed — a gate running, a hook concern firing, a
+ * refusal. Conflating them would make "the linter ran" indistinguishable from
+ * "the agent invoked the linter", and the interesting failure is precisely the
+ * case where a gate was SKIPPED while the agent narrated that it passed.
+ */
+export function _load_event_trace(run_dir: string): string[] | null {
+    const p = path.join(run_dir, 'event-trace.json');
+    if (!_exists(p)) return null;
+    const raw = JSON.parse(fs.readFileSync(p, 'utf-8')) as Array<string | { event?: string }>;
+    if (!Array.isArray(raw)) return null;
+    return raw.map((e) => (typeof e === 'string' ? e : (e.event ?? ''))).filter((s) => s !== '');
+}
+
 /** Count meaningful steps: tool calls net of retries (a call whose name equals
  * the immediately-preceding call name is a retry, not a new step). */
 export function _count_meaningful_steps(trace: string[]): number {
@@ -217,6 +235,28 @@ export function _grade_assertions(
                     missing, forbidden, pass: missing.length === 0 && forbidden.length === 0,
                 });
             }
+        } else if (kind === 'event-choice') {
+            // The forbidden-event half of the case shape. Same manual-pending
+            // rule as tool-choice: no trace is NEVER a silent pass, because a
+            // missing trace and a clean run are the two readings this assertion
+            // exists to separate.
+            const mustEmit = (a['must_emit'] as string[] | undefined) ?? [];
+            const mustNotEmit = (a['must_not_emit'] as string[] | undefined) ?? [];
+            const trace = _load_event_trace(run_dir);
+            if (trace === null) {
+                results.push({
+                    kind, must_emit: mustEmit, must_not_emit: mustNotEmit, pass: null,
+                    note: 'manual-pending: no event-trace.json in run dir — record a trace or grade manually',
+                });
+            } else {
+                const seen = new Set(trace);
+                const missing = mustEmit.filter((e) => !seen.has(e));
+                const forbidden = mustNotEmit.filter((e) => seen.has(e));
+                results.push({
+                    kind, must_emit: mustEmit, must_not_emit: mustNotEmit,
+                    missing, forbidden, pass: missing.length === 0 && forbidden.length === 0,
+                });
+            }
         } else if (kind === 'trajectory_budget') {
             // Meaningful step = one tool call net of retries (a retry is a call whose
             // tool name repeats the immediately-preceding call). No trace → manual-pending.

package/src/scripts/schemas/delivery-manifest.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "delivery-manifest.schema.json",
+  "title": "Delivery manifest",
+  "description": "Obligations that may travel on a runtime carrier instead of standing context, and what happens to each when that carrier is unavailable. Contract: docs/contracts/resident-process-floors.md § 3. Resolver: src/scripts/_lib/delivery_criticality.ts.",
+  "type": "object",
+  "required": ["schema_version", "entries"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/entry" }
+    }
+  },
+  "definitions": {
+    "entry": {
+      "type": "object",
+      "required": ["id", "criticality"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Logical obligation id — the rule, gate or floor being delivered."
+        },
+        "criticality": {
+          "enum": ["critical-A", "critical-B", "standard"],
+          "description": "critical-A never migrates off standing context. critical-B may migrate and is delivered EAGERLY when the carrier is unavailable, never dropped. standard may fail open. Required here even though the resolver defaults an omitted value to critical-B: a manifest is authored, and an author who has not decided should be made to, while a RUNTIME value that is merely absent must still fail closed."
+        },
+        "carrier": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The runtime carrier that would deliver this obligation."
+        },
+        "why": {
+          "type": "string",
+          "description": "Why this class and not the next one down. Required by review, not by schema."
+        }
+      }
+    }
+  }
+}

package/src/scripts/schemas/drafting-channels.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/drafting-channels.schema.json",
+  "x-schemaVersion": "1.0.0",
+  "title": "Drafting channel registry (src/config/drafting-channels.yml)",
+  "$comment": "road-to-channel-contract-and-profile-drift Phase 1.2. Validated by tests/scripts/drafting_channels_schema.test.ts against the Draft-07 SUBSET exported by src/scripts/validate_frontmatter.ts (type, required, properties, additionalProperties:false, items, minItems, pattern, minLength, enum) — no $ref, no patternProperties, no if-then, because that validator supports none of them and a schema using them would silently not be checked. SCOPE: an output shape for prose this package writes. Deliberately NOT merged into reach-channels.schema.json: a reach channel is an external retrieval backend with an install string, a health probe and a lifecycle, and a drafting channel has none of those and carries a length and a cadence instead; a merged schema would make every field optional for half its rows. The `id` values are FLAG VALUES — what a user types after `--channel=` — which is why the enum is closed: the short form `linkedin` is the plausible typo, and an open enum would accept it silently.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "channels"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "enum": ["drafting-channels-v1"],
+      "description": "Registry format version. Bumped only on a breaking shape change."
+    },
+    "channels": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The `--channel` enum, one entry per accepted flag value. Order carries no meaning.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "length_default", "cadence"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "enum": ["tweet", "linkedin-post", "blog", "freeform"],
+            "description": "The literal `--channel=` value. Closed enum: adding a drafting channel is a contract change to docs/contracts/write-engine.md and to the three command surfaces, so it may not be done by adding a row here alone."
+          },
+          "length_default": {
+            "type": "integer",
+            "description": "Default word count when `--length` is omitted. Mirrors the Length-default column of write-engine.md § Per-channel defaults."
+          },
+          "cadence": {
+            "type": "string",
+            "minLength": 10,
+            "description": "Paragraph/structure guidance for this channel. Mirrors the Cadence-guidance column of write-engine.md § Per-channel defaults."
+          }
+        }
+      }
+    }
+  }
+}

package/src/scripts/schemas/evals.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/evals.schema.json",
-  "x-schemaVersion": "1.0.0",
+  "x-schemaVersion": "1.1.0",
   "title": "Skill behavioural evals (evals.json)",
   "$comment": "Behavioural-eval spec consumed by run_skill_evals.ts (scaffold/aggregate/report) and counted by skill_eval_coverage.ts. Distinct from triggers.json (activation/routing axis). Roadmap: road-to-skill-eval-coverage Phase 1. Assertion kinds mirror _grade_assertions() in run_skill_evals.ts exactly \u2014 add a kind there before adding it here.",
   "type": "object",
@@ -198,6 +198,29 @@
                       "description": "Ceiling on meaningful steps = tool calls net of retries (a call repeating the immediately-preceding call name is a retry, not a step). Counted from <run_dir>/tool-trace.json; no trace → manual-pending. v2, additive."
                     }
                   }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind"],
+                  "anyOf": [
+                    { "required": ["kind", "must_emit"] },
+                    { "required": ["kind", "must_not_emit"] }
+                  ],
+                  "properties": {
+                    "kind": { "const": "event-choice" },
+                    "must_emit": {
+                      "type": "array",
+                      "items": { "type": "string", "minLength": 1 },
+                      "description": "Harness events the run MUST have emitted, checked against <run_dir>/event-trace.json. v2, additive."
+                    },
+                    "must_not_emit": {
+                      "type": "array",
+                      "items": { "type": "string", "minLength": 1 },
+                      "description": "Harness events the run MUST NOT have emitted — a skipped gate or a refused turn becomes checkable rather than narrated. v2, additive."
+                    }
+                  },
+                  "$comment": "Forbidden-event array alongside the expected-event array. An EVENT is something the harness observed (a gate running, a hook concern firing, a refusal); a TOOL call is something the agent did — conflating them makes \"the linter ran\" indistinguishable from \"the agent invoked the linter\", and the interesting failure is a gate that was SKIPPED while the agent narrated a pass. Hence a separate kind and a separate trace file. `anyOf` requires at least one of the two arrays BY CONSTRUCTION: the sibling tool-choice shape requires neither, so {\"kind\": \"tool-choice\"} is schema-valid and enforces nothing — this kind cannot express that. No trace present → pass:null manual-pending, never a silent pass."
                 }
               ]
             }

package/src/scripts/schemas/rule.schema.json

@@ -158,7 +158,43 @@
         "type": "string",
         "enum": ["developer", "reviewer", "tester", "po", "incident", "planner"]
       },
-      "description": "Subagent role-mode scoping axis (road-to-lean-agent-init Phase 4), parallel to `workspaces`/`packs`. Closed vocabulary — the six RoleMode ids from src/scripts/_lib/subagent_spawn.ts. Absent/empty = untagged, fails safe (ships to every role). Kernel rules (type: always) always ship regardless of this field. Enforced via this schema's `enum` (not a src/config/discovery/*.yml + lint_artefact_frontmatter.ts cross-check like workspaces/packs) because lint_artefact_frontmatter.ts still scans the retired legacy rules tree (0 artefacts post-ADR-051 src/ migration) and is a no-op for src/rules/*.md today; validate_frontmatter.ts (the active src/rules linter) enforces this enum instead."
+      "description": "Subagent role-mode scoping axis (road-to-lean-agent-init Phase 4), parallel to `workspaces`/`packs`. Closed vocabulary — the six RoleMode ids from src/scripts/_lib/subagent_spawn.ts. Absent/empty = untagged, fails safe (ships to every role). Kernel rules (type: always) always ship regardless of this field. Enforced via this schema's `enum` (not a src/config/discovery/*.yml + lint_artefact_frontmatter.ts cross-check like workspaces/packs) because lint_artefact_frontmatter.ts still scans the retired legacy rules tree (0 artifacts post-ADR-051 src/ migration) and is a no-op for src/rules/*.md today; validate_frontmatter.ts (the active src/rules linter) enforces this enum instead."
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_type"],
+      "allOf": [
+        {
+          "$comment": "`normative_level` states how binding the SOURCE is. For `own-analysis` there is no external source, so the field answers a question that does not arise and `informative` is its only coherent value — requiring it there forces a non-answer. `verified_on` is conditional for the same reason and not a second exception: it stamps when an EXTERNAL source pointer was last checked, and where there is no external source the rule\u2019s own git history is its staleness. Both are required for every other source_type, where the questions are real. Surfaced by the delivered-payload ceiling: ten blocks did not fit, and the two fields that did not fit were the two that were not saying anything.",
+          "if": { "properties": { "source_type": { "not": { "const": "own-analysis" } } }, "required": ["source_type"] },
+          "then": { "required": ["normative_level", "verified_on"] }
+        }
+      ],
+      "description": "Where this rule's NORMATIVE CONTENT came from, and what it was when it left. Optional; road-to-retired-claims-stay-retired Phase 3. Distinct from `decision_impact_evidence`, which points at an observation that the model already complies WITHOUT the rule \u2014 the opposite direction. A rule stating a threshold, a number, or a mechanism taken from outside this repository either cites it here or is recorded as own analysis; `src/rules/code-provenance.md` \u00a7 The knowledge layer states that obligation for prose, and this block is where a rule discharges it structurally. Optional on day one by design: 0 of 120 rules carried any provenance field before this, and a required field would fail the build on all of them at once \u2014 the gate-that-can-only-block shape this repository's own records name as the reason a gate gets suppressed.",
+      "properties": {
+        "source_type": {
+          "type": "string",
+          "enum": ["own-analysis", "internal-incident", "external-standard", "external-research", "vendor-doc"],
+          "description": "`own-analysis`: derived in this repository, no external source \u2014 a COMPLETE discharge, never a fallback for not having looked. `internal-incident`: a failure observed here. `external-standard`: OWASP, WCAG, an RFC, a regulation. `external-research`: a paper or study. `vendor-doc`: a host or provider's own documentation."
+        },
+        "source_urls": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 8 },
+          "description": "Optional. Where the source lives. An `ENC1:` token per `src/rules/source-confidentiality.md` where naming the source in the tracked tree is not permitted. Absent is CORRECT for `own-analysis`, and for an `internal-incident` whose record is a commit or an ADR rather than a URL."
+        },
+        "verified_on": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "Dated stamp on the citation, in the same sense as the claims ledger's `https://\u2026 (YYYY-MM-DD)` evidence form: the date this block was last checked against the rule's normative content and the source it names. It is NOT a fetch receipt \u2014 nothing here retrieves a URL, and a block claiming otherwise would be the manufactured verification `src/rules/direct-answers.md` Iron Law 2 forbids. A stamp that never moves while the rule's body changes is the signal a reader should act on."
+        },
+        "normative_level": {
+          "type": "string",
+          "enum": ["mandatory", "recommended", "informative"],
+          "description": "How binding the SOURCE is \u2014 never how binding this rule is. A rule may impose an Iron Law on top of an `informative` source; stating the source's own level is what stops a house choice being read as an external requirement."
+        }
+      }
     },
     "lifecycle": {
       "type": "string",
@@ -192,6 +228,21 @@
       },
       "description": "ADR-013 trust block. Vocabulary mirrored by scripts/lint_artefact_frontmatter.py."
     },
+    "composition_review": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The authoring-search record (road-to-composition-before-creation Phase 3): which incumbents were searched before this artifact was created, and the declared delta for each. Optional on existing artifacts by design \u2014 nothing is backfilled. Distinct from `collision_ok`, which is keyed by trigger VALUE and fires only on a trigger collision; this is keyed by INCUMBENT and is written at authoring time whether or not any trigger is shared.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["candidate", "disposition", "rationale"],
+        "properties": {
+          "candidate": {"type": "string", "minLength": 1, "description": "The incumbent searched, as `skill:<name>` / `rule:<name>` / `command:<name>` / `guideline:<path>`. The literal `none` records a search that found no credible incumbent \u2014 the value that must exist so an author is never pushed to invent one to satisfy the schema."},
+          "disposition": {"type": "string", "enum": ["extend_incumbent", "compose_with_incumbent", "create_separate", "none_found"], "description": "What happened to this candidate. `create_separate` is the value no other disposition vocabulary in this tree can express: an incumbent exists, was evaluated, and a separate artifact was authored anyway."},
+          "rationale": {"type": "string", "minLength": 16, "description": "One sentence naming the delta \u2014 what this artifact does that the candidate does not, or why the candidate could not absorb it. A lint checks that this is non-empty and that `candidate` resolves; it cannot check that the search was diligent, and does not pretend to."}
+        }
+      }
+    },
     "collision_ok": {
       "type": "object",
       "additionalProperties": {"type": "string", "minLength": 8},

package/src/scripts/schemas/skill.schema.json

@@ -26,7 +26,7 @@
       "type": "string",
       "minLength": 1,
       "maxLength": 200,
-      "description": "Trigger phrase; the ceiling is 200 chars, measured. Lowered from 220 on 2026-08-22 because 220 described no artefact that existed: across all 290 skills the distribution was median 181 / p75 189 / max 200, with ZERO over 200, so the 20 chars above the recommended line were dead headroom a future author could fill with no gate objecting. p75 = 189 is the recorded soft target; 200 is the hard line. Descriptions load eagerly via progressive disclosure, so every char here is standing cost on every spawn."
+      "description": "Trigger phrase; the ceiling is 200 chars, measured. Lowered from 220 on 2026-08-22 because 220 described no artifact that existed: across all 290 skills the distribution was median 181 / p75 189 / max 200, with ZERO over 200, so the 20 chars above the recommended line were dead headroom a future author could fill with no gate objecting. p75 = 189 is the recorded soft target; 200 is the hard line. Descriptions load eagerly via progressive disclosure, so every char here is standing cost on every spawn."
     },
     "compatibility": {
       "type": "string",
@@ -374,6 +374,21 @@
       "default": "active",
       "description": "ADR-013 lifecycle state."
     },
+    "composition_review": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The authoring-search record (road-to-composition-before-creation Phase 3): which incumbents were searched before this artifact was created, and the declared delta for each. Optional on existing artifacts by design \u2014 nothing is backfilled. Distinct from `collision_ok`, which is keyed by trigger VALUE and fires only on a trigger collision; this is keyed by INCUMBENT and is written at authoring time whether or not any trigger is shared.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["candidate", "disposition", "rationale"],
+        "properties": {
+          "candidate": {"type": "string", "minLength": 1, "description": "The incumbent searched, as `skill:<name>` / `rule:<name>` / `command:<name>` / `guideline:<path>`. The literal `none` records a search that found no credible incumbent \u2014 the value that must exist so an author is never pushed to invent one to satisfy the schema."},
+          "disposition": {"type": "string", "enum": ["extend_incumbent", "compose_with_incumbent", "create_separate", "none_found"], "description": "What happened to this candidate. `create_separate` is the value no other disposition vocabulary in this tree can express: an incumbent exists, was evaluated, and a separate artifact was authored anyway."},
+          "rationale": {"type": "string", "minLength": 16, "description": "One sentence naming the delta \u2014 what this artifact does that the candidate does not, or why the candidate could not absorb it. A lint checks that this is non-empty and that `candidate` resolves; it cannot check that the search was diligent, and does not pretend to."}
+        }
+      }
+    },
     "requires_skills": {
       "type": "array",
       "minItems": 1,
@@ -382,7 +397,7 @@
         "type": "string",
         "pattern": "^[a-z][a-z0-9-]*$"
       },
-      "description": "Skill-composition graph (roadmap 3.4): names of sub-skills this skill's body invokes/assumes. Distinct from ADR-015 `requires` (artefact→pack edges). scripts/check_skill_requires.py enforces (a) each target exists and (b) the required skill is co-available wherever this skill ships (same pack, a requires_hint-reachable pack, or always-on)."
+      "description": "Skill-composition graph (roadmap 3.4): names of sub-skills this skill's body invokes/assumes. Distinct from ADR-015 `requires` (artifact→pack edges). scripts/check_skill_requires.py enforces (a) each target exists and (b) the required skill is co-available wherever this skill ships (same pack, a requires_hint-reachable pack, or always-on)."
     },
     "trust": {
       "type": "object",

package/src/scripts/skill_overlap.ts

@@ -300,7 +300,13 @@ export function render(pairs: Pair[], total: number): string {
     const lines: string[] = [
         '# Skill Structural Overlap (baseline)',
         '',
-        '> Generated by `scripts/skill_overlap.py`. Scans',
+        // The literal rather than `_lib/generated_by`'s helper, deliberately:
+        // `lint_skill_originality`'s harness copies THIS FILE ALONE into a
+        // synthetic tree and runs it, so a `./_lib/` import here fails to
+        // resolve at runtime. The attribution is a constant, not a
+        // computation, and the tree-wide invariant is held by the sweep in
+        // tests/scripts/generated_by.test.ts rather than by this import.
+        '> Generated by `skill_overlap`. Do not edit. Scans',
         '> `src/skills/*/SKILL.md` frontmatter (description +',
         '> trigger metadata) and body symbol references. Reports pairs in two',
         `> tiers: **strong** ≥ ${pyFloatStr(STRONG_TOKEN)} description-token Jaccard or ≥ ${pyFloatStr(STRONG_SYMBOL)}`,

package/src/scripts/skill_tools/run_block_d_eval.ts

@@ -28,6 +28,9 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { audit, type PersonaRow } from './audit_persona_coverage.js';
+/** Sentinel for "no catalogue root resolved" — never a readable path. */
+const NO_CATALOGUE = '<no-skills-catalogue>';
+
 import { DEFAULT_SKILLS_DIR, rank } from './score_skill_relevance.js';
 import { suggest } from './suggest_skill_for_task.js';
 import { pyRound } from '../_lib/value_ladder.js';
@@ -312,7 +315,11 @@ function _argError(message: string): never {
 
 export function parse_args(argv: string[]): Args {
     const args: Args = {
-        skills_dir: DEFAULT_SKILLS_DIR,
+        // `?? ''` is deliberately NOT used here: an empty string re-creates
+        // exactly the silent-empty-catalogue defect that repointing
+        // DEFAULT_SKILLS_DIR removed. When no catalogue resolves, this reads
+        // as the literal marker below and the caller's own check reports it.
+        skills_dir: DEFAULT_SKILLS_DIR ?? NO_CATALOGUE,
         personas_dir: PERSONAS_DIR,
         corpus_dir: CORPUS_DIR,
         json: false,