shapeup-sdlc 1.6.2

package/skills/tech-lead/schemas/gate-answers.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin/schemas/gate-answers.schema.json",
+  "title": "GateAnswerSet",
+  "description": "A pre-recorded set of PO decisions, one per gate, that lets a run cross its gates without a human in the loop. This is NOT 'gates off' — every gate still emits its block and still records a decision in the ledger; the decision's SOURCE becomes this file instead of a live human. That distinction is the whole design: an unattended run with no answer set stalls at the first ⏸ and burns its wall-clock budget (measured: shapeup-sdlc DNF at 1800s on benchmark F3), while an unattended run with one produces the same audit trail an interactive run does.",
+  "type": "object",
+  "required": ["version", "preset", "answers"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "preset": {
+      "type": "string",
+      "enum": ["ci", "guarded", "interactive", "custom"],
+      "description": "Provenance of this set. 'ci' = every gate pre-approved (headless); 'guarded' = low-risk gates pre-approved, judgment gates still ask; 'interactive' = nothing pre-approved (the default lane); 'custom' = hand-authored."
+    },
+    "authorized_by": {
+      "type": "string",
+      "description": "Who pre-approved these decisions. Free text, recorded verbatim in the round ledger so a shipped run can always name the human behind its sign-off."
+    },
+    "on_missing": {
+      "type": "string",
+      "enum": ["ask", "proceed", "abort"],
+      "default": "ask",
+      "description": "What to do at a gate this set has no answer for. 'abort' is the correct value for headless lanes: a fast attributable failure beats a silent stall that reads as a slow run."
+    },
+    "escalation": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Policy for a worker's structured ESCALATE (advisor-protocol), which is a gate in all but name.",
+      "properties": {
+        "default": {
+          "type": "string",
+          "enum": ["ask", "assume-and-record", "abort"],
+          "default": "ask"
+        },
+        "budget_per_scope_per_round": { "type": "integer", "minimum": 0, "default": 2 }
+      }
+    },
+    "answers": {
+      "type": "object",
+      "description": "Gate id → decision. Ids match the ⏸ GATE blocks the orchestrator emits.",
+      "additionalProperties": false,
+      "properties": {
+        "L0":     { "$ref": "#/definitions/answer" },
+        "L1a":    { "$ref": "#/definitions/answer" },
+        "L1a.5":  { "$ref": "#/definitions/answer" },
+        "L1b":    { "$ref": "#/definitions/answer" },
+        "L2":     { "$ref": "#/definitions/answer" },
+        "L3":     { "$ref": "#/definitions/answer" },
+        "QA":     { "$ref": "#/definitions/answer" },
+        "H":      { "$ref": "#/definitions/answer" },
+        "L4":     { "$ref": "#/definitions/answer" },
+        "COACH-1":{ "$ref": "#/definitions/answer" }
+      }
+    }
+  },
+  "definitions": {
+    "answer": {
+      "type": "object",
+      "required": ["decision"],
+      "additionalProperties": false,
+      "properties": {
+        "decision": {
+          "type": "string",
+          "enum": [
+            "proceed",
+            "ask",
+            "abort",
+            "loop",
+            "stop",
+            "ship",
+            "hold",
+            "accept-cut-list",
+            "ship-all",
+            "run",
+            "skip"
+          ],
+          "description": "proceed/ask/abort apply to review gates (L0, L1a, L1a.5, L1b, L2). L3 takes loop|stop|ask. QA takes run|skip. H takes accept-cut-list|ship-all|ask. L4 takes ship|hold|ask. COACH-1 takes skip|ask."
+        },
+        "note": {
+          "type": "string",
+          "description": "Recorded in the ledger next to the decision. This is where the pre-approval's reasoning lives, and it is the difference between an audited bypass and a rubber stamp."
+        },
+        "max_rounds": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "L3 only — caps the loop decision. Redundant with the run config on purpose: an answer set handed to a run must not be able to authorize more rounds than it names."
+        }
+      }
+    }
+  }
+}

package/skills/tech-lead/schemas/work-order.schema.json

@@ -0,0 +1,21 @@
+{
+  "$id": "work-order.schema.json",
+  "title": "WorkOrder",
+  "description": "The orchestrator → worker envelope (pure-skill architecture v1.0). Compiled by skills/tech-lead/scripts/compile-order.mjs, validated by validate-envelope.mjs before any worker dispatch. A worker depends only on this envelope — never on filesystem topology, run-state format, board schema, or another worker. Path: .shapeup/<slug>/orders/r<N>-a<M>.json (or <slug>/orders/<operation>.json for non-attempt work). Every record type and payload field is DEFINED CENTRALLY in domain.schema.json ($defs + x-payload-by-worker) — this file only shapes the envelope; it never re-defines a domain entity.",
+  "type": "object",
+  "required": ["schema_version", "order_id", "worker", "mode", "payload"],
+  "properties": {
+    "schema_version": { "type": "integer", "enum": [1] },
+    "order_id": {
+      "type": "string",
+      "description": "\"<slug>/r<N>-a<M>\" for build attempts, \"<slug>/<operation>[-r<N>]\" otherwise",
+      "pattern": "^[a-z0-9][a-z0-9-]*/[a-z0-9][A-Za-z0-9.-]*$"
+    },
+    "worker": { "$ref": "domain.schema.json#/$defs/WorkerName" },
+    "mode": { "type": "string", "enum": ["orchestrated", "standalone"] },
+    "operation": { "$ref": "domain.schema.json#/$defs/Operation" },
+    "interaction": { "$ref": "domain.schema.json#/$defs/Interaction" },
+    "substrate": { "$ref": "domain.schema.json#/$defs/Substrate" },
+    "payload": { "$ref": "domain.schema.json#/$defs/WorkOrderPayload" }
+  }
+}

package/skills/tech-lead/schemas/work-result.schema.json

@@ -0,0 +1,40 @@
+{
+  "$id": "work-result.schema.json",
+  "title": "WorkResult",
+  "description": "The worker → orchestrator envelope (pure-skill architecture v1.0). Everything a worker used to write into shared files it now RETURNS as data; skills/tech-lead/scripts/ingest-result.mjs performs the writes (tick AC boxes, flip board status, append execution log, propagate unblocks, append discoveries) deterministically, in one place. Path: .shapeup/<slug>/results/r<N>-a<M>.json. Every record type is DEFINED CENTRALLY in domain.schema.json — this file only shapes the envelope.",
+  "type": "object",
+  "required": ["schema_version", "order_id", "status"],
+  "properties": {
+    "schema_version": { "type": "integer", "enum": [1] },
+    "order_id": { "type": "string", "description": "Copied verbatim from the answered WorkOrder — the 1:1 join key." },
+    "worker": { "type": "string" },
+    "status": { "type": "string", "enum": ["done", "partial", "escalated", "failed"] },
+    "task_results": {
+      "type": "array",
+      "description": "Per-task outcome. ingest-result flips the board row, ticks GATE-verified AC boxes, and appends the Execution Log from these entries.",
+      "items": { "$ref": "domain.schema.json#/$defs/TaskResult" }
+    },
+    "files_touched": {
+      "type": "array",
+      "items": { "$ref": "domain.schema.json#/$defs/FileTouched" }
+    },
+    "escalates": {
+      "type": "array",
+      "description": "advisor-protocol ESCALATE blocks — the worker's one outward port.",
+      "items": { "$ref": "domain.schema.json#/$defs/Escalate" }
+    },
+    "discoveries": {
+      "type": "array",
+      "description": "Raw discovered lines. ingest-result appends them to the discovery ledger — the worker never touches the ledger itself.",
+      "items": { "$ref": "domain.schema.json#/$defs/Discovery" }
+    },
+    "verdict": { "$ref": "domain.schema.json#/$defs/Verdict" },
+    "artifacts": {
+      "type": "array",
+      "description": "Domain artifacts the worker wrote inside its substrate (spec docs, orient/ files, reports).",
+      "items": { "type": "string" }
+    },
+    "assumptions": { "type": "array", "items": { "type": "string" } },
+    "deviations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/skills/tech-lead/scripts/aegis-digest.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// AEGIS digester (design spec v1.1 §3.4/§4.5, PA6 countermeasure).
+//
+// Distills raw build/test/Playwright logs into {file, line, core_message} triples so a
+// task-executor's next attempt gets a few lines of signal instead of a full stack-trace dump.
+// Script-first by design: regex over known log formats is free (no model tokens); an
+// unrecognized line becomes a "raw" triple (file/line unknown) rather than being silently
+// dropped, so a Sonnet fallback (or a human) still has something to look at — this module never
+// invents a file:line it didn't find in the text.
+//
+// Zero dependencies, zero network — same discipline as oracles/*.
+
+import { isMain } from "./lib/is-main.mjs";
+import { runArgs } from "./lib/argv.mjs";
+
+const PATTERNS = [
+  // Node stack frame:  "    at fn (path/to/file.js:12:34)"  or  "    at path/to/file.js:12:34"
+  { re: /^\s*at\s+(?:[\w.$<>\[\] ]+\s+\()?(.+?):(\d+):\d+\)?\s*$/, kind: "stack-frame" },
+  // TAP/test-runner failure: "✗ some test name (path/to/file.js:12)"  or "not ok N - msg (file:line)"
+  { re: /^(?:✗|not ok\b.*?)[^()]*\((.+?):(\d+)\)\s*$/, kind: "test-failure" },
+  // ESLint/tsc style: "path/to/file.ts:12:34 - error TS2345: message"
+  { re: /^(.+?):(\d+):\d+\s*[-–]\s*(?:error|warning)\b.*$/, kind: "compiler-diagnostic" },
+  // Generic "Error: message" line followed later by a stack — capture the message alone.
+  { re: /^\s*(?:Error|TypeError|ReferenceError|AssertionError)\s*:\s*(.+)$/, kind: "error-message" },
+];
+
+/**
+ * Normalize a log line into a compact core message.
+ * @param {string} line - A raw log line.
+ * @returns {string} The line trimmed, whitespace-collapsed, and capped at 200 chars.
+ */
+function coreMessage(line) {
+  return line.trim().replace(/\s+/g, " ").slice(0, 200);
+}
+
+/**
+ * Distill raw build/test/Playwright log text into deduped {file,line,core_message,kind} triples —
+ * never inventing a file:line it did not find in the text.
+ * @param {string} rawText - The raw log output ("" / null tolerated).
+ * @returns {Array<{file:(string|null), line:(number|null), core_message:string, kind:string}>}
+ *   One triple per recognized failure/diagnostic (kind ∈ stack-frame|test-failure|
+ *   compiler-diagnostic|error-message); unmatched error messages become file-less triples.
+ */
+export function digest(rawText) {
+  const lines = (rawText || "").split(/\r?\n/);
+  const triples = [];
+  let pendingMessage = null;
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+
+    let matched = false;
+    for (const { re, kind } of PATTERNS) {
+      const m = line.match(re);
+      if (!m) continue;
+      matched = true;
+      if (kind === "error-message") {
+        pendingMessage = coreMessage(m[1]);
+        continue; // wait for the stack frame that follows to get a file:line
+      }
+      const file = m[1]?.trim();
+      const lineNo = m[2] ? Number(m[2]) : null;
+      triples.push({
+        file: file || null,
+        line: lineNo,
+        core_message: pendingMessage || coreMessage(line),
+        kind,
+      });
+      pendingMessage = null;
+      break;
+    }
+    if (!matched && pendingMessage) {
+      // an error message with no stack frame ever followed — keep it as file-less signal
+      triples.push({ file: null, line: null, core_message: pendingMessage, kind: "error-message" });
+      pendingMessage = null;
+    }
+  }
+  if (pendingMessage) {
+    triples.push({ file: null, line: null, core_message: pendingMessage, kind: "error-message" });
+  }
+
+  // De-duplicate identical (file, line, core_message) triples — repeated retries/log noise.
+  const seen = new Set();
+  return triples.filter((t) => {
+    const key = `${t.file}:${t.line}:${t.core_message}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+// --- CLI ---------------------------------------------------------------------
+/** The typed argv contract (see `./lib/argv.mjs`). A bare `-`, or nothing, means stdin. */
+export const ARGV_SPEC = {
+  usage: "aegis-digest.mjs [<log-file>|-]   (no file → stdin)",
+  _: { arity: 0, max: 1, name: "log-file" },
+};
+
+/**
+ * CLI entry: read a log from a file arg or stdin, print the digested triples as JSON, exit 0.
+ * @returns {Promise<void>} Resolves after printing.
+ */
+async function main() {
+  const arg = runArgs(ARGV_SPEC)._[0];
+  let raw;
+  if (arg && arg !== "-") {
+    const { readFileSync } = await import("node:fs");
+    raw = readFileSync(arg, "utf8");
+  } else {
+    raw = await new Promise((resolve) => {
+      let d = "";
+      process.stdin.on("data", (c) => (d += c));
+      process.stdin.on("end", () => resolve(d));
+      process.stdin.on("error", () => resolve(""));
+    });
+  }
+  const triples = digest(raw);
+  console.log(JSON.stringify(triples, null, 2));
+  process.exit(0);
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}

package/skills/tech-lead/scripts/budget-check.mjs

@@ -0,0 +1,156 @@
+#!/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).
+//
+// 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.
+//
+// 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.
+//
+// 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.
+// Neither can observe that round 1 has been running for twenty-nine minutes. A run can burn its
+// entire wall-clock budget without either breaker moving a single tick, and when the harness is
+// killed from outside, it ships nothing — not even the scopes that were already green.
+//
+// So the fix is not more gate automation (there was no stall to automate away). It is a third
+// breaker on the axis nobody was watching:
+//
+//     OUTER    round_budget     — rounds, the six-week-timebox analog
+//     INNER    attempt_budget   — T0 attempts per scope
+//     DEADLINE wall_clock_budget — elapsed seconds, this file
+//
+// Tripping the deadline breaker does NOT kill the run. It routes to GATE H (scope-hammer): the
+// census runs, the cut list is compared against the baseline, and whatever is green ships. That
+// is the entire difference between an external SIGTERM and a circuit breaker — one produces a
+// dash in every column, the other produces a smaller feature that works.
+//
+// Non-regression by construction: with no `wall_clock_budget_s` in the run config this reports
+// `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
+//
+// Output: { status, elapsed_s, budget_s, remaining_s, used_fraction, action }
+//   status ∈ off | ok | warn | trip
+//   action = the sentence the orchestrator must act on at the round boundary.
+
+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";
+
+/** Fraction of the budget at which the run should stop STARTING work it cannot finish. */
+export const WARN_AT = 0.75;
+
+/**
+ * Decide the breaker state from elapsed time against a budget. Pure, so the structural tests can
+ * assert every boundary without waiting for a clock.
+ *
+ * @param {number} elapsedS - Seconds since the run receipt was written.
+ * @param {number|null} budgetS - Configured wall-clock budget, or null/0 when the breaker is off.
+ * @returns {{status: string, elapsed_s: number, budget_s: number|null, remaining_s: number|null,
+ *            used_fraction: number|null, action: string}}
+ */
+export function evaluateBudget(elapsedS, budgetS) {
+  const elapsed = Math.max(0, Math.round(elapsedS));
+  if (!budgetS || budgetS <= 0) {
+    return {
+      status: "off", elapsed_s: elapsed, budget_s: null, remaining_s: null, used_fraction: null,
+      action: "No wall-clock budget configured — the deadline breaker is off. Round and attempt budgets still apply.",
+    };
+  }
+  const remaining = Math.round(budgetS - elapsed);
+  const used = Number((elapsed / budgetS).toFixed(3));
+
+  if (remaining <= 0) {
+    return {
+      status: "trip", elapsed_s: elapsed, budget_s: budgetS, remaining_s: remaining, used_fraction: used,
+      action:
+        "DEADLINE BREAKER TRIPPED. Do not start another build round or another scope. Go straight to " +
+        "GATE H (delegate scope-hammer with --breaker deadline): run the census, compare the shippable " +
+        "subset against the baseline, and ship what is green. A run killed from outside ships nothing; " +
+        "a run that trips its own breaker ships the part that works.",
+    };
+  }
+  if (used >= WARN_AT) {
+    return {
+      status: "warn", elapsed_s: elapsed, budget_s: budgetS, remaining_s: remaining, used_fraction: used,
+      action:
+        `${remaining}s of ${budgetS}s remain (${Math.round(used * 100)}% spent). Finish and T0-verify the ` +
+        "scope in flight; do NOT open a new scope or a new build round. The next boundary is where the " +
+        "breaker trips, and work started now will be cut at GATE H rather than shipped.",
+    };
+  }
+  return {
+    status: "ok", elapsed_s: elapsed, budget_s: budgetS, remaining_s: remaining, used_fraction: used,
+    action: `${remaining}s remain of ${budgetS}s. Proceed.`,
+  };
+}
+
+/** Locate the active run's receipt — the only place `started_at` is recorded. */
+export function findRun(cwd, slug = null) {
+  const root = localDir(cwd);
+  if (!existsSync(root)) return null;
+  if (!slug) {
+    try {
+      const ptr = JSON.parse(readFileSync(join(root, "active-scope"), "utf8"));
+      slug = ptr?.slug || null;
+    } catch { /* no pointer — fall through to a scan */ }
+  }
+  const candidates = slug ? [slug] : (() => { try { return readdirSync(root); } catch { return []; } })();
+  for (const entry of candidates) {
+    const p = join(root, entry, "receipt.json");
+    if (!existsSync(p)) continue;
+    try { return { slug: entry, receipt: JSON.parse(readFileSync(p, "utf8")) }; }
+    catch { /* unreadable receipt is not a run */ }
+  }
+  return null;
+}
+
+/** The typed argv contract (see `./lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "budget-check.mjs [--slug <slug>] [--cwd <dir>] [--at <iso8601>] [--strict]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str" },
+  cwd: { type: "path" },
+  at: { type: "str" },
+  strict: { type: "flag" },
+};
+
+export function main() {
+  const args = runArgs(ARGV_SPEC);
+  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).");
+    process.exit(2);
+  }
+  const startedAt = Date.parse(run.receipt.started_at || "");
+  if (Number.isNaN(startedAt)) {
+    console.error(`receipt for "${run.slug}" has no parseable started_at — cannot derive elapsed time.`);
+    process.exit(2);
+  }
+  const now = args.at ? Date.parse(args.at) : Date.now();
+  const budget = Number(run.receipt.config?.wall_clock_budget_s || 0) || null;
+  const result = evaluateBudget((now - startedAt) / 1000, budget);
+
+  console.log(JSON.stringify({ slug: run.slug, started_at: run.receipt.started_at, ...result }, null, 2));
+  process.exit(args.strict && result.status === "trip" ? 6 : 0);
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}