shapeup-sdlc 1.6.3 → 3.0.0

package/{skills/tech-lead/scripts/budget-check.mjs → kernel/verify/budget.mjs}

@@ -1,21 +1,15 @@
 #!/usr/bin/env node
 // THE THIRD BREAKER — wall clock. Derived, never claimed; checked at every round boundary.
 //
-// WHY THIS EXISTS (measured, and it corrects an earlier diagnosis).
+// WHY THIS EXISTS (and it corrects an earlier diagnosis).
 //
-// SDD harness benchmark, F3 (wiring trap, Sonnet 5): this harness was killed at the declared
-// 1800 s cap and published as a DNF. The obvious reading — the one the first write-up implied —
-// was that it had stalled at a gate with no human to sign off.
+// A run killed at an external time cap produces nothing scoreable, and the obvious reading is that
+// it stalled at a gate with no human to sign off.
 //
-// Re-reading the retained transcript with transcript-level metrics says otherwise, and the
-// numbers are not close:
-//
-//     327 assistant turns · 262 tool calls · 130 work calls · 37 file writes
-//     19 gate markers, last gate reached L3 · narration_ratio 0.047 · stall_signals 0
-//
-// It was not waiting. It was the LEAST talkative shapeup run in the whole matrix and one of the
-// busiest rows in the dataset, and it got killed mid-loop at GATE L3 — Verdict & Loop. It ran
-// out of clock while genuinely working.
+// Reading the transcript with transcript-level metrics often says otherwise, and not narrowly:
+// steady turns, steady tool calls, steady file writes, gate markers advancing, a low narration
+// ratio and zero stall signals — a run killed mid-loop at GATE L3, Verdict & Loop. It was not
+// waiting. It ran out of clock while genuinely working.
 //
 // That makes the defect specific: **both existing breakers count events, not time.**
 // `round_budget` decrements once per round; `attempt_budget` decrements once per T0 attempt.
@@ -39,8 +33,8 @@
 // `off` and nothing changes. Existing runs behave exactly as before.
 //
 // USAGE
-//   node budget-check.mjs [--slug <slug>] [--cwd <root>] [--at <ISO>]   # status, exit 0
-//   node budget-check.mjs --strict …    # exit 6 when the breaker has tripped
+//   node `harness verify budget` [--slug <slug>] [--cwd <root>] [--at <ISO>]   # status, exit 0
+//   node `harness verify budget` --strict …    # exit 6 when the breaker has tripped
 //
 // Output: { status, elapsed_s, budget_s, remaining_s, used_fraction, action }
 //   status ∈ off | ok | warn | trip
@@ -48,9 +42,8 @@
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { localDir } from "./lib/paths.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { localDir } from "../lib/paths.mjs";
 
 /** Fraction of the budget at which the run should stop STARTING work it cannot finish. */
 export const WARN_AT = 0.75;
@@ -122,7 +115,7 @@ export function findRun(cwd, slug = null) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "budget-check.mjs [--slug <slug>] [--cwd <dir>] [--at <iso8601>] [--strict]",
+  usage: "harness.mjs verify budget [--slug <slug>] [--cwd <dir>] [--at <iso8601>] [--strict]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str" },
   cwd: { type: "path" },
@@ -130,12 +123,19 @@ export const ARGV_SPEC = {
   strict: { type: "flag" },
 };
 
-export function main() {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Check the wall-clock budget for the open run and report the breaker's verdict.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
   const run = findRun(cwd, args.slug ?? null);
   if (!run) {
-    console.error("no run receipt found — open the run with init-run.mjs first (GATE L0.1).");
+    console.error("no run receipt found — open the run with `harness init run` first (GATE L0.1).");
     process.exit(2);
   }
   const startedAt = Date.parse(run.receipt.started_at || "");
@@ -151,6 +151,3 @@ export function main() {
   process.exit(args.strict && result.status === "trip" ? 6 : 0);
 }
 
-if (isMain(import.meta.url)) {
-  main();
-}

package/kernel/verify/dispatch.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// Did THIS SESSION resolve that skill? — the canary's read half.
+//
+// `verify skills` proves the SKILL.md files exist at a root at a version. It cannot prove the
+// session will resolve that copy, because that is a property of how the CLI was launched:
+// `--plugin-dir`, an enabled marketplace install, the right version among several installed. Both
+// states the diagnosis names — installed-but-disabled, and wrong-version-loaded — pass a file check
+// green. Only a live dispatch answers the question, and this reads its evidence.
+//
+// THE EVIDENCE, and why it is evidence rather than a claim. A `Skill(...)` call whose name does not
+// resolve fires NO hook at all: the host rejects the name upstream of the hook layer. Measured, in a
+// live session with a sub-agent making the calls — not inferred. So a decision row from
+// `dispatch-receipt` naming a skill is proof that the name resolved, and its absence after a call
+// was attempted is proof that it did not. Nothing here trusts a sub-agent's report of what happened;
+// the sub-agent cannot write these rows.
+//
+// The canary deliberately dispatches with NO `--order`. It is testing name resolution, not doing
+// work: an order would mean a compiled order with no result sitting in `orders/`, which every reader
+// of that directory would then have to know about, and a canary that perturbs the run it is
+// clearing is not a preflight.
+//
+// Usage:  node kernel/harness.mjs verify dispatch --skill <worker> [--since <iso>] [--cwd <dir>] [--json]
+// Exit:   0 = this session dispatched that skill and the hook layer saw it · 1 = no such evidence
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { decisionsPath } from "../../hooks/lib/decision.mjs";
+
+/**
+ * Every decision row on disk, newest last. An unreadable or absent ledger is an empty list — an
+ * absence proves nothing on its own, and the caller decides what that means.
+ *
+ * @param {string} cwd - Project root the ledger resolves against.
+ * @returns {object[]} Parsed rows; unparseable lines are dropped rather than throwing.
+ */
+export function decisionRows(cwd) {
+  const path = decisionsPath(cwd);
+  if (!existsSync(path)) return [];
+  try {
+    return readFileSync(path, "utf8").split("\n").filter((l) => l.trim())
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * Find evidence that a skill resolved in this checkout.
+ *
+ * The host reports skills namespaced (`shapeup-sdlc-plugin:orient`) and orders name them bare
+ * (`orient`), so a row matches on either form — the caller should not have to know which spelling
+ * the hook happened to capture.
+ *
+ * @param {object[]} rows - Decision rows, e.g. from {@link decisionRows}.
+ * @param {string} skill - The worker name to look for, bare or namespaced.
+ * @param {string} [since] - ISO timestamp; rows older than this are ignored. Without it, evidence
+ *   from any point in the checkout's history counts, which is why the canary always passes one.
+ * @returns {{resolved:boolean, rows:object[], considered:number}} The matching rows, newest last.
+ */
+export function dispatchEvidence(rows, skill, since = null) {
+  const bare = String(skill).slice(String(skill).lastIndexOf(":") + 1);
+  const floor = since ? Date.parse(since) : null;
+  const hits = rows.filter((r) => {
+    if (r.hook !== "dispatch-receipt" || !r.subject) return false;
+    const subj = String(r.subject);
+    const subjBare = subj.slice(subj.lastIndexOf(":") + 1).split("/")[0];
+    if (subjBare !== bare && subj !== skill) return false;
+    if (floor !== null && !Number.isNaN(floor) && !(Date.parse(r.at) >= floor)) return false;
+    return true;
+  });
+  return { resolved: hits.length > 0, rows: hits, considered: rows.length };
+}
+
+// ---------------------------------------------------------------------------
+/** The typed argv contract (see `./lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "harness.mjs verify dispatch --skill <worker> [--since <iso> | --within <seconds>] [--cwd <dir>] [--json]",
+  _: { arity: 0, max: 0 },
+  skill: { type: "str", required: true },
+  since: { type: "str" },
+  // `--within` exists because the canary's caller cannot compute a timestamp. A Workflow script may
+  // not call `Date.now()` — it would break resume — so a control script asking "was this dispatched
+  // JUST NOW" has no clock of its own. Without a window the check answers "ever, in this checkout",
+  // which a project that once had the plugin loaded satisfies forever: the canary would pass on the
+  // strength of a run from last month. The kernel has a clock; it does the arithmetic.
+  within: { type: "int", min: 1 },
+  cwd: { type: "path" },
+  json: { type: "flag" },
+};
+
+/**
+ * Report whether this session has been observed dispatching a named skill.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when the evidence exists, 1 when it does not.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const since = args.since || (args.within ? new Date(Date.now() - args.within * 1000).toISOString() : null);
+  const ev = dispatchEvidence(decisionRows(cwd), args.skill, since);
+  if (args.json) {
+    console.log(JSON.stringify({ skill: args.skill, since, ...ev }, null, 2));
+  } else if (ev.resolved) {
+    const last = ev.rows[ev.rows.length - 1];
+    console.log(`✅ ${args.skill} resolved in this session — dispatch observed at ${last.at} (${ev.rows.length} row(s))`);
+  }
+  if (ev.resolved) process.exit(0);
+  console.error(`  ✗ verify dispatch: no evidence this session resolved "${args.skill}".`);
+  console.error(`    A Skill call whose name does not resolve fires no hook at all, so the absence of a`);
+  console.error(`    decision row after an attempted dispatch means the skill was never reached. Either the`);
+  console.error(`    plugin is not loaded in this session (\`claude --plugin-dir <repo>\`, or install and`);
+  console.error(`    enable it), or the dispatch was never attempted. ${ev.considered} decision row(s) scanned${since ? ` since ${since}` : ""}.`);
+  process.exit(1);
+}

package/{skills/tech-lead/scripts/validate-envelope.mjs → kernel/verify/envelope.mjs}

@@ -2,11 +2,11 @@
 // Envelope schema gate (pure-skill architecture v1.0, plan P0).
 //
 // The lesson already in the repo: structured artifacts + deterministic tooling beat prose
-// conventions (t0-verify.mjs is the most reliable component in the harness). This script makes
+// conventions (harness verify t0 is the most reliable component in the harness). This script makes
 // the WorkOrder/WorkResult ports mechanically checkable: a malformed order never reaches a
 // worker, a malformed result never reaches ingest.
 //
-// Zero dependencies, zero network — same discipline as the oracles and gate-l2.mjs. Implements
+// Zero dependencies, zero network — same discipline as the oracles and the GATE L2 block. Implements
 // the JSON-Schema subset the shipped schemas use (type, required, properties, items, enum,
 // pattern, $ref) rather than pulling in a validator dependency. $ref supports two forms:
 //   #/$defs/Name                       — a definition in the SAME schema document
@@ -14,7 +14,7 @@
 //                                        registry; resolved against the schema's own dir,
 //                                        falling back to skills/tech-lead/schemas/)
 //
-// Usage (CLI):    node skills/tech-lead/scripts/validate-envelope.mjs <envelope.json> <schema.json>
+// Usage (CLI):    node kernel/harness.mjs verify envelope <envelope.json> <schema.json>
 //                 exit 0 = valid, 1 = invalid (errors printed one per line)
 // Usage (hook):   PreToolUse on Skill|Agent — when the tool input carries `--order <path>`,
 //                 the order file is validated against schemas/work-order.schema.json; an
@@ -24,12 +24,11 @@
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { runHook, readStdin, settle } from "../../../hooks/lib/decision.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { runHook, readStdin, settle } from "../../hooks/lib/decision.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-export const SCHEMAS_DIR = resolve(HERE, "../schemas");
+export const SCHEMAS_DIR = resolve(HERE, "../../skills/tech-lead/schemas");
 
 /**
  * Validate a value against the JSON-Schema subset the envelope schemas use (type, required,
@@ -201,15 +200,21 @@ export function validateFile(envelopePath, schemaPath) {
  * the envelope arrives on stdin, so nothing here is consulted.
  */
 export const ARGV_SPEC = {
-  usage: "validate-envelope.mjs <envelope.json> <schema.json>   (no args → PreToolUse hook mode)",
+  usage: "harness.mjs verify envelope <envelope.json> <schema.json>   (no args → PreToolUse hook mode)",
   _: { arity: 2, max: 2, name: "<envelope.json> <schema.json>" },
 };
 
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  if (process.argv[2]) {
+/**
+ * Validate an envelope against its schema, or run as the PreToolUse gate when given no args.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export async function cli(rawArgv) {
+  if (rawArgv.length) {
     // CLI mode
-    const [envelopePath, schemaPath] = runArgs(ARGV_SPEC)._;
+    const [envelopePath, schemaPath] = runArgs(ARGV_SPEC, rawArgv)._;
     try {
       const { valid, errors } = validateFile(resolve(envelopePath), resolve(schemaPath));
       if (valid) {
@@ -223,7 +228,7 @@ if (isMainModule) {
       process.exit(1);
     }
   } else {
-    // Hook mode (PreToolUse). Deny contract identical to gate-l2.mjs, and — since v1.5 — the same
+    // Hook mode (PreToolUse). Deny contract identical to the GATE L2 block, and — since v1.5 — the same
     // receipt: `allow` carries evidence, so "validated the order and permitted it" is no longer
     // byte-identical to "this hook never ran" (hooks/lib/decision.mjs).
     await runHook("validate-envelope", async () => {
@@ -266,12 +271,12 @@ if (isMainModule) {
         },
       });
       if (!existsSync(orderPath)) {
-        deny(`WorkOrder gate — order file not found: ${orderPath}. Compile it first (compile-order.mjs) — a worker must never be dispatched against a dangling order.`, "order-missing");
+        deny(`WorkOrder gate — order file not found: ${orderPath}. Compile it first (harness compile) — a worker must never be dispatched against a dangling order.`, "order-missing");
       }
       try {
         const { valid, errors } = validateFile(orderPath, join(SCHEMAS_DIR, "work-order.schema.json"));
         if (!valid) {
-          deny(`WorkOrder gate — ${orderPath} fails schema validation: ${errors.slice(0, 5).join("; ")}. A malformed order never reaches a worker; fix the order (or compile-order.mjs) and re-dispatch.`, "schema-invalid");
+          deny(`WorkOrder gate — ${orderPath} fails schema validation: ${errors.slice(0, 5).join("; ")}. A malformed order never reaches a worker; fix the order (or harness compile) and re-dispatch.`, "schema-invalid");
         }
       } catch (e) {
         if (e?.name === "HookDecision") throw e;

package/{skills/tech-lead/scripts/lib → kernel/verify}/ratchet-tree.mjs

@@ -11,7 +11,7 @@
 // from code it did not write, cannot see the history of, and is told about only through error
 // strings. The paper's `revert(commit)` is the MORE COMMON branch, and it was the absent one.
 //
-// Under a ratchet there is one rule for both (see `t0-verify.mjs` → `decideStatus`): keep the tree
+// Under a ratchet there is one rule for both (see ``harness verify t0`` → `decideStatus`): keep the tree
 // when the score strictly improved, restore the last kept tree when it did not.
 //
 // NO COMMITS ON THE BRANCH UNDER TEST. The harness's standing convention is that it never writes
@@ -19,7 +19,7 @@
 // SHADOW REF — `refs/shapeup/<scope_id>/kept` — which is invisible to `git log`, `git status` and
 // every branch operation, and is reachable for `git restore` and for forensics afterwards.
 //
-// NON-REGRESSION (plan §7). Every operation here is best-effort: outside a git work tree, with no
+// NON-REGRESSION. Every operation here is best-effort: outside a git work tree, with no
 // `git` on PATH, or with no snapshot yet taken, the functions report `{ ok: false, reason }` and
 // the caller proceeds exactly as it does today. A ratchet that can break a build by failing to
 // take a snapshot would get the whole mechanism disabled, which costs more than it saves.
@@ -62,11 +62,16 @@ export function isRepo(cwd) {
 }
 
 /**
- * `keep` — publish the current working tree (including untracked files) as this scope's kept tree.
+ * `keep` — publish the current TRACKED working tree as this scope's kept tree.
  *
  * `git stash create` builds the stash commit WITHOUT touching the index, the working tree, or the
  * stash list; `update-ref` then points the shadow ref at it. Nothing the user can see changes.
  *
+ * TRACKED ONLY, and the limit is real rather than a nicety: `stash create` takes no `-u`, so a file
+ * the attempt CREATED is not in the snapshot. {@link restore} therefore cannot remove it — which is
+ * the behaviour that function already documents, stated here too so the pair reads honestly from
+ * either end.
+ *
  * @param {string} scopeId - Scope id the snapshot belongs to.
  * @param {string} cwd - Repository working directory.
  * @returns {{ok:boolean, ref?:string, sha?:string, reason?:string}} `ok:true` with the ref and the
@@ -88,25 +93,42 @@ export function snapshot(scopeId, cwd) {
 }
 
 /**
- * `revert` — restore the working tree from this scope's last kept snapshot.
+ * `revert` — restore THIS SCOPE'S OWN FILES from its last kept snapshot.
+ *
+ * `git restore --source=<ref> --worktree -- <pathspec>`: it rewrites tracked files back to the kept
+ * state and leaves the index and HEAD alone. It does NOT delete files created since the snapshot —
+ * removing a file the harness cannot prove it created is not a revert, it is data loss, and the
+ * attempt's own fixtures are what decide whether the leftover matters.
+ *
+ * THE PATHSPEC IS THE WHOLE POINT, and it used to be `.`. A scope's snapshot is a stash of the
+ * ENTIRE tree, so a repo-wide revert rolled every other scope back to whatever state it happened to
+ * be in when THIS scope last went green. With scopes building side by side that is silent
+ * cross-scope data destruction, and no other control can see it: `sandbox-guard` fences the Edit and
+ * Write tools, and this is a `git` subprocess. Measured directly — one scope's red attempt reverted
+ * a neighbour's committed file back to the baseline while the neighbour was still working in it.
  *
- * Deliberately `git restore --source=<ref> --worktree -- .`: it rewrites tracked files back to the
- * kept state and leaves the index and HEAD alone. It does NOT delete files created since the
- * snapshot — removing a file the harness cannot prove it created is not a revert, it is data loss,
- * and the attempt's own fixtures are what decide whether the leftover matters.
+ * Substrate globs are usable as git pathspecs unchanged (`src/parse/**`, `apps/web/cart/*.tsx`).
+ * `allowed` only, never `shared`: a shared path is by definition one another scope may also be
+ * writing, so reverting it is the very thing this bound exists to prevent. An empty pathspec
+ * restores NOTHING and says so, rather than falling back to a repo-wide revert — a scope that
+ * declares no writable surface has nothing of its own to roll back.
  *
  * @param {string} scopeId - Scope id whose kept tree should be restored.
  * @param {string} cwd - Repository working directory.
- * @returns {{ok:boolean, ref?:string, sha?:string, reason?:string}} `ok:true` when the tree was
- *   restored; `ok:false` with a reason when there is no snapshot yet (the first trial, by
- *   definition) or git refused.
+ * @param {string[]} [pathspec=[]] - The scope's `substrate.allowed` globs; the bound on what may be
+ *   rewritten.
+ * @returns {{ok:boolean, ref?:string, sha?:string, paths?:number, reason?:string}} `ok:true` when
+ *   the tree was restored; `ok:false` with a reason when there is no snapshot yet (the first trial,
+ *   by definition), no pathspec to bound the revert, or git refused.
  */
-export function restore(scopeId, cwd) {
+export function restore(scopeId, cwd, pathspec = []) {
   if (!isRepo(cwd)) return { ok: false, reason: "not a git work tree" };
+  const paths = (pathspec || []).filter((p) => typeof p === "string" && p.trim());
+  if (!paths.length) return { ok: false, reason: `no substrate pathspec for ${scopeId} — refusing a repo-wide revert` };
   const ref = keptRef(scopeId);
   const resolved = git(["rev-parse", "--verify", "--quiet", ref], cwd);
   if (!resolved.ok || !resolved.stdout) return { ok: false, reason: `no snapshot at ${ref}` };
-  const restored = git(["restore", `--source=${resolved.stdout}`, "--worktree", "--", "."], cwd);
+  const restored = git(["restore", `--source=${resolved.stdout}`, "--worktree", "--", ...paths], cwd);
   if (!restored.ok) return { ok: false, reason: restored.stderr || "git restore failed" };
-  return { ok: true, ref, sha: resolved.stdout };
+  return { ok: true, ref, sha: resolved.stdout, paths: paths.length };
 }

package/kernel/verify/skills.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// Worker-roster preflight — refuse a run whose workers are not on disk, before any spend.
+//
+// WHAT IT CATCHES. A dispatch against a plugin that is absent, disabled or a different version
+// returns `<tool_use_error>Unknown skill</tool_use_error>`, and the sub-agent then does the craft
+// itself from the prose already in its own prompt. `hooks/dispatch-receipt.mjs` makes that visible
+// at ingest; this makes it visible at `init run`, before a single sub-agent has been paid for.
+//
+// WHAT IT HONESTLY CANNOT DO, stated here because a check that overclaims is worse than no check.
+// It proves *these files exist at this root at this version*. It cannot prove the SESSION will
+// resolve that copy — that is a property of how the CLI was launched (`--plugin-dir`, an enabled
+// marketplace install, the right version among several), and only a live dispatch answers it. The
+// orchestrator's first leg is a canary dispatch whose receipt is required for exactly that reason;
+// this check and that canary are two halves, not two attempts at the same half.
+//
+// THE ROSTER IS DERIVED, NEVER SPELLED. It comes from `domain.schema.json#/$defs/WorkerName` — the
+// same enum that decides which workers a WorkOrder may be addressed to. A hand-written list beside
+// a schema enum is the drift this project exists to prevent: eight names beside a ten-member enum
+// reads perfectly and is wrong, and the two it would omit (`translator`, `coach`) are exactly the
+// ones a short run never reaches, so the omission would surface months later on the one run that did.
+//
+// THE ROOT IS DERIVED FROM THIS MODULE'S OWN LOCATION, not from `CLAUDE_PLUGIN_ROOT`: the env var is
+// not reliably exported into a sub-agent's shell, and the kernel that is executing is already inside
+// the plugin root. `--plugin-root <dir>` exists for fixtures, which must be able to describe a
+// broken installation without breaking the installation under test.
+//
+// Usage:  node kernel/harness.mjs verify skills [--plugin-root <dir>] [--json] [--quiet]
+// Exit:   0 = every worker resolved · 1 = one or more missing (named on stderr)
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runArgs } from "../lib/argv.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The plugin root, resolved from where this file actually is (`kernel/verify/` → repo root). */
+export const PLUGIN_ROOT = resolve(HERE, "../..");
+
+/**
+ * The complete worker roster, read from the schema that defines it.
+ *
+ * @param {string} [root=PLUGIN_ROOT] - Plugin root the schema is read from.
+ * @returns {string[]} Every member of `WorkerName`, in schema order.
+ * @throws {Error} When the schema is missing or does not carry the enum — a kernel that cannot find
+ *   its own domain registry has a broken installation, which is the very thing being checked.
+ */
+export function roster(root = PLUGIN_ROOT) {
+  const schemaPath = join(root, "skills/tech-lead/schemas/domain.schema.json");
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  const names = schema?.$defs?.WorkerName?.enum;
+  if (!Array.isArray(names) || !names.length) {
+    throw new Error(`${schemaPath} carries no $defs/WorkerName enum — the roster cannot be derived`);
+  }
+  return names;
+}
+
+/**
+ * Resolve every worker in the roster against a plugin root.
+ *
+ * A worker is present when its `SKILL.md` is readable. That is the file the host loads to answer a
+ * `Skill(...)` call, so its absence is the closest on-disk fact to "this dispatch will fail".
+ *
+ * @param {string} [root=PLUGIN_ROOT] - Plugin root to check.
+ * @returns {{root:string, version:(string|null), name:(string|null), workers:Array<{worker:string,
+ *   path:string, present:boolean}>, missing:string[]}} The full picture, including the version, so a
+ *   wrong-version run is legible in the trace instead of silently green.
+ */
+export function resolveWorkers(root = PLUGIN_ROOT) {
+  let version = null, name = null;
+  try {
+    const manifest = JSON.parse(readFileSync(join(root, ".claude-plugin/plugin.json"), "utf8"));
+    version = manifest.version ?? null;
+    name = manifest.name ?? null;
+  } catch { /* an unreadable manifest is reported as null, never as a failure of its own */ }
+  const workers = roster(root).map((worker) => {
+    const path = join(root, "skills", worker, "SKILL.md");
+    return { worker, path, present: existsSync(path) };
+  });
+  return { root, version, name, workers, missing: workers.filter((w) => !w.present).map((w) => w.worker) };
+}
+
+// ---------------------------------------------------------------------------
+/** The typed argv contract (see `./lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "harness.mjs verify skills [--plugin-root <dir>] [--json] [--quiet]",
+  _: { arity: 0, max: 0 },
+  "plugin-root": { type: "path" },
+  json: { type: "flag" },
+  quiet: { type: "flag" },
+};
+
+/**
+ * Check the worker roster resolves, and say which copy of the plugin answered.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when every worker resolved, 1 when any is missing.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  let report;
+  try {
+    report = resolveWorkers(args.pluginRoot ? resolve(args.pluginRoot) : PLUGIN_ROOT);
+  } catch (e) {
+    console.error(`  ✗ verify skills: ${e.message}`);
+    process.exit(1);
+  }
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (!args.quiet) {
+    // The root and the version are printed on the SUCCESS path too. A run against the wrong copy
+    // of the plugin is green by every other measure; printing which copy answered is the only way
+    // that shows up in a trace someone reads later.
+    console.log(`plugin: ${report.name ?? "unknown"} ${report.version ?? "unknown version"}`);
+    console.log(`root:   ${report.root}`);
+    console.log(`workers: ${report.workers.length - report.missing.length}/${report.workers.length} resolved`);
+  }
+  if (report.missing.length) {
+    console.error(`  ✗ verify skills: ${report.missing.length} worker skill(s) missing under ${report.root}:`);
+    for (const w of report.workers.filter((x) => !x.present)) console.error(`      ${w.worker} — no SKILL.md at ${w.path}`);
+    console.error(`    This plugin copy cannot run the pipeline. Load the working copy with`);
+    console.error(`    \`claude --plugin-dir <repo>\`, or install/enable the plugin, then retry.`);
+    process.exit(1);
+  }
+  process.exit(0);
+}