shapeup-sdlc 1.7.0 → 3.0.0

package/{skills/tech-lead/scripts/lib/contract-md.mjs → kernel/lib/contract.mjs}

@@ -1,4 +1,4 @@
-// contract-md — read and write the committed contracts as markdown.
+// contract — read and write the committed contracts as markdown.
 //
 // WHY (ADR-0001). Scope contracts, the wiring map and the project profile are *low-level design*:
 // which files a slice may touch, which seam each use case attaches to, where the app starts. A
@@ -56,10 +56,30 @@ export const SCOPE_CONTRACT = {
   signatures: { affordance_manifest: ["test_id", "role"] },
 };
 
-/** `WiringMap` — per use case: engine → seam → entry-point call site → affordance. */
+/**
+ * `WiringMap` — per use case: engine → seam → entry-point call site → affordance.
+ *
+ * `perSection` is a MIGRATION READER, and it exists because the canonical shape was never written.
+ * `solution-architect` was told to produce a `{schema_version, feature, entry_point, entries[]}`
+ * OBJECT and never told the markdown layout, so every run authored its own: a `## Entries` section
+ * with one `### UC-xx — title` subsection per use case, each holding a vertical `| Field | Value |`
+ * table. Under this spec that parses as no table at all — and the vertical layout carries no
+ * `use_case` header cell, so the `signatures` detector below cannot see it either and the contract
+ * reports as perfectly readable while yielding nothing.
+ *
+ * Measured across every completed run in the corpus: 9 of 9 committed wiring maps parsed to ZERO
+ * entries with `unreadableReason() === null`, and `trace-lint` certified `🟢 green · 0/0 engines
+ * reach <entry point>` against a deliverable whose engines were on disk — the exact failure quoted
+ * in the banner above, recurred in a shape its own fix could not detect.
+ *
+ * The horizontal `## Wiring` table stays canonical: it is what `renderContract` emits, so a map
+ * regenerated by any later `wire` converges on it without a migration step. This reader only keeps
+ * the maps already committed from resolving to nothing.
+ */
 export const WIRING_MAP = {
   tables: { entries: "Wiring" },
   signatures: { entries: ["use_case", "engine"] },
+  perSection: { field: "entries", key: "use_case", idPattern: /^(UC-[A-Za-z0-9_.-]+)/ },
 };
 
 /** `ProjectProfile` — archetype + entry point. All scalars; no tables. */
@@ -74,10 +94,52 @@ export const PROJECT_PROFILE = { tables: {} };
  */
 export const UNREADABLE = "$unreadable_tables";
 
+/**
+ * Marks a contract that parsed only via a MIGRATION reader — readable, but not in the canonical
+ * shape. Without it the fallback is permanent by silence: the file works, nothing says it is the
+ * old form, and one artifact quietly keeps two formats forever. Readers surface it as a warn so a
+ * regeneration converges the file instead of the reader carrying it indefinitely.
+ */
+export const LEGACY_LAYOUT = "$legacy_layout";
+
 // ---------------------------------------------------------------------------
 // Scalars
 // ---------------------------------------------------------------------------
 
+/**
+ * Remove ONE matching pair of surrounding quotes, and unescape what was inside them.
+ *
+ * The pairing check is the whole point. Stripping a leading or trailing quote INDEPENDENTLY eats a
+ * character from any value that merely ends in one — a shell fixture like
+ * `export STORE="$T/s.json"` came back missing its final quote and was handed to `bash` as a
+ * syntax error. Nothing reports that as a parse failure: the verification step simply scores the
+ * implementation red, attempt after attempt, against code that was correct the whole time. A lossy
+ * reader is indistinguishable from a builder that cannot make progress, which is what makes this
+ * expensive rather than merely wrong.
+ *
+ * A double-quoted scalar that parses as JSON is read as JSON, because that is the escaping
+ * convention {@link uncoerce} emits — the two are exact inverses, and the round trip is asserted.
+ *
+ * EVERYTHING ELSE IS UNWRAPPED BUT NOT UNESCAPED, deliberately. A backslash inside a scalar that
+ * is not valid JSON belongs to whatever will consume the value, not to this dialect: shell
+ * verification fixtures are the common case, and there `echo "[{\"text\": \"ok\"}]"` needs its
+ * backslashes delivered intact. Unescaping on this path would corrupt them exactly as surely as
+ * the missing pair check corrupted the values that end in a quote — the same defect, from the
+ * other side. So the escaping convention applies only where it is unambiguous.
+ *
+ * @param {string} s - The trimmed raw text.
+ * @returns {string} The value with its surrounding quotes removed, or `s` unchanged.
+ */
+function unquote(s) {
+  if (s.length < 2) return s;
+  const q = s[0];
+  if ((q !== '"' && q !== "'") || s[s.length - 1] !== q) return s;
+  if (q === '"') {
+    try { return JSON.parse(s); } catch { /* not JSON — unwrap only, see above */ }
+  }
+  return s.slice(1, -1);
+}
+
 /**
  * Coerce one frontmatter or table-cell value.
  *
@@ -110,7 +172,7 @@ export function coerce(raw) {
   // A LIST IS TESTED BEFORE THE QUOTES ARE STRIPPED. `"[a, b]"` is a quoted STRING; stripping first
   // would turn it into a list and change its type on a round-trip.
   if (/^\[.*\]$/.test(trimmed)) return splitList(trimmed.slice(1, -1));
-  const v = trimmed.replace(/^["']|["']$/g, "");
+  const v = unquote(trimmed);
   if (v === "true") return true;
   if (v === "false") return false;
   if (v === "~" || v === "null" || v === "") return null;
@@ -129,7 +191,12 @@ export function uncoerce(v) {
   // trip that wrote it re-reads as several members — the same shredding, arriving from the writer's
   // side instead of the reader's.
   if (Array.isArray(v)) return `[${v.map((x) => (/[,"]/.test(String(x)) ? JSON.stringify(String(x)) : String(x))).join(", ")}]`;
-  return String(v);
+  const s = String(v);
+  // A scalar that itself begins AND ends with a quote is indistinguishable, once written, from a
+  // quoted scalar — so emit it in the JSON form the reader unwraps exactly. Without this the round
+  // trip loses the value's own outer quotes, which is the same shredding as the reader's half.
+  if (s.length >= 2 && (s[0] === '"' || s[0] === "'") && s[s.length - 1] === s[0]) return JSON.stringify(s);
+  return s;
 }
 
 /**
@@ -287,6 +354,36 @@ export function parseTables(body) {
   return out;
 }
 
+/**
+ * Fold per-entity `| Field | Value |` sections into the row array a horizontal table would give.
+ *
+ * The legacy wiring-map layout (see {@link WIRING_MAP}): one `### UC-xx — title` subsection per use
+ * case, each holding a vertical two-column table. The entity id comes from the HEADING, the fields
+ * from the rows. Field names are unwrapped from backticks and snake-cased so they land on the same
+ * keys the canonical horizontal table produces — the two layouts must yield identical objects or
+ * this is a second format rather than a second spelling of one.
+ *
+ * @param {Object<string, Array<Object>>} tables - `parseTables` output, keyed by heading.
+ * @param {{field:string, key:string, idPattern:RegExp}} desc - The `perSection` descriptor.
+ * @returns {Array<Object>} One row per matching section, in document order; [] when none match.
+ */
+export function perSectionRows(tables, desc) {
+  const out = [];
+  for (const [heading, rows] of Object.entries(tables)) {
+    const id = heading.match(desc.idPattern)?.[1];
+    if (!id || !rows.length) continue;
+    const cols = new Set(Object.keys(rows[0]));
+    if (!cols.has("field") || !cols.has("value")) continue; // not a Field/Value table — prose, skip
+    const entry = { [desc.key]: id };
+    for (const r of rows) {
+      const k = String(r.field ?? "").replace(/`/g, "").trim().toLowerCase().replace(/\s+/g, "_");
+      if (k && r.value !== undefined) entry[k] = r.value;
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
 /**
  * Render rows as a markdown table.
  * @param {Array<Object>} rows - Row objects.
@@ -343,6 +440,57 @@ export function parseContract(md, spec = SCOPE_CONTRACT) {
       }
     }
   }
+  // THE PER-SECTION LAYOUT, read only when the canonical table is genuinely absent.
+  //
+  // Ordering matters: the canonical `## Wiring` table always wins, so a map carrying both shapes
+  // never has the migration reader override the current one. If neither yields rows but the body
+  // DOES carry sections this descriptor recognises, that is a parse failure and not an empty
+  // field — the whole point of the banner above — so it is reported rather than returned as
+  // silence. That case is what let 9 of 9 committed maps read as clean while holding nothing.
+  const ps = spec.perSection;
+  if (ps && !(ps.field in out)) {
+    const rows = perSectionRows(tables, ps);
+    if (rows.length) { out[ps.field] = rows; out[LEGACY_LAYOUT] = true; }
+    // The headings come from the BODY, not from `tables` — `parseTables` only records a heading
+    // that has a table under it, so a section whose table is missing or malformed leaves no trace
+    // there. Looking for the evidence in the parsed output is looking where the failure already
+    // erased it, which is the same mistake this whole diagnostic exists to correct.
+    else if ([...String(body).matchAll(/^#{1,6}\s+(.*)$/gm)].some((m) => ps.idPattern.test(m[1].trim()))) {
+      unreadable.push({
+        field: ps.field, expected_heading: Object.entries(spec.tables || {}).find(([f]) => f === ps.field)?.[1] || ps.field,
+        found_under: "per-entity sections whose tables this dialect could not read", rows: 0,
+      });
+    }
+  }
+
+  // A NON-TABLE FIELD WRITTEN AS A `## SECTION` VANISHES, and the loop above cannot see it.
+  //
+  // Everything above answers "was a declared TABLE written under the wrong heading". It says
+  // nothing about the other half of the contract — the scalars and string lists that live in
+  // frontmatter — because the parser has no heading to expect for them. So an author who writes
+  //
+  //     ## e2e_verification_fixtures
+  //     - `node --test test/store.test.js` — round-trips load()/save()
+  //
+  // instead of a frontmatter key produces a contract where that field is simply `undefined`, and
+  // every reader downstream treats it as "not declared". Measured: an architect did exactly this,
+  // the fixtures reached `verify t0` as `undefined`, and six scopes were certified T0-green having
+  // executed nothing — while the substrate list beside it, written as a frontmatter block list,
+  // parsed perfectly. One field silently vanished between the writer and the reader.
+  //
+  // The detector is deliberately narrow: a heading whose text is a bare snake_case identifier is
+  // an author naming a FIELD, not writing prose — `## Why this slice` and `## Affordances` cannot
+  // match. Reported through the same channel, so `unreadableReason()` covers both halves and a
+  // reader still asks once.
+  for (const m of String(body).matchAll(/^##\s+([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\s*$/gm)) {
+    const field = m[1];
+    if (field in out) continue;                                   // also present in frontmatter — fine
+    if (Object.prototype.hasOwnProperty.call(spec.tables || {}, field)) continue;  // handled above
+    unreadable.push({
+      field, expected_heading: field, rows: 0,
+      found_under: "a `## " + field + "` markdown section, which this dialect reads as prose",
+    });
+  }
   if (unreadable.length) out[UNREADABLE] = unreadable;
   return out;
 }
@@ -359,9 +507,19 @@ export function unreadableReason(contract) {
   const u = contract && contract[UNREADABLE];
   if (!u || !u.length) return null;
   return u
-    .map((x) => (x.found_under === "an indented block this dialect cannot read" || x.found_under === "both"
-      ? `\`${x.field}\` was written as \`${x.expected_heading}\` but ${x.rows} indented line(s) beneath it could not be read, so the value parsed as ABSENT`
-      : `\`${x.field}\` must be a table under a \`## ${x.expected_heading}\` heading; found ${x.rows} matching row(s) under "${x.found_under}" instead, so the field parsed as ABSENT`))
+    .map((x) => {
+      if (x.found_under === "an indented block this dialect cannot read" || x.found_under === "both") {
+        return `\`${x.field}\` was written as \`${x.expected_heading}\` but ${x.rows} indented line(s) beneath it could not be read, so the value parsed as ABSENT`;
+      }
+      // A frontmatter field written as a prose section. Phrased as its own case because telling an
+      // author to "use a table heading" when the fix is "put it in frontmatter" sends them the
+      // wrong way — and this is the field whose silent absence certified six scopes on no evidence.
+      if (x.rows === 0 && String(x.found_under).includes("markdown section")) {
+        return `\`${x.field}\` was written as a \`## ${x.field}\` markdown section, which this dialect reads as prose — ` +
+          `it must be a FRONTMATTER key (a \`- \` block list or an inline [a, b] list), so as written the field parsed as ABSENT`;
+      }
+      return `\`${x.field}\` must be a table under a \`## ${x.expected_heading}\` heading; found ${x.rows} matching row(s) under "${x.found_under}" instead, so the field parsed as ABSENT`;
+    })
     .join("; ");
 }
 
@@ -460,6 +618,92 @@ export function readAllContracts(dir, spec = SCOPE_CONTRACT) {
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// The scope ↔ spec join
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalise one use-case reference to a bare `UC-*` id.
+ *
+ * The same reference is written three ways across the tree — `UC-AddTodo`, `[[UC-AddTodo]]` and
+ * `[[usecases/UC-AddTodo]]` all name one file — so every reader must strip identically or the two
+ * sides of a join disagree about a UC they both hold.
+ *
+ * @param {string} ref - A use-case reference in any of the accepted forms.
+ * @returns {string} The bare id (`UC-AddTodo`), trimmed.
+ */
+export function ucId(ref) {
+  return String(ref ?? "").trim().replace(/^\[\[|\]\]$/g, "").replace(/^usecases\//, "").replace(/\.md$/, "").trim();
+}
+
+/**
+ * The tasks on a LOCAL board that belong to a scope, joined through the COMMITTED spec.
+ *
+ * WHY THE JOIN GOES THROUGH THE USE CASE. A scope contract is committed and a board is not, so a
+ * contract that named its task ids directly held a pointer into a gitignored, per-machine tier:
+ * on a fresh clone the ids resolved to nothing and every reader silently read "no tasks" rather
+ * than "the board is missing". Measured on a committed contract naming `TASK-004` with no board on
+ * disk: `compile` exited 0 and wrote a build order carrying no work at all. `use_cases[]` is the
+ * same LOCAL→SHARED direction the board's own `use_case_refs` already flows in, so the join is
+ * re-derived from two artifacts that are each valid on their own.
+ *
+ * @param {Array<{use_case_refs?:string[]}>} tasks - The parsed board.
+ * @param {{use_cases?:string[]}} contract - The scope contract.
+ * @returns {Array<object>} The board tasks anchored to ≥1 of this scope's use cases, in board
+ *   order; [] when the scope names no use cases (the caller owns that fallback, because "this
+ *   scope has no anchor" and "this scope has no tasks" are different questions).
+ */
+export function tasksForScope(tasks, contract) {
+  const id = contract?.scope_id;
+  // AN EXPLICIT ASSIGNMENT WINS, and it is the only thing that makes this a PARTITION.
+  //
+  // The UC join alone is not one. A use case is routinely implemented by several scopes — that is
+  // what a vertical slice IS — so on a cut like the corpus's four scopes over a single UC, every
+  // scope matched every task. The previous `tasks[]` field partitioned correctly and paid for it by
+  // putting a machine-local id in a committed file; this restores the partition in the sanctioned
+  // direction instead, with the LOCAL task naming the committed scope. Absent, the UC join stands —
+  // which is right whenever the cut gives each scope its own use cases, and spec-lint's
+  // SCOPE-PARTITION reds the case where it does not.
+  const claimed = (tasks || []).filter((t) => t.scope_id);
+  if (id && claimed.length) {
+    const mine = claimed.filter((t) => String(t.scope_id).trim() === id);
+    // A board only partly stamped still resolves: assigned tasks go to their scope, and anything
+    // unassigned falls back to the UC join rather than vanishing mid-migration.
+    const rest = (tasks || []).filter((t) => !t.scope_id);
+    return [...mine, ...byUseCase(rest, contract)];
+  }
+  return byUseCase(tasks, contract);
+}
+
+/** The UC-overlap half of {@link tasksForScope}. @param {Array<object>} tasks Board. @param {object} contract Scope. @returns {Array<object>} Matches. */
+function byUseCase(tasks, contract) {
+  const mine = new Set((contract?.use_cases || []).map(ucId).filter(Boolean));
+  if (!mine.size) return [];
+  return (tasks || []).filter((t) => (t.use_case_refs || []).some((r) => mine.has(ucId(r))));
+}
+
+/**
+ * Tasks that more than one scope would build — the ambiguity {@link tasksForScope} cannot resolve.
+ *
+ * Dispatch has to be a partition: a task built by two scopes is built twice, and the second builder
+ * is denied by the sandbox for writing outside its own substrate, so the cost lands as burnt
+ * attempts and escalations rather than as corruption. Measured on the corpus's four-scope,
+ * one-use-case cut: every task claimed by every scope.
+ *
+ * @param {Array<{id:string, scope_id?:string, use_case_refs?:string[]}>} tasks - The parsed board.
+ * @param {Array<{scope_id:string, use_cases?:string[]}>} contracts - Every scope in the run.
+ * @returns {Array<{task_id:string, scopes:string[]}>} One entry per contested task; [] when the
+ *   assignment is already a partition.
+ */
+export function scopePartitionConflicts(tasks, contracts) {
+  const out = [];
+  for (const t of tasks || []) {
+    const owners = (contracts || []).filter((c) => tasksForScope([t], c).length).map((c) => c.scope_id);
+    if (owners.length > 1) out.push({ task_id: t.id, scopes: owners });
+  }
+  return out;
+}
+
 /**
  * Extract the prose a regeneration must not destroy — everything in the body except the sections
  * this spec owns.