@rsaglobaltech/specgate 0.8.1

package/dist/packages/core/src/domain/Reconciliation.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * What `specops sync` does with one file when the pack has moved on.
+ *
+ * The hard case is the ordinary one: the pack changed a file and so did the
+ * project. Sync therefore keeps a baseline — the content the pack last wrote —
+ * and treats the three-way comparison as the primary decision rather than a
+ * fallback. Without a baseline it refuses to guess, because silently choosing
+ * a side is how a local edit disappears without anyone noticing.
+ *
+ * Pure: the contents arrive as strings and the outcome says what to write.
+ * Reading them, running `git merge-file`, and writing the result are the
+ * caller's, so every branch below is testable without a filesystem.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTCOME_LABEL = exports.CONFLICT_OUTCOMES = void 0;
+exports.reconcile = reconcile;
+/** The outcomes a human has to resolve by hand. */
+exports.CONFLICT_OUTCOMES = new Set([
+    "conflict",
+    "conflict-skipped",
+    "conflict-no-base",
+]);
+/** How each outcome is named in the per-pack summary. */
+exports.OUTCOME_LABEL = {
+    added: "added",
+    unchanged: "unchanged",
+    updated: "updated",
+    overwritten: "overwritten",
+    kept: "kept (local edits preserved)",
+    merged: "merged",
+    conflict: "CONFLICT (markers written)",
+    "conflict-skipped": "CONFLICT (skipped)",
+    "conflict-no-base": "CONFLICT (no merge base)",
+};
+/**
+ * @param base     what the pack wrote last time, or null if never recorded
+ * @param local    what the project has now, or null if the file does not exist
+ * @param incoming what the pack writes this time
+ */
+function reconcile(base, local, incoming, opts, merge) {
+    if (local === null) {
+        return { outcome: "added", write: incoming, baselineContent: incoming };
+    }
+    if (local === incoming) {
+        return { outcome: "unchanged", write: null, baselineContent: incoming };
+    }
+    if (opts.force) {
+        return { outcome: "overwritten", write: incoming, baselineContent: incoming };
+    }
+    if (base === null) {
+        // No merge base recorded — refuse to guess. Leave local untouched.
+        return { outcome: "conflict-no-base", write: null, baselineContent: null };
+    }
+    if (local === base) {
+        return { outcome: "updated", write: incoming, baselineContent: incoming };
+    }
+    if (incoming === base) {
+        // Pack unchanged for this file; local edits stand.
+        return { outcome: "kept", write: null, baselineContent: base };
+    }
+    // Both sides diverged from base — real three-way merge.
+    const result = merge(base, local, incoming);
+    if (!result.conflict) {
+        return { outcome: "merged", write: result.merged, baselineContent: incoming };
+    }
+    if (opts.abortOnConflict) {
+        return { outcome: "conflict-skipped", write: null, baselineContent: base };
+    }
+    return { outcome: "conflict", write: result.merged, baselineContent: base };
+}
+//# sourceMappingURL=Reconciliation.js.map

package/dist/packages/core/src/domain/Reconciliation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Reconciliation.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/Reconciliation.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AA4DH,8BAqCC;AApFD,mDAAmD;AACtC,QAAA,iBAAiB,GAAkC,IAAI,GAAG,CAAmB;IACxF,UAAU;IACV,kBAAkB;IAClB,kBAAkB;CACnB,CAAC,CAAC;AAEH,yDAAyD;AAC5C,QAAA,aAAa,GAA+C;IACvE,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,WAAW,EAAE,aAAa;IAC1B,IAAI,EAAE,8BAA8B;IACpC,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,4BAA4B;IACtC,kBAAkB,EAAE,oBAAoB;IACxC,kBAAkB,EAAE,0BAA0B;CAC/C,CAAC;AAwBF;;;;GAIG;AACH,SAAgB,SAAS,CACvB,IAAmB,EACnB,KAAoB,EACpB,QAAgB,EAChB,IAAsB,EACtB,KAAc;IAEd,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;IAC1E,CAAC;IACD,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;IAC1E,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;IAChF,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,mEAAmE;QACnE,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;IAC7E,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;IAC5E,CAAC;IACD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,mDAAmD;QACnD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;IACjE,CAAC;IAED,wDAAwD;IACxD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;IAChF,CAAC;IACD,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;IAC7E,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;AAC9E,CAAC"}

package/dist/packages/core/src/domain/RequirementGraph.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * The dependency graph between requirements.
+ *
+ * `harness run` processed requirements in matrix order and cut every worktree
+ * from the same base, which is wrong whenever one requirement builds on
+ * another: REQ-002 needed REQ-001's code to exist and there was no way to say
+ * so, so somebody had to know it and pass `--base-branch` by hand. That is
+ * defect H12 of the closure plan, and the false failure recorded as H9 was the
+ * same gap seen from the other side.
+ *
+ * A requirement declares what it builds on inside the `csda:trace` comment it
+ * already carries:
+ *
+ *   <!-- csda:trace uc=UC-002 feature=features/auth/scopes.feature
+ *        depends=REQ-001 -->
+ *
+ * That comment is the repository's existing way of attaching machine-readable
+ * facts to a requirement, and `change archive` already reads it to write the
+ * traceability row. So the model is the one this repository uses everywhere
+ * else: **the requirement declares, the matrix reflects.** Nothing about the
+ * ten-column format changes, which matters — `done` and `alm sync` both read
+ * Status as the penultimate cell, so an extra column would have silently sent
+ * status writes to the wrong place.
+ *
+ * A missing declaration means no dependencies, so every project that never
+ * writes one behaves exactly as it does today.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequirementGraph = void 0;
+exports.splitDependencies = splitDependencies;
+/** `"REQ-001, REQ-003"` → `["REQ-001", "REQ-003"]`, de-duplicated and upper-cased. */
+function splitDependencies(raw) {
+    const seen = new Set();
+    for (const token of String(raw).split(/[,;\s]+/)) {
+        const id = token.trim().toUpperCase();
+        if (id)
+            seen.add(id);
+    }
+    return [...seen];
+}
+/**
+ * The graph over a known set of requirements, and every question the CLI asks
+ * of it.
+ *
+ * Built once and then queried: ordering, levels and cycles are all derived
+ * from the same two adjacency maps, so they cannot disagree with each other.
+ */
+class RequirementGraph {
+    dependsOn;
+    dependents;
+    unknown;
+    selfReferential;
+    ids;
+    constructor(requirementIds, declared) {
+        this.ids = requirementIds.map((id) => String(id).toUpperCase());
+        const known = new Set(this.ids);
+        const dependsOn = {};
+        const dependents = {};
+        for (const id of known) {
+            dependsOn[id] = [];
+            dependents[id] = [];
+        }
+        const unknown = [];
+        const selfReferential = [];
+        for (const [requirement, deps] of Object.entries(declared)) {
+            if (!known.has(requirement))
+                continue; // declared for a REQ not in this project
+            for (const dependency of deps) {
+                if (dependency === requirement) {
+                    selfReferential.push(requirement);
+                }
+                else if (!known.has(dependency)) {
+                    unknown.push({ requirement, dependency });
+                }
+                else {
+                    dependsOn[requirement].push(dependency);
+                    dependents[dependency].push(requirement);
+                }
+            }
+        }
+        this.dependsOn = dependsOn;
+        this.dependents = dependents;
+        this.unknown = unknown;
+        this.selfReferential = selfReferential;
+    }
+    /** Build from an adjacency map the caller already has — the harness has one. */
+    static fromDependencies(requirementIds, declared) {
+        return new RequirementGraph(requirementIds, declared);
+    }
+    /**
+     * Requirements in an order where every dependency comes before what needs
+     * it, and the sets that could run at the same time.
+     *
+     * Kahn's algorithm with the queue kept in the caller's original order, so
+     * the result is stable: two requirements that do not constrain each other
+     * stay in matrix order, and a project with no declarations gets its input
+     * back untouched.
+     */
+    get schedule() {
+        const remaining = new Map(this.ids.map((id) => [id, new Set(this.dependsOn[id] ?? [])]));
+        const order = [];
+        const levels = [];
+        while (remaining.size > 0) {
+            const ready = this.ids.filter((id) => remaining.get(id)?.size === 0);
+            if (ready.length === 0)
+                break; // everything left is in, or behind, a cycle
+            levels.push(ready);
+            for (const id of ready) {
+                order.push(id);
+                remaining.delete(id);
+            }
+            for (const deps of remaining.values()) {
+                for (const id of ready)
+                    deps.delete(id);
+            }
+        }
+        return { order, levels };
+    }
+    get order() {
+        return this.schedule.order;
+    }
+    get levels() {
+        return this.schedule.levels;
+    }
+    /**
+     * The cycles among the requirements that could not be ordered.
+     *
+     * Reporting "there is a cycle" is not actionable; reporting
+     * `REQ-002 → REQ-003 → REQ-002` is.
+     */
+    get cycles() {
+        const ordered = new Set(this.order);
+        const stuck = this.ids.filter((id) => !ordered.has(id));
+        return this.findCycles(stuck);
+    }
+    /**
+     * Everything that transitively waits on `requirement`, so a cascade is
+     * reported once as blocked rather than N times as failed.
+     */
+    transitiveDependents(requirement) {
+        const blocked = new Set();
+        let grew = true;
+        while (grew) {
+            grew = false;
+            for (const [id, deps] of Object.entries(this.dependsOn)) {
+                if (blocked.has(id))
+                    continue;
+                if (deps.some((d) => d === requirement || blocked.has(d))) {
+                    blocked.add(id);
+                    grew = true;
+                }
+            }
+        }
+        return blocked;
+    }
+    /** Depth-first, returning each cycle once, as the path that closes it. */
+    findCycles(stuck) {
+        const inStuck = new Set(stuck);
+        const cycles = [];
+        const seenSignature = new Set();
+        const done = new Set();
+        const path = [];
+        const visit = (id) => {
+            if (done.has(id))
+                return;
+            const at = path.indexOf(id);
+            if (at !== -1) {
+                this.recordCycle(path.slice(at), cycles, seenSignature);
+                return;
+            }
+            path.push(id);
+            for (const dep of this.dependsOn[id] ?? []) {
+                if (inStuck.has(dep))
+                    visit(dep);
+            }
+            path.pop();
+            done.add(id);
+        };
+        for (const id of stuck)
+            visit(id);
+        return cycles;
+    }
+    /** Rotate to the smallest id so one loop found from two entry points is one cycle. */
+    recordCycle(cycle, cycles, seen) {
+        const smallest = [...cycle].sort()[0];
+        const pivot = cycle.indexOf(smallest);
+        const normalised = [...cycle.slice(pivot), ...cycle.slice(0, pivot)];
+        const signature = normalised.join(">");
+        if (seen.has(signature))
+            return;
+        seen.add(signature);
+        cycles.push(normalised);
+    }
+}
+exports.RequirementGraph = RequirementGraph;
+//# sourceMappingURL=RequirementGraph.js.map

package/dist/packages/core/src/domain/RequirementGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequirementGraph.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/RequirementGraph.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAYH,8CAOC;AARD,sFAAsF;AACtF,SAAgB,iBAAiB,CAAC,GAAW;IAC3C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAa,gBAAgB;IAClB,SAAS,CAAqC;IAC9C,UAAU,CAAqC;IAC/C,OAAO,CAA+B;IACtC,eAAe,CAAoB;IAE3B,GAAG,CAAoB;IAExC,YAAoB,cAAiC,EAAE,QAAuB;QAC5E,IAAI,CAAC,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QAChE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEhC,MAAM,SAAS,GAA6B,EAAE,CAAC;QAC/C,MAAM,UAAU,GAA6B,EAAE,CAAC;QAChD,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;YACvB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC;YACnB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC;QACtB,CAAC;QAED,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,MAAM,eAAe,GAAa,EAAE,CAAC;QAErC,KAAK,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC;gBAAE,SAAS,CAAC,yCAAyC;YAChF,KAAK,MAAM,UAAU,IAAI,IAAI,EAAE,CAAC;gBAC9B,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;oBAC/B,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBACpC,CAAC;qBAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;oBAClC,OAAO,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;gBAC5C,CAAC;qBAAM,CAAC;oBACN,SAAS,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;oBACxC,UAAU,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBAC3C,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;IAED,gFAAgF;IAChF,MAAM,CAAC,gBAAgB,CACrB,cAAiC,EACjC,QAAuB;QAEvB,OAAO,IAAI,gBAAgB,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,QAAQ;QACV,MAAM,SAAS,GAAG,IAAI,GAAG,CACvB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAC9D,CAAC;QAEF,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAe,EAAE,CAAC;QAE9B,OAAO,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC;YACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,CAAC,4CAA4C;YAE3E,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;gBACvB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACf,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACvB,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;gBACtC,KAAK,MAAM,EAAE,IAAI,KAAK;oBAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC3B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;IAC7B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED;;;;;OAKG;IACH,IAAI,MAAM;QACR,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,oBAAoB,CAAC,WAAmB;QACtC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAClC,IAAI,IAAI,GAAG,IAAI,CAAC;QAChB,OAAO,IAAI,EAAE,CAAC;YACZ,IAAI,GAAG,KAAK,CAAC;YACb,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBACxD,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;oBAAE,SAAS;gBAC9B,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC1D,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBAChB,IAAI,GAAG,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,0EAA0E;IAClE,UAAU,CAAC,KAAwB;QACzC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAe,EAAE,CAAC;QAC9B,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,IAAI,GAAa,EAAE,CAAC;QAE1B,MAAM,KAAK,GAAG,CAAC,EAAU,EAAQ,EAAE;YACjC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,OAAO;YAEzB,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC5B,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;gBACd,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;gBACxD,OAAO;YACT,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC3C,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,KAAK,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACf,CAAC,CAAC;QAEF,KAAK,MAAM,EAAE,IAAI,KAAK;YAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QAClC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,sFAAsF;IAC9E,WAAW,CAAC,KAAe,EAAE,MAAkB,EAAE,IAAiB;QACxE,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,UAAU,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QACrE,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,OAAO;QAChC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1B,CAAC;CACF;AAnKD,4CAmKC"}

package/dist/packages/core/src/domain/RequirementPlan.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequirementPlan = void 0;
+class RequirementPlan {
+    static DONE_STATUSES = new Set(["Implemented", "Verified", "Released"]);
+    static PLACEHOLDER_RE = /^(TBD|TODO|\?+|-)?$|\{\{/;
+    static isMeaningful(value) {
+        if (typeof value !== "string")
+            return false;
+        const stripped = value.replace(/^`|`$/g, "").trim();
+        if (!stripped)
+            return false;
+        return !RequirementPlan.PLACEHOLDER_RE.test(stripped);
+    }
+    static classifyRow(row, fileChecker) {
+        const reqId = row.requirement || "";
+        if (!/^REQ-\d+/.test(reqId))
+            return null;
+        const featureExists = fileChecker(row.featureFile || "");
+        const techDeclared = RequirementPlan.isMeaningful(row.technicalArtifact);
+        const testDeclared = RequirementPlan.isMeaningful(row.testArtifact);
+        const techExists = techDeclared && fileChecker(row.technicalArtifact || "");
+        const testExists = testDeclared && fileChecker(row.testArtifact || "");
+        const isDone = RequirementPlan.DONE_STATUSES.has(row.status || "");
+        let category;
+        if (!featureExists)
+            category = "NEEDS_FEATURE";
+        else if (!techDeclared && !testDeclared)
+            category = "NEEDS_EVERYTHING";
+        else if (testDeclared && !testExists && techDeclared && !techExists)
+            category = "NEEDS_EVERYTHING";
+        else if (testDeclared && !testExists)
+            category = "NEEDS_TEST";
+        else if (techDeclared && !techExists)
+            category = "NEEDS_IMPLEMENTATION";
+        else if (!isDone)
+            category = "NEEDS_STATUS_UPDATE";
+        else
+            category = "DONE";
+        return {
+            requirement: reqId,
+            scenario_id: row.scenarioId || "",
+            feature_file: row.featureFile || "",
+            technical_artifact: row.technicalArtifact || "",
+            test_artifact: row.testArtifact || "",
+            status: row.status || "",
+            feature_exists: featureExists,
+            technical_exists: techExists,
+            test_exists: testExists,
+            category,
+        };
+    }
+    static buildSummary(items) {
+        const summary = {
+            total: items.length,
+            done: 0,
+            needs_feature: 0,
+            needs_test: 0,
+            needs_implementation: 0,
+            needs_status_update: 0,
+            needs_everything: 0,
+            blocked: 0,
+        };
+        for (const item of items) {
+            if (item.category === "DONE")
+                summary.done++;
+            else if (item.category === "NEEDS_FEATURE")
+                summary.needs_feature++;
+            else if (item.category === "NEEDS_TEST")
+                summary.needs_test++;
+            else if (item.category === "NEEDS_IMPLEMENTATION")
+                summary.needs_implementation++;
+            else if (item.category === "NEEDS_STATUS_UPDATE")
+                summary.needs_status_update++;
+            else if (item.category === "NEEDS_EVERYTHING")
+                summary.needs_everything++;
+            if (item.blocked_by && item.blocked_by.length > 0) {
+                summary.blocked++;
+            }
+        }
+        return summary;
+    }
+}
+exports.RequirementPlan = RequirementPlan;
+//# sourceMappingURL=RequirementPlan.js.map

package/dist/packages/core/src/domain/RequirementPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequirementPlan.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/RequirementPlan.ts"],"names":[],"mappings":"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"}

package/dist/packages/core/src/domain/RequirementReadiness.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Is this requirement fit to hand to an agent? (B2)
+ *
+ * ## The attempt with the worst cost/result ratio in the loop
+ *
+ * `plan` already classifies `NEEDS_FEATURE` and `NEEDS_EVERYTHING`, and
+ * `harness run` never used it as a filter. A requirement whose feature does not
+ * exist and whose row declares no artifacts is handed over exactly like any
+ * other, and the agent discovers halfway through that it has to invent the
+ * acceptance criterion — then spends up to `max_attempts` × the timeout on it.
+ *
+ * What this buys is not a new rule. It is that "is this ready for an agent?"
+ * stops being the intuition of whoever typed the command and becomes something
+ * calculated, with a fix attached to each answer.
+ *
+ * ## Blocking versus warning
+ *
+ * A blocker means the agent cannot succeed, not that the requirement is untidy:
+ *
+ * - **no feature file** — there is no acceptance criterion to satisfy;
+ * - **a scenario the gate cannot fail** — the reward signal is counterfeit
+ *   (H14), so a green run would prove nothing;
+ * - **dependencies not green** — the work it builds on is not there;
+ * - **`Deprecated`** — nobody wants it built;
+ * - **`Needs Clarification`** — its meaning is disputed, and an agent asked to
+ *   settle a disagreement will settle it by guessing.
+ *
+ * Undeclared artifacts only warn. The row being vague about *where* the work
+ * goes does not stop the work, and `A2` already reports it against the diff
+ * afterwards, which is the moment there is evidence to report.
+ *
+ * ## Why no I/O here
+ *
+ * Whether a file exists and what its scenarios say are facts the caller
+ * gathers; whether those facts add up to "ready" is a rule. Keeping them apart
+ * is what lets every case below be tested without a project on disk.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNBUILDABLE_STATUS = exports.READINESS_CODES = void 0;
+exports.requirementReadiness = requirementReadiness;
+const Diagnostic_1 = require("./Diagnostic");
+exports.READINESS_CODES = Object.freeze({
+    NO_FEATURE: "requirement_has_no_feature",
+    UNRUNNABLE_SCENARIO: "requirement_scenario_unrunnable",
+    BLOCKED_BY: "requirement_blocked_by_dependency",
+    NOT_WANTED: "requirement_not_wanted",
+    NEEDS_CLARIFICATION: "requirement_needs_clarification",
+    NO_TEST_ARTIFACT: "requirement_declares_no_test_artifact",
+    NO_TECHNICAL_ARTIFACT: "requirement_declares_no_technical_artifact",
+});
+/** Statuses that mean an agent should not be pointed at this row. */
+exports.UNBUILDABLE_STATUS = Object.freeze({
+    Deprecated: exports.READINESS_CODES.NOT_WANTED,
+    "Needs Clarification": exports.READINESS_CODES.NEEDS_CLARIFICATION,
+});
+function requirementReadiness(input) {
+    const target = input.requirement;
+    const blockers = [];
+    const unbuildable = exports.UNBUILDABLE_STATUS[String(input.status || "")];
+    if (unbuildable) {
+        blockers.push((0, Diagnostic_1.error)(unbuildable, unbuildable === exports.READINESS_CODES.NOT_WANTED
+            ? `status is ${input.status} — nobody wants this built.`
+            : `status is ${input.status} — its meaning is still disputed, and an agent ` +
+                `asked to settle a disagreement will settle it by guessing.`, {
+            target,
+            fix: unbuildable === exports.READINESS_CODES.NOT_WANTED
+                ? "Drop it from the run, or move the row out of Deprecated."
+                : "Settle the question with the people who raised it, then set the status.",
+        }));
+    }
+    if (!input.featureExists) {
+        blockers.push((0, Diagnostic_1.error)(exports.READINESS_CODES.NO_FEATURE, input.featureFile
+            ? `its feature file ${input.featureFile} does not exist, so there is no ` +
+                `acceptance criterion to satisfy.`
+            : "the row declares no feature file, so there is no acceptance criterion to satisfy.", {
+            target,
+            fix: `Write the scenario first: \`specgate req link ${target} --feature <path>\`.`,
+        }));
+    }
+    // Only errors. A scenario Cucumber sees as empty passes without running
+    // anything, so a green gate on it would mean nothing (H14).
+    const unrunnable = (input.scenarioFindings || []).filter((f) => f.severity === "error");
+    if (unrunnable.length > 0) {
+        blockers.push((0, Diagnostic_1.error)(exports.READINESS_CODES.UNRUNNABLE_SCENARIO, `its scenario would pass without testing anything (${unrunnable.length} error(s)), ` +
+            `so the gate could not tell success from failure.`, {
+            target,
+            fix: "Run `specgate validate <dir> --strict-scenarios` to see them, and fix them first.",
+        }));
+    }
+    const blocked = input.blockedBy || [];
+    if (blocked.length > 0) {
+        blockers.push((0, Diagnostic_1.error)(exports.READINESS_CODES.BLOCKED_BY, `it depends on ${blocked.join(", ")}, which ${blocked.length === 1 ? "is" : "are"} not done.`, {
+            target,
+            fix: `Run ${blocked.join(", ")} first — \`specgate harness run\` orders them for you.`,
+        }));
+    }
+    // Warnings, not blockers: a vague row does not stop the work, and A2 reports
+    // the same gap against the actual diff afterwards — the moment there is
+    // evidence rather than an expectation.
+    //
+    // These are not the noise trap A2 had to avoid. `TBD` in the test column is
+    // not a false positive; it is an accurate statement about an incomplete row,
+    // and TDD says that column is what should be filled in first.
+    if (!input.testDeclared) {
+        blockers.push((0, Diagnostic_1.warning)(exports.READINESS_CODES.NO_TEST_ARTIFACT, "the row declares no test artifact, so the agent chooses where the test " +
+            "goes and the matrix will point somewhere else.", { target, fix: `specgate req link ${target} --test <path>` }));
+    }
+    if (!input.technicalDeclared) {
+        blockers.push((0, Diagnostic_1.warning)(exports.READINESS_CODES.NO_TECHNICAL_ARTIFACT, "the row declares no production artifact, so the agent chooses where the " +
+            "implementation goes and the matrix will point somewhere else.", { target, fix: `specgate req link ${target} --code <path>` }));
+    }
+    return { ready: !blockers.some((b) => b.severity === "error"), blockers };
+}
+//# sourceMappingURL=RequirementReadiness.js.map

package/dist/packages/core/src/domain/RequirementReadiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequirementReadiness.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/RequirementReadiness.ts"],"names":[],"mappings":"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"}

package/dist/packages/core/src/domain/RequirementSyntax.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Whether a requirement's prose is checkable by a machine — EARS, opt-in (F6).
+ *
+ * ## Why this exists
+ *
+ * `PLAN_PREDICTABLE_CODE_EVOLUTION.md` §4 names the real gap against
+ * Predictable Code: `specgate validate` checks that the paperwork is internally
+ * consistent, not that the code does what the spec says. §8.1 draws the
+ * consequence — a code verifier is useless while the spec it checks against is
+ * prose. `- Max 5 failed attempts per hour per user` is not checkable by
+ * anything. So the first step is not a verifier; it is making the requirement
+ * itself say something a machine can hold code to.
+ *
+ * EARS (Easy Approach to Requirements Syntax) is the narrowest tool for that:
+ * five sentence shapes, each pairing a trigger keyword with an obligation.
+ * This module does not attempt to parse full EARS grammar — no regex can
+ * reliably tell "the system" from a response clause. It checks the one thing a
+ * regex can tell honestly: whether an obligation keyword (RFC 2119) is present
+ * at all, and whether a requirement that opens as an unwanted-behaviour clause
+ * (`IF …`) actually resolves with `THEN …`. Anything wider would be the H13
+ * mistake again — a check that claims to enforce a grammar it does not parse.
+ *
+ * ## Why RFC 2119 lives here now
+ *
+ * `DeltaSpec.ts` already enforces `no_rfc2119_keyword`, but only for
+ * requirements inside a delta (`change validate` / `change archive`) — a
+ * capability spec at rest has never been checked. Moving the constant here and
+ * having `DeltaSpec` import it keeps one definition instead of two that can
+ * drift, which is the F1/A3 lesson: a rule enforced in one place and silent in
+ * another is not a rule, it is luck.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIREMENT_SYNTAX_CODES = exports.RFC2119 = void 0;
+exports.analyseRequirementText = analyseRequirementText;
+const Diagnostic_1 = require("./Diagnostic");
+/** An obligation keyword, English or Spanish. Unchanged from `DeltaSpec`. */
+exports.RFC2119 = /\b(SHALL|MUST|SHOULD|MAY|DEBE|DEBERÁ|DEBERA)\b/;
+/** Every code this module can emit. Callers branch on these, never on prose. */
+exports.REQUIREMENT_SYNTAX_CODES = Object.freeze({
+    NO_RFC2119: "no_rfc2119_keyword",
+    MISSING_THEN: "requirement_missing_then_clause",
+});
+/**
+ * The one paired-keyword EARS shape a regex can check honestly: a requirement
+ * that opens as "IF <trigger>" (unwanted behaviour) has to resolve with
+ * "THEN <response>" in the same sentence, or it names a trigger and never says
+ * what happens.
+ *
+ * The other four EARS shapes — ubiquitous, event-driven (`WHEN`), state-driven
+ * (`WHILE`), optional-feature (`WHERE`) — have no second keyword to be missing;
+ * their only checkable requirement is the obligation keyword, which
+ * `NO_RFC2119` already covers. Claiming to validate their internal structure
+ * beyond that would be checking a shape this module cannot actually parse.
+ */
+const IF_TRIGGER = /^\s*(?:IF|SI)\b/i;
+const THEN_KEYWORD = /\b(?:THEN|ENTONCES)\b/i;
+/**
+ * Checks one requirement's prose. `text` is the requirement body as
+ * `SpecParser` / `DeltaSpec` hand it over — free-text only, scenario steps
+ * live separately and are not part of this check.
+ *
+ * Two independent findings, never conflated: a requirement can state no
+ * obligation at all (`NO_RFC2119`), or state one but leave an `IF` trigger
+ * unresolved (`MISSING_THEN`). A requirement missing both reports both — they
+ * are different defects with different fixes.
+ */
+function analyseRequirementText(text, opts) {
+    const trimmed = String(text || "").trim();
+    const found = [];
+    const at = (extra = {}) => ({
+        target: opts.target,
+        ...(opts.file ? { file: opts.file } : {}),
+        ...(opts.line ? { line: opts.line } : {}),
+        ...extra,
+    });
+    if (!trimmed)
+        return found;
+    const hasObligation = exports.RFC2119.test(trimmed);
+    if (!hasObligation) {
+        found.push((0, Diagnostic_1.warning)(exports.REQUIREMENT_SYNTAX_CODES.NO_RFC2119, `${opts.target} states no obligation (SHALL / MUST / SHOULD / MAY / DEBE / DEBERÁ).`, at({ fix: 'Rewrite the body as "The system SHALL …" or one of its EARS forms.' })));
+    }
+    if (IF_TRIGGER.test(trimmed) && !THEN_KEYWORD.test(trimmed)) {
+        found.push((0, Diagnostic_1.warning)(exports.REQUIREMENT_SYNTAX_CODES.MISSING_THEN, `${opts.target} opens with "IF" but never resolves with "THEN" — the trigger names a ` +
+            "condition and never says what the system does about it.", at({
+            fix: 'Complete the EARS unwanted-behaviour form: "IF <trigger>, THEN the system SHALL …".',
+        })));
+    }
+    return found;
+}
+//# sourceMappingURL=RequirementSyntax.js.map

package/dist/packages/core/src/domain/RequirementSyntax.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequirementSyntax.js","sourceRoot":"","sources":["../../../../../packages/core/src/domain/RequirementSyntax.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAuCH,wDAwCC;AA5ED,6CAAuC;AAEvC,6EAA6E;AAChE,QAAA,OAAO,GAAG,gDAAgD,CAAC;AAExE,gFAAgF;AACnE,QAAA,wBAAwB,GAAG,MAAM,CAAC,MAAM,CAAC;IACpD,UAAU,EAAE,oBAAoB;IAChC,YAAY,EAAE,iCAAiC;CAChD,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,GAAG,kBAAkB,CAAC;AACtC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAE9C;;;;;;;;;GASG;AACH,SAAgB,sBAAsB,CACpC,IAAY,EACZ,IAAsD;IAEtD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,MAAM,EAAE,GAAG,CAAC,QAAiC,EAAE,EAAE,EAAE,CAAC,CAAC;QACnD,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,KAAK;KACT,CAAC,CAAC;IAEH,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE3B,MAAM,aAAa,GAAG,eAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CACR,IAAA,oBAAO,EACL,gCAAwB,CAAC,UAAU,EACnC,GAAG,IAAI,CAAC,MAAM,sEAAsE,EACpF,EAAE,CAAC,EAAE,GAAG,EAAE,oEAAoE,EAAE,CAAC,CAClF,CACF,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5D,KAAK,CAAC,IAAI,CACR,IAAA,oBAAO,EACL,gCAAwB,CAAC,YAAY,EACrC,GAAG,IAAI,CAAC,MAAM,wEAAwE;YACpF,yDAAyD,EAC3D,EAAE,CAAC;YACD,GAAG,EAAE,qFAAqF;SAC3F,CAAC,CACH,CACF,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}