@event4u/agent-config 11.0.0 → 12.0.0

package/src/scripts/lint_command_tiers.ts

@@ -1,20 +1,24 @@
 #!/usr/bin/env node
 /**
- * Lint slash-command frontmatter for the `tier:` key.
+ * Lint slash-command frontmatter for the `visibility:` key.
  *
  * Ported from the retired Python `src/scripts/lint_command_tiers.py` (ADR-200, Phase 4 /
- * Wave 4b). Mirrors the Python CLI contract exactly: same scan scope, file
- * ordering, finding messages, stdout/stderr split, and exit codes
- * (return-code bitwise-OR accumulation across the domain + per-root +
- * condensed-projection passes).
+ * Wave 4b). Keeps the Python CLI contract's shape: same scan scope, file
+ * ordering, stdout/stderr split, and exit codes (return-code bitwise-OR
+ * accumulation across the domain + per-root + condensed-projection passes).
  *
- * Hard-fails CI if any command lacks a `tier:` declaration or uses an unknown
- * tier value. The valid tier set is locked by
+ * The integer `tier:` alias this file was named for is GONE
+ * (road-to-tier-removal Phase 4): `visibility:` is now the sole command-surface
+ * classifier. The filename is retained because the gate id, its Taskfile entry,
+ * and the contract doc all key on it; only the checked key changed.
+ *
+ * Hard-fails CI if any command lacks a `visibility:` declaration or uses an
+ * unknown value. The valid set is locked by
  * docs/contracts/command-surface-tiers.md.
  *
  * Exit codes:
- *   0  every command declares a valid tier
- *   1  one or more commands missing or using an invalid tier
+ *   0  every command declares a valid visibility
+ *   1  one or more commands missing or using an invalid visibility
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -79,20 +83,13 @@ function COMMANDS_DIRS(): string[] {
 }
 
 const DOMAINS_DIR = path.join(REPO, "src", "domains");
-// Consumer-facing projection — must also carry tier so .augment/commands/
-// (which symlinks to dist/agent-src/commands/) renders the tier filter.
+// Consumer-facing projection — must also carry visibility so .augment/commands/
+// (which symlinks to dist/agent-src/commands/) renders the surface filter.
 const COMMANDS_DIR_CONDENSED = path.join(REPO, "dist/agent-src", "commands");
 
-const VALID_TIERS: ReadonlySet<string> = new Set(["0", "1", "2"]);
-// ADR-092: `visibility:` is the named source of truth; `tier:` is the
-// back-compat integer alias. Both are validated; when both are present they
-// MUST agree per this mapping.
+// ADR-092 named `visibility:` the source of truth; road-to-tier-removal Phase 4
+// removed the integer `tier:` alias, so this set is the whole vocabulary.
 const VALID_VISIBILITIES: ReadonlySet<string> = new Set(["visible", "advanced", "internal"]);
-const TIER_TO_VISIBILITY: Readonly<Record<string, string>> = {
-  "0": "visible",
-  "1": "advanced",
-  "2": "internal",
-};
 
 export function parse_field(text: string, key: string): string | null {
   if (!text.startsWith("---\n")) {
@@ -116,15 +113,13 @@ export function parse_field(text: string, key: string): string | null {
   return null;
 }
 
-export function parse_tier(text: string): string | null {
-  return parse_field(text, "tier");
-}
-
 /**
  * Validate the visibility field (ADR-092). Returns an error string or null.
  *
- * Requires a present + valid visibility, and consistency with the tier alias
- * whenever both are declared.
+ * Requires a present + valid visibility. The tier↔visibility consistency clause
+ * is gone with the alias itself (road-to-tier-removal Phase 4) — a stray `tier:`
+ * key is now rejected by `command.schema.json` (`additionalProperties: false`),
+ * not reconciled here.
  */
 export function visibility_error(text: string): string | null {
   const vis = parse_field(text, "visibility");
@@ -134,10 +129,6 @@ export function visibility_error(text: string): string | null {
   if (!VALID_VISIBILITIES.has(vis)) {
     return `invalid visibility '${vis}'`;
   }
-  const tier = parse_field(text, "tier");
-  if (tier !== null && tier in TIER_TO_VISIBILITY && TIER_TO_VISIBILITY[tier] !== vis) {
-    return `visibility '${vis}' disagrees with tier '${tier}' (expected '${TIER_TO_VISIBILITY[tier]}')`;
-  }
   return null;
 }
 
@@ -153,12 +144,6 @@ function stripChar(s: string, ch: string): string {
   return s.slice(start, end);
 }
 
-// Mirror Python's `print(sorted(set))` list repr: ['0', '1', ...].
-function sortedTiersRepr(): string {
-  const items = [...VALID_TIERS].sort();
-  return `[${items.map((s) => `'${s}'`).join(", ")}]`;
-}
-
 // Mirror Python's `print(sorted(VALID_VISIBILITIES))` list repr.
 function sortedVisibilitiesRepr(): string {
   const items = [...VALID_VISIBILITIES].sort();
@@ -184,43 +169,27 @@ export function lint(commands_dir: string, quiet = false): number {
     return 1;
   }
 
-  const missing: string[] = [];
-  const invalid: Array<[string, string]> = [];
   const vis_errors: Array<[string, string]> = [];
 
   for (const cmd of commands) {
     const rel = relPosix(cmd, commands_dir);
     const text = fs.readFileSync(cmd, "utf-8");
-    const tier = parse_tier(text);
-    if (tier === null) {
-      missing.push(rel);
-    } else if (!VALID_TIERS.has(tier)) {
-      invalid.push([rel, tier]);
-    }
     const ve = visibility_error(text);
     if (ve !== null) {
       vis_errors.push([rel, ve]);
     }
   }
 
-  if (missing.length > 0 || invalid.length > 0 || vis_errors.length > 0) {
+  if (vis_errors.length > 0) {
     process.stderr.write(
-      `❌  lint_command_tiers: ${missing.length} missing tier, ` +
-        `${invalid.length} invalid tier, ${vis_errors.length} visibility ` +
+      `❌  lint_command_tiers: ${vis_errors.length} visibility ` +
         `(of ${commands.length} commands)\n`,
     );
-    for (const name of missing) {
-      process.stderr.write(`    missing tier: ${name}\n`);
-    }
-    for (const [name, tier] of invalid) {
-      process.stderr.write(`    invalid tier '${tier}': ${name}\n`);
-    }
     for (const [name, err] of vis_errors) {
       process.stderr.write(`    ${err}: ${name}\n`);
     }
     process.stderr.write(
-      `    valid tiers: ${sortedTiersRepr()}; ` +
-        `valid visibility: ${sortedVisibilitiesRepr()}\n`,
+      `    valid visibility: ${sortedVisibilitiesRepr()}\n`,
     );
     process.stderr.write(
       "    contract: docs/contracts/command-surface-tiers.md (ADR-092)\n",
@@ -231,7 +200,7 @@ export function lint(commands_dir: string, quiet = false): number {
   if (!quiet) {
     process.stdout.write(
       `✅  lint_command_tiers: ${commands.length} commands, ` +
-        "all tier + visibility values valid\n",
+        "all visibility values valid\n",
     );
   }
   return 0;
@@ -246,35 +215,20 @@ export function lint_domain_sources(quiet = false): number {
     );
     return 1;
   }
-  const missing: string[] = [];
-  const invalid: Array<[string, string]> = [];
   const vis_errors: Array<[string, string]> = [];
   for (const c of commands) {
     const rel = relPosix(c, REPO);
     const text = fs.readFileSync(c, "utf-8");
-    const t = parse_tier(text);
-    if (t === null) {
-      missing.push(rel);
-    } else if (!VALID_TIERS.has(t)) {
-      invalid.push([rel, t]);
-    }
     const ve = visibility_error(text);
     if (ve !== null) {
       vis_errors.push([rel, ve]);
     }
   }
-  if (missing.length > 0 || invalid.length > 0 || vis_errors.length > 0) {
+  if (vis_errors.length > 0) {
     process.stderr.write(
-      `❌  lint_command_tiers: ${missing.length} missing tier, ` +
-        `${invalid.length} invalid tier, ${vis_errors.length} visibility ` +
+      `❌  lint_command_tiers: ${vis_errors.length} visibility ` +
         `(of ${commands.length} domain commands)\n`,
     );
-    for (const name of missing) {
-      process.stderr.write(`    missing tier: ${name}\n`);
-    }
-    for (const [name, tier] of invalid) {
-      process.stderr.write(`    invalid tier '${tier}': ${name}\n`);
-    }
     for (const [name, err] of vis_errors) {
       process.stderr.write(`    ${err}: ${name}\n`);
     }
@@ -283,7 +237,7 @@ export function lint_domain_sources(quiet = false): number {
   if (!quiet) {
     process.stdout.write(
       `✅  lint_command_tiers: ${commands.length} domain commands, ` +
-        "all tier + visibility values valid\n",
+        "all visibility values valid\n",
     );
   }
   return 0;
@@ -354,7 +308,7 @@ export function main(): number {
   }
   // The condensed projection is the consumer-facing tree (via the
   // .augment/commands → dist/agent-src/commands symlink). It must also
-  // carry tier so the surface stays uniform.
+  // carry visibility so the surface stays uniform.
   if (_isDir(COMMANDS_DIR_CONDENSED)) {
     rc |= lint(COMMANDS_DIR_CONDENSED, QUIET);
   }

package/src/scripts/lint_originality.ts

@@ -20,6 +20,8 @@
  *
  * Modes:
  *   (no args)          full pairwise audit → agents/reports/originality.{json,md}
+ *   --base <ref>       the revision the change set is measured against; defines
+ *                      what counts as ESTABLISHED scaffold (see below)
  *   --changed <f...>   CI path: each changed file vs the whole same-class corpus
  *                      AND vs the other changed files of its class
  *
@@ -41,7 +43,7 @@
  *      it drifts as commands/skills are added or removed. Re-run the full audit
  *      after any large corpus change; do not treat 40 % as invariant.
  *   2. Adversarial batch masking. In `--changed` mode the boilerplate set is
- *      computed from the corpus MINUS the change set, so a batch of ≥ _dfFloor
+ *      derived from the ESTABLISHED corpus, so a batch of ≥ _dfFloor
  *      near-identical re-skins submitted together cannot classify its own shared
  *      shingles as boilerplate (see `_changed`). The full-audit sweep (no
  *      "changed" notion) does NOT have this guard — a batch of ≥ floor identical
@@ -51,8 +53,35 @@
  *      computes the PR's changed corpus files and runs `--changed` on them
  *      (empty changed set reports INCONCLUSIVE, never a pass).
  *
+ *      HOW "established" is resolved, and why it changed (2026-08-14):
+ *      With `--base <ref>` the established corpus is the class corpus AS IT
+ *      EXISTS AT THAT REVISION — content read from git, not from the worktree.
+ *      Without it, the older approximation applies: on-disk corpus MINUS the
+ *      change set.
+ *
+ *      That approximation has a degeneracy the base-ref form does not. When a
+ *      change set covers (nearly) the whole class — a mechanical edit such as
+ *      dropping one frontmatter key from every command — "corpus minus change
+ *      set" is EMPTY, no shingle clears the DF floor, nothing is scaffold, and
+ *      the class's shared skeleton is scored as authored overlap. Measured on
+ *      road-to-tier-removal Phase 4: the full audit reported worst 40 % / 0
+ *      failures, while `--changed` over the same 200 unmodified-in-substance
+ *      files reported 67.9 % and 3 failures — byte-identical on the base
+ *      revision's own content, so the delta was entirely the masking collapse.
+ *
+ *      The base-ref form does NOT weaken the guard, and it is worth being
+ *      precise about why rather than claiming more. Both forms close the
+ *      re-skin-batch axis, for different reasons: the old one excludes the
+ *      change set outright, the new one relies on those files' shared shingles
+ *      being absent from the base content (a NEW file contributes nothing at
+ *      all; a REWRITTEN file contributes only its OLD text). Either way a
+ *      batch cannot promote its own new shingles to scaffold. What changes is
+ *      only the degenerate case: an established corpus that is empty because
+ *      the change set swallowed it.
+ *
  * Exit 0 clean/warn · 1 fail · 2 usage.
  */
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -176,7 +205,11 @@ function _templateShingles(spec: ClassSpec): Set<string> {
 }
 
 function _load(abs: string, cls: ArtifactClass, tmpl: Set<string>): Artifact {
-    const text = fs.readFileSync(abs, 'utf-8');
+    return _loadText(fs.readFileSync(abs, 'utf-8'), abs, cls, tmpl);
+}
+
+/** `_load` over supplied text — used to load a file's content at a base ref. */
+function _loadText(text: string, abs: string, cls: ArtifactClass, tmpl: Set<string>): Artifact {
     const raw = shingles(text, K);
     // Subtract shared scaffold — a shingle also present in the class template
     // is boilerplate, not authored content.
@@ -332,14 +365,41 @@ function _writeReport(byClass: Map<ArtifactClass, Artifact[]>, pairs: Pair[], di
 
 // --- changed mode ------------------------------------------------------------
 
-function _changed(files: string[]): { pairs: Pair[]; fails: number } {
-    // The boilerplate DF set is derived from the ESTABLISHED corpus only — the
-    // change set under review is excluded. Without this, a batch of ≥ _dfFloor
-    // near-identical re-skins submitted together would lift its OWN shared
-    // shingles over the floor, be reclassified as boilerplate, subtracted from
-    // every copy, and score 0 against each other — the gate blinds itself on
-    // exactly the attack it exists to catch. "What is scaffold" must be defined
-    // by the corpus as it stands, never by the diff proposing to change it.
+/**
+ * A corpus file's content at `ref`, or null when the file does not exist there.
+ *
+ * Null is the load-bearing case: a file absent at the base revision is NEW in
+ * this change set, so it contributes nothing to the scaffold definition. That is
+ * what keeps a batch of re-skinned newcomers from masking itself.
+ *
+ * A git failure is indistinguishable from "absent" at this layer, and both
+ * resolve the same conservative way — the file is excluded from scaffold, which
+ * can only make the gate stricter, never blinder.
+ */
+function _textAtRef(ref: string, relpath: string): string | null {
+    const r = spawnSync('git', ['show', `${ref}:${relpath}`], {
+        cwd: ROOT,
+        encoding: 'utf-8',
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    if (r.status !== 0 || typeof r.stdout !== 'string') return null;
+    return r.stdout;
+}
+
+function _changed(files: string[], base: string | null = null): { pairs: Pair[]; fails: number } {
+    // The boilerplate DF set is derived from the ESTABLISHED corpus only.
+    // Without this, a batch of ≥ _dfFloor near-identical re-skins submitted
+    // together would lift its OWN shared shingles over the floor, be
+    // reclassified as boilerplate, subtracted from every copy, and score 0
+    // against each other — the gate blinds itself on exactly the attack it
+    // exists to catch. "What is scaffold" must be defined by the corpus as it
+    // stands, never by the diff proposing to change it.
+    //
+    // `--base` makes "as it stands" literal: scaffold comes from the class
+    // corpus AT THAT REVISION. Without it we fall back to the older
+    // approximation (on-disk minus the change set), which is equivalent for a
+    // small change set but degenerates to an EMPTY established corpus when the
+    // change set covers the class — see the § 2 note in the module header.
     const changedRel = new Set(files.map((f) => _rel(path.resolve(ROOT, f))));
 
     // Build the corpus in RAW (template-subtracted, pre-DF) form per class so we
@@ -351,8 +411,18 @@ function _changed(files: string[]): { pairs: Pair[]; fails: number } {
         const tmpl = _templateShingles(spec);
         templateCache.set(spec.name, tmpl);
         const arts = spec.files().map((f) => _load(f, spec.name, tmpl));
-        // Established corpus = on-disk arts minus the change set.
-        const boiler = _boilerplateSet(arts.filter((a) => !changedRel.has(a.relpath)));
+        // Established corpus: at `base` when given (a file absent there is NEW
+        // and contributes no scaffold), else on-disk arts minus the change set.
+        const established =
+            base === null
+                ? arts.filter((a) => !changedRel.has(a.relpath))
+                : arts
+                      .map((a) => {
+                          const text = _textAtRef(base, a.relpath);
+                          return text === null ? null : _loadText(text, path.resolve(ROOT, a.relpath), spec.name, tmpl);
+                      })
+                      .filter((a): a is Artifact => a !== null);
+        const boiler = _boilerplateSet(established);
         for (const a of arts) _subtract(a, boiler);
         byClass.set(spec.name, arts);
         boilerByClass.set(spec.name, boiler);
@@ -404,13 +474,30 @@ export function main(argv?: string[]): number {
     }
     let quiet = false;
     let changedFiles: string[] | null = null;
+    let base: string | null = null;
     for (let i = 0; i < args.length; i++) {
         const a = args[i] as string;
         if (a === '--quiet') { quiet = true; }
+        else if (a === '--base') {
+            // `--changed` swallows the rest of argv, so `--base` must precede it.
+            const v = args[i + 1];
+            if (v === undefined || v.startsWith('-')) {
+                process.stderr.write(`--base needs a git ref\n${_usage()}`);
+                return 2;
+            }
+            base = v;
+            i += 1;
+        }
         else if (a === '--changed') { changedFiles = args.slice(i + 1).filter((x) => !x.startsWith('-')); break; }
         else if (a.startsWith('-')) { process.stderr.write(`unrecognized argument: ${a}\n${_usage()}`); return 2; }
         else { process.stderr.write(`unexpected argument: ${a} (did you mean --changed ${a}?)\n${_usage()}`); return 2; }
     }
+    if (base !== null && changedFiles === null) {
+        // Silently ignoring it would let a workflow think the base-anchored
+        // scaffold was in effect when the full audit does not use one at all.
+        process.stderr.write(`--base is only meaningful with --changed\n${_usage()}`);
+        return 2;
+    }
 
     // Asserted for BOTH modes, and before either: `--changed` compares each
     // candidate against the same corpus, so a dead root there reports "no
@@ -434,7 +521,7 @@ export function main(argv?: string[]): number {
     }
 
     if (changedFiles !== null) {
-        const { pairs, fails } = _changed(changedFiles);
+        const { pairs, fails } = _changed(changedFiles, base);
         if (pairs.length > 0) {
             const stream = fails > 0 ? process.stderr : process.stdout;
             stream.write(`lint_originality: ${pairs.length} overlap(s) ≥ WARN ${WARN}% (${fails} ≥ FAIL ${FAIL}%):\n`);
@@ -466,7 +553,7 @@ export function main(argv?: string[]): number {
 }
 
 function _usage(): string {
-    return 'usage: lint_originality [--quiet] [--changed <file...>]\n';
+    return 'usage: lint_originality [--quiet] [--base <ref>] [--changed <file...>]\n';
 }
 
 function _isCliEntry(): boolean {

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",

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",

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);