@event4u/agent-config 11.0.0 → 12.1.0

package/src/scripts/release.ts

@@ -536,7 +536,7 @@ function die(msg: string, code = 2): never {
     throw new SystemExitError(code);
 }
 
-interface RunResult {
+export interface RunResult {
     returncode: number;
     stdout: string;
     stderr: string;
@@ -1623,6 +1623,93 @@ function set_template_pin(p: string, version: string): void {
     fs.writeFileSync(p, lines.join('\n'), 'utf-8');
 }
 
+/**
+ * Refuse a MAJOR cut that carries a scheduled deprecation due at or before it.
+ *
+ * **The trigger is the shape of the TARGET, not a comparison with the current
+ * version.** A major target is `X.0.0` — and that one predicate covers every
+ * path to a major: the `--as major` flag, an explicit `--version 13.0.0`,
+ * auto-detection from a `feat!:` commit, AND `--resume`, where
+ * `_detect_in_flight_target()` returns the already-bumped `package.json`
+ * version so `target === current` and any current-vs-target comparison
+ * silently returns. Resume was the fourth path an earlier version of this
+ * guard missed while its own comment claimed three paths converged.
+ *
+ * Refusing a resumed release can strand a partially-completed one, and that is
+ * the deliberate trade: a stranded release is recoverable by fixing the table
+ * and resuming again, whereas a major shipped over a missed commitment is the
+ * failure this whole surface exists to prevent.
+ *
+ * The target version is PASSED to the gate. Without it the gate falls back to
+ * `package.json`, which at the cut to N still reads N-1 — so a row committed
+ * to N reads as one major early and passes, and only rows already a major late
+ * could ever be refused. That is the lateness being prevented, so measuring
+ * against the shipped version would have made the refusal fire exactly one
+ * major too late, forever.
+ *
+ * Runs under `--dry-run` too, unlike the rest of preflight: this check is one
+ * subprocess reading two files, so the "keep a preview fast" rationale that
+ * excludes the ~15s test-trend collection does not apply — and a preview that
+ * reports green for the single condition that will refuse the real run is the
+ * case an operator runs a preview to discover. It REPORTS there rather than
+ * dying: `--dry-run` exiting 0 before `execute()` and before `preflight()` is a
+ * contract this file's own tests assert, and an earlier revision of this guard
+ * broke it by sitting above the dry-run branch with no preview mode.
+ *
+ * @param runner Seam for the gate invocation. Production passes nothing and
+ * gets the real `run`; tests inject a stub, because the alternative — reaching
+ * this branch only by mutating `docs/MIGRATION.md` — would make the refusal
+ * path testable exclusively through a tracked-file edit.
+ */
+export function assert_scheduled_deprecations_clear(
+    target: string,
+    runner: (args: readonly string[]) => RunResult = (args) => run(args, { check: false, capture: true }),
+    opts: { previewOnly?: boolean } = {},
+): void {
+    const [, minor, patch] = parse_version(target);
+    if (minor !== 0 || patch !== 0) {
+        return;
+    }
+    const res = runner([
+        './scripts-run',
+        'src/scripts/lint_scheduled_deprecations',
+        '--cutting',
+        target,
+    ]);
+    if (res.returncode === 0) {
+        return;
+    }
+    process.stderr.write(res.stdout);
+    process.stderr.write(res.stderr);
+    if (res.returncode !== 1) {
+        // The gate reserves 1 for a finding and 2 for a usage/environment
+        // failure. Diagnosing the latter as "the table has an overdue row"
+        // sends the releaser to edit a file that is not the problem.
+        die(
+            `refusing the ${target} cut: the scheduled-deprecations check could not run ` +
+                `(exit ${String(res.returncode)}). That is an environment or usage failure, not a ` +
+                'finding in docs/MIGRATION.md — fix the invocation or the checkout, then re-run.',
+        );
+    }
+    if (opts.previewOnly === true) {
+        // The preview's job is to SHOW what the real run will refuse. Dying
+        // here would break the `--dry-run exits 0` contract asserted elsewhere
+        // in this file's tests — trading a documented exit code for a message
+        // that has already been printed above.
+        process.stderr.write(
+            `\n(dry-run) the ${target} cut WOULD BE REFUSED for the reason above. ` +
+                'Previewing only; exit code unchanged.\n',
+        );
+        return;
+    }
+    die(
+        `refusing the ${target} cut: the scheduled-deprecations table in docs/MIGRATION.md ` +
+            'has a row due at or before this major, or one that cannot be resolved. Act on ' +
+            "it — perform the removal in its own change, or revise the row's commitment and " +
+            'record why the surface stays — then re-run.',
+    );
+}
+
 // ─── preflight ────────────────────────────────────────────────────────────────
 
 /**
@@ -2578,6 +2665,13 @@ function main(argv: readonly string[] | null = null): number {
     }
     parse_version(target);
 
+    // Runs in dry-run too — a preview that hides the one condition which will
+    // refuse the real run is the case previews are for — but REPORTS there
+    // instead of dying: `--dry-run returns 0` is a contract this file's tests
+    // assert, and breaking it to surface a warning would trade a documented
+    // exit code for a message.
+    assert_scheduled_deprecations_clear(target, undefined, { previewOnly: args.dry_run });
+
     if (!args.dry_run) {
         preflight(target, { resume: args.resume, ci: args.ci });
     }

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

@@ -14,15 +14,10 @@
       "maxLength": 64,
       "$comment": "Always the path-derived hyphen slug (`commit`, `council-default`) — identical to the `.claude/skills/` directory slug generated by condense.py. Agent-Skills-spec-compliant (lowercase letters, digits, hyphens; no leading/trailing/double hyphen; <=64 chars) so strict consumers like Zed accept projected SKILL.md entries. Colon names (`council:default`) are FORBIDDEN since the 2026-06 Zed fix; Claude Code's `/cluster:sub` invocation is path-derived from `commands/<cluster>/<sub>.md` and unaffected by this field."
     },
-    "tier": {
-      "type": "integer",
-      "enum": [0, 1, 2],
-      "description": "Command-surface tier per docs/contracts/command-surface-tiers.md. 0 = daily-driver (rendered in default `./agent-config --help`), 1 = power-user (rendered with `--tier=1`), 2 = maintenance/internal (rendered only with `--tier=all`). Default for new commands is 2 — promotion is gated by ADR criteria, never by author preference. BACK-COMPAT ALIAS since ADR-092: `visibility:` is the named source of truth (visible↔0, advanced↔1, internal↔2); `tier:` is retained as a derived integer alias and dual-emitted in the discovery manifest during the deprecation window. When both are present they MUST agree (enforced by lint_command_tiers.py)."
-    },
     "visibility": {
       "type": "string",
       "enum": ["visible", "advanced", "internal"],
-      "description": "Command-surface visibility (ADR-092) — the NAMED source of truth that supersedes the integer `tier:` proxy. `visible` = daily-driver (default `./agent-config --help`, ↔ tier 0), `advanced` = power-user (`--tier=1`, ↔ tier 1), `internal` = maintenance/hidden (`--tier=all` only, ↔ tier 2). Read by the surface classifier (commands ls/explain), the per-pack visible-command budget audit, and the discovery-manifest builder, each preferring `visibility:` and falling back to `tier:`. Default for new commands is `internal`; promotion is gated by ADR criteria per docs/contracts/command-surface-tiers.md."
+      "description": "Command-surface visibility per docs/contracts/command-surface-tiers.md — the sole command-surface classifier since the integer `tier:` alias was removed. `visible` = daily-driver (default `./agent-config --help`), `advanced` = power-user (`--tier=1`), `internal` = maintenance/hidden (`--tier=all` only). Read by the surface classifier (commands ls/explain), the per-pack visible-command budget audit, and the discovery-manifest builder. Default for new commands is `internal`; promotion is gated by ADR criteria. Presence and validity are enforced by lint_command_tiers.ts."
     },
     "description": {
       "type": "string",
@@ -71,7 +66,7 @@
       "type": "string",
       "minLength": 1,
       "maxLength": 200,
-      "description": "6.0.0-C Phase 2 routing metadata. One-line existence justification: the single user intent this command serves (e.g. 'Implement a ticket end-to-end from its tracker id'). REQUIRED on every visible command (tier 0/1), enforced by scripts/lint_command_routing.py; optional on internal (tier 2) commands. The human-readable answer to 'why does this command exist?'"
+      "description": "6.0.0-C Phase 2 routing metadata. One-line existence justification: the single user intent this command serves (e.g. 'Implement a ticket end-to-end from its tracker id'). REQUIRED on every visible command (visibility `visible`/`advanced`), enforced by scripts/lint_command_routing.py; optional on `internal` commands. The human-readable answer to 'why does this command exist?'"
     },
     "routes_to": {
       "type": "array",
@@ -81,7 +76,7 @@
         "type": "string",
         "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
       },
-      "description": "6.0.0-C Phase 2 routing metadata. The data backbone the routing-eval lint checks against: the skill slug(s), cluster sub-command(s), or command(s) this command routes the intent to (e.g. ['refine-ticket', 'feature-planning'] or ['fix-ci']). Always hyphen slugs — colon identifiers forbidden since the 2026-06 Zed fix. REQUIRED on every visible command (tier 0/1), enforced by scripts/lint_command_routing.py; optional on internal commands."
+      "description": "6.0.0-C Phase 2 routing metadata. The data backbone the routing-eval lint checks against: the skill slug(s), cluster sub-command(s), or command(s) this command routes the intent to (e.g. ['refine-ticket', 'feature-planning'] or ['fix-ci']). Always hyphen slugs — colon identifiers forbidden since the 2026-06 Zed fix. REQUIRED on every visible command (visibility `visible`/`advanced`), enforced by scripts/lint_command_routing.py; optional on `internal` commands."
     },
     "category": {
       "type": "string",
@@ -96,7 +91,7 @@
         "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$",
         "$comment": "Colon form stays ALLOWED here on purpose: `replaces` lists PRIOR names/aliases, and pre-2026-06 colon names (`commit:in-chunks`) are legitimate historical aliases."
       },
-      "description": "6.0.0-C Phase 2 routing metadata. The alias / deprecation link: prior command name(s) or alias(es) this command absorbs or supersedes. Empty array `[]` when the command replaces nothing (the common case). REQUIRED-as-a-key on every visible command (tier 0/1) so the routing surface is explicit, enforced by scripts/lint_command_routing.py; optional on internal commands. Distinct from `superseded_by` (set on the OLD shim pointing forward); `replaces` is set on the NEW canonical command pointing back."
+      "description": "6.0.0-C Phase 2 routing metadata. The alias / deprecation link: prior command name(s) or alias(es) this command absorbs or supersedes. Empty array `[]` when the command replaces nothing (the common case). REQUIRED-as-a-key on every visible command (visibility `visible`/`advanced`) so the routing surface is explicit, enforced by scripts/lint_command_routing.py; optional on `internal` commands. Distinct from `superseded_by` (set on the OLD shim pointing forward); `replaces` is set on the NEW canonical command pointing back."
     },
     "type": {
       "type": "string",
@@ -163,8 +158,8 @@
     },
     "model_tier": {
       "type": "string",
-      "enum": ["lite", "medium", "high", "inherit"],
-      "description": "Vendor-neutral capability band the command needs (ADR-035). Commands project as Claude skills, so high/medium/lite produce a native Claude `model:` (high→opus, medium→sonnet, lite→haiku) when model.auto_switch=auto; the generator owns that mapping. inherit keeps the session model. Non-Claude agents are suggestion-only. No vendor model names here."
+      "enum": ["lite", "medium", "high", "frontier", "inherit"],
+      "description": "Vendor-neutral capability band the command needs (ADR-035, amended by ADR-232). Commands project as Claude skills, so frontier/high/medium/lite produce a native Claude `model:` when model.auto_switch=auto; the generator owns that mapping. inherit keeps the session model. `frontier` is the band above the strongest generally-recommended one - opt-in and expected to stay rare. Non-Claude agents are suggestion-only. No vendor model names here."
     },
     "context": {
       "type": "string",

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

@@ -31,7 +31,16 @@
     "compatibility": {
       "type": "string",
       "maxLength": 500,
-      "description": "Agent-Skills spec field (optional): machine-readable declaration of environment requirements — system packages, network access, product/host constraints. Mirrors the public spec so media/doc skills can state requirements outside prose."
+      "deprecated": true,
+      "description": "DEPRECATED (announced 2026-08-14, removal maintainer-scheduled — see docs/MIGRATION.md § Scheduled deprecations). Agent-Skills spec field (optional): free-text declaration of environment requirements — system packages, network access, product/host constraints. Superseded by `harness_compat` (the machine-readable class) plus `runtime_requires` (the probeable detail). Still accepted and still emitted so the public-spec mirror keeps working during the window; new skills declare `harness_compat` instead."
+    },
+    "harness_compat": {
+      "type": "string",
+      "enum": [
+        "consumer-installed-deps"
+      ],
+      "description": "Structured replacement for the free-text `compatibility` class claim: WHAT KIND of harness constraint the skill carries, in a form `doctor`/`preflight` can branch on. Distinct from `runtime_requires`, which names WHICH bins/env/network to probe — a Python module such as `python-docx` is not a PATH binary, so it has no `bins` entry and would otherwise be invisible to any machine reader. Deliberately single-valued: the enum is derived from the only two skills that ever declared `compatibility`, and both attest exactly one class. A second value is added when a skill attests one, never pre-emptively — a speculative vocabulary is the pro-forma-field risk this schema already refuses for `runtime_requires`. `consumer-installed-deps` = the skill runs only where the consumer has itself installed named third-party libraries or engines; this package ships no runtime for it.",
+      "$comment": "road-to-skill-ecosystem-executable-payloads Phase 1, under the maintainer's 2026-08-14 resolution of blocker `compatibility-deprecation-is-a-consumer-visible-decision`: ADDITIVE — `harness_compat` lands beside `compatibility`, which is NOT removed here; its removal is approved in principle and scheduled through docs/MIGRATION.md § Scheduled deprecations, never dropped silently. Enum evidence (verbatim, the complete population of `compatibility` users): docx-authoring — \"Requires a consumer-installed OOXML library (python-docx …) … Ships zero runtime in this package.\"; pdf-tools — \"Requires consumer-installed PDF libraries: pypdf …, reportlab …; an OCR engine (e.g. tesseract) … Ships zero runtime in this package.\" Both state one class; the label generalises \"library\"/\"engine\" to \"deps\" and adds no claim neither text makes."
     },
     "runtime_requires": {
       "type": "object",
@@ -159,9 +168,10 @@
         "lite",
         "medium",
         "high",
+        "frontier",
         "inherit"
       ],
-      "description": "Vendor-neutral capability band the skill needs (ADR-035). high/medium/lite project to a native Claude `model:` (high→opus, medium→sonnet, lite→haiku) when model.auto_switch=auto; the generator owns that mapping exclusively. inherit keeps the session model. Non-Claude agents are suggestion-only — the model-recommendation rule names the tier and the agent resolves its own model. No vendor model names here."
+      "description": "Vendor-neutral capability band the skill needs (ADR-035, amended by ADR-232). frontier/high/medium/lite project to a native Claude `model:` when model.auto_switch=auto; the generator owns that mapping exclusively. inherit keeps the session model. `frontier` means reasoning capability above the strongest generally-recommended band - opt-in and expected to stay rare, so work that genuinely needs it says so instead of inheriting it silently. Non-Claude agents are suggestion-only - the model-recommendation rule names the tier and the agent resolves its own model. No vendor model names here."
     },
     "context": {
       "type": "string",

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

@@ -34,8 +34,8 @@
     },
     "model_tier": {
       "type": "string",
-      "enum": ["lite", "medium", "high", "inherit"],
-      "description": "Vendor-neutral capability band (ADR-034/035). high/medium/lite project to a native Claude `model:` (high→opus, medium→sonnet, lite→haiku) via model_tier.ts; `inherit` is a documented passthrough sentinel (→ CC `model: inherit`), not a new mapping."
+      "enum": ["lite", "medium", "high", "frontier", "inherit"],
+      "description": "Vendor-neutral capability band (ADR-034/035, amended by ADR-232). frontier/high/medium/lite project to a native Claude `model:` via model_tier.ts; `inherit` is a documented passthrough sentinel (→ CC `model: inherit`), not a new mapping. `frontier` is the band above the strongest generally-recommended one - opt-in, expected to stay rare, and never the resolution of `inherit`."
     },
     "effort": {
       "type": "string",

package/src/scripts/session_eol_report.ts

@@ -61,6 +61,33 @@ export interface EolReport {
         compact_summary_records: number;
         marker_drift: boolean;
     };
+    /**
+     * State-destroyed vs state-captured, as ONE reading
+     * (road-to-inbox-harvest-2026-08-d-context-ledger Step 2.2).
+     *
+     * Before this, a compaction count and an advisory count sat in two places
+     * and nobody correlated them, so "how often was state destroyed with no
+     * capture in front of it" had no answer at all.
+     *
+     * HONEST LIMIT, stated in the shape rather than in prose only: the two
+     * sides come from different corpora — compactions are scanned out of
+     * transcripts, the advisory stamps live in per-session state files under a
+     * hashed key — and no field joins a transcript to its state file. So this
+     * is an AGGREGATE comparison over the same store, not a per-session join,
+     * and `join_basis` says so on every emitted report. A reader may compare
+     * the totals; a reader may NOT conclude that a specific compaction lacked
+     * a capture.
+     */
+    capture: {
+        /** Session-eol state files found. `null` ⇒ the directory is absent. */
+        state_files: number | null;
+        /** State files carrying an `advisory_fired_at` stamp. */
+        advisory_fired: number;
+        /** State files that additionally recorded "advised, but no envelope". */
+        advised_without_envelope: number;
+        /** Always `"aggregate"` today. See the doc comment. */
+        join_basis: 'aggregate';
+    };
     /** Pearson r of file bytes vs final context tokens over the readable set. */
     bytes_tokens_pearson_r: number | null;
     threshold_crossings: Record<string, number>;
@@ -130,6 +157,47 @@ export function scanSessionFile(file: string): SessionSummary | null {
     return { file, bytes, counters, last_ts };
 }
 
+/** Where `session_eol_hook` persists its per-session state (gitignored). */
+export const SESSION_EOL_STATE_REL = path.join('agents', 'runtime', 'state', 'session-eol');
+
+/**
+ * The capture side of the Step-2.2 reading.
+ *
+ * `state_files: null` distinguishes "the directory is not there" from "it is
+ * there and empty" — an instrument that reports 0 for both cannot tell a quiet
+ * estate from one it cannot see, which is the failure the sibling ledger fixed
+ * for its own open-record set.
+ */
+export function scanCaptureState(root: string): EolReport['capture'] {
+    const dir = path.join(root, SESSION_EOL_STATE_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+    } catch {
+        return { state_files: null, advisory_fired: 0, advised_without_envelope: 0, join_basis: 'aggregate' };
+    }
+
+    let advisoryFired = 0;
+    let advisedWithoutEnvelope = 0;
+    for (const name of names) {
+        try {
+            const parsed: unknown = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
+            if (typeof parsed !== 'object' || parsed === null) continue;
+            const rec = parsed as Record<string, unknown>;
+            if (typeof rec['advisory_fired_at'] === 'string') advisoryFired++;
+            if (typeof rec['missing_envelope_warned_at'] === 'string') advisedWithoutEnvelope++;
+        } catch {
+            // A torn or hand-edited state file is data we do not have.
+        }
+    }
+    return {
+        state_files: names.length,
+        advisory_fired: advisoryFired,
+        advised_without_envelope: advisedWithoutEnvelope,
+        join_basis: 'aggregate',
+    };
+}
+
 export function buildReport(root: string, now: Date = new Date()): EolReport {
     const files = listTranscriptFiles({ root });
     const sessions: SessionSummary[] = [];
@@ -176,6 +244,7 @@ export function buildReport(root: string, now: Date = new Date()): EolReport {
             compact_summary_records: summaryRecords,
             marker_drift: summaryRecords !== allEvents.length,
         },
+        capture: scanCaptureState(root),
         bytes_tokens_pearson_r: pearson(
             withUsage
                 .filter((s) => (s.counters.final_context_tokens as number) > 1_000)
@@ -216,6 +285,18 @@ export function renderText(r: EolReport): string {
             `  trigger pre-tokens: min=${fmt(c.pre_tokens.min)} median=${fmt(c.pre_tokens.median)} max=${fmt(c.pre_tokens.max)}`,
         );
     }
+    // Step 2.2: the capture side, printed directly under the destruction side
+    // so the two are read together. `join_basis` is printed every time — a
+    // reader must not mistake an aggregate comparison for a per-session join.
+    const cap = r.capture;
+    if (cap.state_files === null) {
+        lines.push(`  capture: no session-eol state directory — capture side UNOBSERVED (not zero)`);
+    } else {
+        lines.push(
+            `  capture: ${cap.advisory_fired} of ${cap.state_files} state file(s) advised, ` +
+                `${cap.advised_without_envelope} advised with no envelope [join: ${cap.join_basis}]`,
+        );
+    }
     if (c.post_tokens) {
         lines.push(`  post-tokens median=${fmt(c.post_tokens.median)}`);
     }

package/src/scripts/skill_linter.ts

@@ -254,6 +254,42 @@ const EXTERNAL_EXECUTION_HANDLERS = new Set(['shell', 'php', 'node']);
  * span lines and accept a bare key whose value sits somewhere below it.
  */
 const RUNTIME_REQUIRES_BLOCK_PATTERN = /^runtime_requires:[ \t]*(\{.*)?$/m;
+
+/**
+ * The deprecated free-text `compatibility:` key and its structured successor
+ * `harness_compat:`, both top-level. Anchored at column 0 so a `compatibility:`
+ * nested inside another block (or the word inside a quoted description) is not
+ * read as the frontmatter key — the same reason the neighbouring patterns above
+ * use `^` rather than a bare substring test. A value is required after the colon
+ * so a bare key with the value on the next line is not counted as a declaration.
+ */
+const COMPATIBILITY_KEY_PATTERN = /^compatibility:[ \t]*\S/m;
+const HARNESS_COMPAT_KEY_PATTERN = /^harness_compat:[ \t]*\S/m;
+
+/**
+ * `safety_mode: strict` is a claim made in the frontmatter about a skill whose
+ * execution path may mutate something. Nothing checked that the body honours it,
+ * so the claim could be pure metadata. These patterns recognise the two shapes
+ * the action-reference split allows (`skill-writing` § Action-reference split):
+ * an inline precondition that gates the write, or a deferral of the write-path
+ * steps into the skill's own `references/`.
+ *
+ * Deliberately a warning over a phrase list rather than an error over a required
+ * section: a skill that gates its write path some third way is doing the right
+ * thing, and a hard gate over a corpus of one strict skill would be a gate that
+ * mostly cannot fail — the defect class `road-to-skill-ecosystem-gate-integrity`
+ * exists to remove.
+ */
+const STRICT_WRITE_GATE_PATTERNS = [
+    /--dry-run/i,
+    /\bnever silent[- ]run/i,
+    /\bpropose,? never\b/i,
+    /\bconfirms? before\b/i,
+    /\bexplicit (?:user )?confirmation\b/i,
+    /\basks? (?:the user )?(?:first|before)\b/i,
+];
+const SKILL_REFERENCE_DEFERRAL_PATTERN = /\]\(\.{0,2}\/?references\//;
+
 const VALID_EXECUTION_FIELDS = new Set([
     'type',
     'handler',
@@ -1295,7 +1331,7 @@ function lint_wing4_boundaries(text: string): Issue[] {
  * for an optional parameter — a future caller that forgets it gets a confident
  * error about a declaration it never looked for.
  */
-function lint_execution_metadata(execution: ExecutionBlock, frontmatter: string): Issue[] {
+function lint_execution_metadata(execution: ExecutionBlock, frontmatter: string, body = ''): Issue[] {
     const issues: Issue[] = [];
 
     const execType = execution.type;
@@ -1370,6 +1406,29 @@ function lint_execution_metadata(execution: ExecutionBlock, frontmatter: string)
         );
     }
 
+    // road-to-skill-ecosystem-executable-payloads Phase 5 — the action-reference
+    // split. A strict-mode skill either gates its write path inline, or says it
+    // does not define the mutating workflow and defers those steps to its own
+    // `references/` behind a precondition. Neither present → the strict claim is
+    // frontmatter only, and the body reads like an ordinary skill.
+    if (
+        safetyMode === 'strict' &&
+        body !== '' &&
+        !STRICT_WRITE_GATE_PATTERNS.some((p) => p.test(body)) &&
+        !SKILL_REFERENCE_DEFERRAL_PATTERN.test(body)
+    ) {
+        issues.push(
+            new Issue(
+                'warning',
+                'strict_mode_missing_write_gate',
+                "execution.safety_mode is 'strict' but the body names no precondition on the write " +
+                    'path and defers no write-path steps to the skill\'s references/ — state the gate ' +
+                    'inline (propose-then-confirm, --dry-run) or defer it, per skill-writing ' +
+                    '§ Action-reference split',
+            ),
+        );
+    }
+
     const timeout = execution.timeout_seconds;
     if (timeout !== undefined) {
         if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout <= 0) {
@@ -1583,9 +1642,30 @@ export function lint_skill(p: string, text: string, absPath: string | null = nul
             }
         }
 
+        // `compatibility:` is deprecated in favour of the structured
+        // `harness_compat:` (schema, 2026-08-14). The field is NOT removed — the
+        // schema still accepts it and both existing users still carry it — so this
+        // is a warning, not an error: its job is to stop NEW adoption during the
+        // window, which is the only thing a deprecation notice with no gate cannot
+        // do. Regex, not a YAML parse, to match the file's existing convention.
+        if (
+            COMPATIBILITY_KEY_PATTERN.test(frontmatter) &&
+            !HARNESS_COMPAT_KEY_PATTERN.test(frontmatter)
+        ) {
+            issues.push(
+                new Issue(
+                    'warning',
+                    'deprecated_compatibility_field',
+                    "Frontmatter declares the deprecated free-text 'compatibility:' without the structured " +
+                        "'harness_compat:' that supersedes it — add harness_compat (see skill.schema.json and " +
+                        'docs/MIGRATION.md § Scheduled deprecations); compatibility stays accepted until removal',
+                ),
+            );
+        }
+
         const execution = parseExecutionBlock(frontmatter);
         if (execution !== null) {
-            issues.push(...lint_execution_metadata(execution, frontmatter));
+            issues.push(...lint_execution_metadata(execution, frontmatter, text.replace(FRONTMATTER_PATTERN, '')));
         }
 
         const tierMatch = TIER_PATTERN.exec(frontmatter);