agent-sdd 1.0.3

package/dist/shared/domain/PartitionGrammar.d.ts

@@ -0,0 +1,4 @@
+export declare const PARTITION_PREFIX_RE_SRC = "[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)*";
+export declare const ID_TAIL_RE_SRC = "[A-Z]+-\\d+";
+export declare const PARTITION_NAME_RE: RegExp;
+export declare const NORMATIVE_ID_RE: RegExp;

package/dist/shared/domain/PartitionGrammar.js

@@ -0,0 +1,16 @@
+/*
+ * Single source of truth for the partition-prefix grammar (CST-007),
+ * imported by both `MarkerParser` and `Config` so the two cannot drift.
+ */
+/*
+ * One or more lowercase tokens joined by `:`, so adopters can namespace
+ * partitions (e.g. `bridge:commands`).
+ */
+export const PARTITION_PREFIX_RE_SRC = "[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)*";
+/*
+ * Normative-ID tail. Contains no `:`, which is what makes the rightmost-`:`
+ * split in `MarkerParser.lastIndexOf(":")` unambiguous (CST-007).
+ */
+export const ID_TAIL_RE_SRC = "[A-Z]+-\\d+";
+export const PARTITION_NAME_RE = new RegExp(`^${PARTITION_PREFIX_RE_SRC}$`);
+export const NORMATIVE_ID_RE = new RegExp(`^${PARTITION_PREFIX_RE_SRC}:${ID_TAIL_RE_SRC}$`);

package/dist/shared/domain/PlanFile.d.ts

@@ -0,0 +1,28 @@
+export type AttestationTargetStatus = "approved" | "deprecated" | "removed";
+export interface PendingAttestation {
+    id: string;
+    ownerRole: string;
+    approverIdentity: string;
+    timestamp: string;
+    changeRequest: string;
+    scope: string;
+    targetStatus: AttestationTargetStatus;
+    reviewedTestOracle?: string;
+}
+export interface PlanFileShape {
+    planId: string;
+    createdAt: string;
+    pendingAttestations: PendingAttestation[];
+}
+export declare const PLAN_ID_GRAMMAR: RegExp;
+/** Generate a plan-id from a Date and 5 [a-z0-9] random chars.
+ *  rand: optional injectable RNG (yields a value in [0, 1)) for determinism. */
+export declare function generatePlanId(now: Date, rand?: () => number): string;
+/** Format a Date as YYYY-MM-DDTHHMMSSZ (ISO-8601 basic UTC, second precision). */
+export declare function isoBasicUtc(now: Date): string;
+/** Parse a YAML-decoded plan-file object into a typed PlanFileShape.
+ *  Throws on shape violation. */
+export declare function parsePlanFile(value: unknown): PlanFileShape;
+/** Serialise a PlanFileShape into a stable YAML string. The fields are
+ *  emitted in fixed order so plan files diff cleanly across edits. */
+export declare function serialisePlanFile(plan: PlanFileShape): string;

package/dist/shared/domain/PlanFile.js

@@ -0,0 +1,112 @@
+/*
+ * CTR-019 / SUR-014
+ * Plan-file shape: one YAML file per plan_id, holding pending attestations
+ * that `sdd finalize` materialises atomically into spec files. Pure module
+ * (no node:*); filesystem I/O lives in feature-local outbound adapters.
+ */
+export const PLAN_ID_GRAMMAR = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{6}Z-[a-z0-9]{5}$/;
+const RAND_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+/** Generate a plan-id from a Date and 5 [a-z0-9] random chars.
+ *  rand: optional injectable RNG (yields a value in [0, 1)) for determinism. */
+export function generatePlanId(now, rand = Math.random) {
+    const ts = isoBasicUtc(now);
+    let suffix = "";
+    for (let i = 0; i < 5; i++) {
+        const r = Math.floor(rand() * RAND_ALPHABET.length);
+        suffix += RAND_ALPHABET[r];
+    }
+    return `${ts}-${suffix}`;
+}
+/** Format a Date as YYYY-MM-DDTHHMMSSZ (ISO-8601 basic UTC, second precision). */
+export function isoBasicUtc(now) {
+    const y = String(now.getUTCFullYear()).padStart(4, "0");
+    const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(now.getUTCDate()).padStart(2, "0");
+    const hh = String(now.getUTCHours()).padStart(2, "0");
+    const mm = String(now.getUTCMinutes()).padStart(2, "0");
+    const ss = String(now.getUTCSeconds()).padStart(2, "0");
+    return `${y}-${m}-${d}T${hh}${mm}${ss}Z`;
+}
+/** Parse a YAML-decoded plan-file object into a typed PlanFileShape.
+ *  Throws on shape violation. */
+export function parsePlanFile(value) {
+    if (!isObj(value)) {
+        throw new Error("plan-file must be an object");
+    }
+    const planId = strField(value, "plan_id");
+    if (!PLAN_ID_GRAMMAR.test(planId)) {
+        throw new Error(`plan_id "${planId}" does not match grammar ${PLAN_ID_GRAMMAR.source}`);
+    }
+    const createdAt = strField(value, "created_at");
+    const pendingRaw = value.pending_attestations;
+    if (!Array.isArray(pendingRaw)) {
+        throw new Error("plan-file.pending_attestations must be an array");
+    }
+    const pending = pendingRaw.map((item, idx) => {
+        if (!isObj(item)) {
+            throw new Error(`pending_attestations[${idx}] must be an object`);
+        }
+        const ts = strField(item, "target_status", "approved");
+        if (!isTargetStatus(ts)) {
+            throw new Error(`pending_attestations[${idx}].target_status invalid: ${ts}`);
+        }
+        const out = {
+            id: strField(item, "id"),
+            ownerRole: strField(item, "owner_role"),
+            approverIdentity: strField(item, "approver_identity"),
+            timestamp: strField(item, "timestamp"),
+            changeRequest: strField(item, "change_request"),
+            scope: strField(item, "scope", "first-time-approval"),
+            targetStatus: ts,
+        };
+        const oracle = item.reviewed_test_oracle;
+        if (typeof oracle === "string" && oracle.length > 0) {
+            out.reviewedTestOracle = oracle;
+        }
+        return out;
+    });
+    return { planId, createdAt, pendingAttestations: pending };
+}
+/** Serialise a PlanFileShape into a stable YAML string. The fields are
+ *  emitted in fixed order so plan files diff cleanly across edits. */
+export function serialisePlanFile(plan) {
+    const lines = [];
+    lines.push(`plan_id: ${plan.planId}`);
+    lines.push(`created_at: ${plan.createdAt}`);
+    lines.push("pending_attestations:");
+    for (const a of plan.pendingAttestations) {
+        lines.push(`  - id: ${a.id}`);
+        lines.push(`    owner_role: ${a.ownerRole}`);
+        lines.push(`    approver_identity: ${a.approverIdentity}`);
+        lines.push(`    timestamp: ${a.timestamp}`);
+        lines.push(`    change_request: ${quoteIfNeeded(a.changeRequest)}`);
+        lines.push(`    scope: ${a.scope}`);
+        lines.push(`    target_status: ${a.targetStatus}`);
+        if (a.reviewedTestOracle !== undefined) {
+            lines.push(`    reviewed_test_oracle: ${a.reviewedTestOracle}`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+function quoteIfNeeded(s) {
+    if (/^[a-zA-Z0-9_./:?=&%@+-]+$/.test(s)) {
+        return s;
+    }
+    return JSON.stringify(s);
+}
+function isTargetStatus(v) {
+    return v === "approved" || v === "deprecated" || v === "removed";
+}
+function isObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function strField(o, key, fallback) {
+    const v = o[key];
+    if (typeof v === "string" && v.length > 0) {
+        return v;
+    }
+    if (v === undefined && fallback !== undefined) {
+        return fallback;
+    }
+    throw new Error(`plan-file field ${key} must be a non-empty string`);
+}

package/dist/shared/domain/Scope.d.ts

@@ -0,0 +1 @@
+export declare function globScopeEntries(scope: readonly string[]): string[];

package/dist/shared/domain/Scope.js

@@ -0,0 +1,3 @@
+export function globScopeEntries(scope) {
+    return scope.filter((entry) => /[*?[]/.test(entry));
+}

package/dist/shared/domain/SpecApprovalRewrite.d.ts

@@ -0,0 +1,23 @@
+export type ApprovalTargetStatus = "approved" | "deprecated" | "removed";
+export interface ApprovalAttestation {
+    id: string;
+    approver: string;
+    ownerRole: string;
+    changeRequest: string;
+    scope: string;
+    targetStatus: ApprovalTargetStatus;
+    reviewedTestOracle: string | null;
+}
+export interface IdMatch {
+    id: string;
+    startLine: number;
+    endLine: number;
+    indent: string;
+}
+export interface RewriteResult {
+    newContent: string;
+    matched: IdMatch[];
+}
+export declare function rewriteApproval(content: string, req: ApprovalAttestation, when: Date): RewriteResult;
+export declare function findMatches(lines: readonly string[], idOrGlob: string): IdMatch[];
+export declare function matchId(pattern: string, candidate: string): boolean;

package/dist/shared/domain/SpecApprovalRewrite.js

@@ -0,0 +1,254 @@
+/*
+ * CST-003 / INV-004: pure rewriter shared by the approve and finalize slices;
+ * no I/O — the adapter handles read/write.
+ */
+export function rewriteApproval(content, req, when) {
+    const lines = content.split(/\r?\n/);
+    const matches = findMatches(lines, req.id);
+    if (matches.length === 0) {
+        return { newContent: content, matched: [] };
+    }
+    /* Apply matches from last to first so line indices stay stable. */
+    const sorted = [...matches].sort((a, b) => b.startLine - a.startLine);
+    let buf = [...lines];
+    for (const m of sorted) {
+        buf = applyOne(buf, m, req, when);
+    }
+    return { newContent: buf.join("\n"), matched: matches };
+}
+/*
+ * INV-007: the lifecycle anchor exists in two YAML shapes (flat
+ * `lifecycle.status:` and nested `lifecycle:` + `status:`); pick the first
+ * anchor found so it can be written back in the same shape.
+ */
+function scanAnchors(block, fallbackIndent) {
+    let statusKind = null;
+    let statusIdx = -1;
+    let statusIndent = fallbackIndent;
+    let approvalIndent = fallbackIndent;
+    let approvalIdx = -1;
+    for (let i = 0; i < block.length; i++) {
+        const line = block[i];
+        if (statusKind === null) {
+            const flat = /^(\s*)lifecycle\.status:/.exec(line);
+            if (flat !== null) {
+                statusKind = "flat";
+                statusIdx = i;
+                statusIndent = flat[1];
+                approvalIndent = flat[1];
+                continue;
+            }
+            const nestedHeader = /^(\s*)lifecycle:\s*$/.exec(line);
+            if (nestedHeader !== null) {
+                const headerIndent = nestedHeader[1];
+                const childIndent = `${headerIndent}  `;
+                for (let j = i + 1; j < block.length; j++) {
+                    const child = block[j];
+                    if (new RegExp(`^${childIndent}status:\\s*\\S`).test(child)) {
+                        statusKind = "nested";
+                        statusIdx = j;
+                        statusIndent = childIndent;
+                        approvalIndent = childIndent;
+                        break;
+                    }
+                    if (child.length > 0 && !child.startsWith(headerIndent)) {
+                        break;
+                    }
+                    if (child.length > 0 &&
+                        child.startsWith(headerIndent) &&
+                        !child.startsWith(childIndent)) {
+                        break;
+                    }
+                }
+            }
+        }
+        if (approvalIdx < 0) {
+            const ar = /^(\s*)approval_record:/.exec(line);
+            if (ar !== null) {
+                approvalIdx = i;
+            }
+        }
+    }
+    return { statusKind, statusIdx, statusIndent, approvalIndent, approvalIdx };
+}
+/*
+ * Strip the existing block (header + its deeper-indented children) before
+ * writing the new one, so repeated approvals don't interleave records.
+ */
+function approvalBlockEnd(block, approvalIdx) {
+    const headerMatch = /^(\s*)approval_record:/.exec(block[approvalIdx] ?? "");
+    const headerIndent = headerMatch !== null ? headerMatch[1].length : 0;
+    let endExclusive = approvalIdx + 1;
+    while (endExclusive < block.length) {
+        const line = block[endExclusive];
+        if (line.trim().length === 0) {
+            break;
+        }
+        const indentMatch = /^(\s*)/.exec(line);
+        const lineIndent = indentMatch !== null ? indentMatch[1].length : 0;
+        if (lineIndent <= headerIndent) {
+            break;
+        }
+        endExclusive++;
+    }
+    return endExclusive;
+}
+function applyOne(lines, m, req, when) {
+    const sliceStart = m.startLine - 1;
+    const sliceEndExclusive = m.endLine - 1;
+    const before = lines.slice(0, sliceStart);
+    const block = lines.slice(sliceStart, sliceEndExclusive);
+    const after = lines.slice(sliceEndExclusive);
+    const { statusKind, statusIdx, statusIndent, approvalIndent, approvalIdx } = scanAnchors(block, m.indent);
+    if (statusKind === null) {
+        return [...before, ...block, ...after];
+    }
+    if (statusKind === "flat") {
+        block[statusIdx] = `${statusIndent}lifecycle.status: ${req.targetStatus}`;
+    }
+    else {
+        block[statusIdx] = `${statusIndent}status: ${req.targetStatus}`;
+    }
+    const approvalLines = approvalBlock(req, when, approvalIndent);
+    if (approvalIdx >= 0) {
+        const endExclusive = approvalBlockEnd(block, approvalIdx);
+        block.splice(approvalIdx, endExclusive - approvalIdx, ...approvalLines);
+    }
+    else {
+        block.splice(statusIdx + 1, 0, ...approvalLines);
+    }
+    return [...before, ...block, ...after];
+}
+function approvalBlock(req, when, indent) {
+    const out = [
+        `${indent}approval_record:`,
+        `${indent}  owner_role: ${yamlScalar(req.ownerRole)}`,
+        `${indent}  approver_identity: ${yamlScalar(req.approver)}`,
+        `${indent}  timestamp: ${when.toISOString()}`,
+        `${indent}  change_request: ${yamlScalar(req.changeRequest)}`,
+        `${indent}  scope: ${yamlScalar(req.scope)}`,
+    ];
+    if (req.reviewedTestOracle !== null) {
+        out.push(`${indent}  reviewed_test_oracle: ${yamlScalar(req.reviewedTestOracle)}`);
+    }
+    return out;
+}
+/*
+ * Emit a value as a YAML scalar, quoting only when the raw string would parse
+ * differently as plain YAML (e.g. `:` followed by whitespace reads as a nested
+ * mapping). Plain URLs lack `: ` and stay unquoted.
+ */
+function yamlScalar(value) {
+    if (value.length === 0) {
+        return '""';
+    }
+    const needsQuoting = /:\s/.test(value) || /^[\s?\-#&*!|>'"%@`]/.test(value) || /\s$/.test(value);
+    if (!needsQuoting) {
+        return value;
+    }
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+class RecordCursor {
+    idOrGlob;
+    out;
+    start = -1;
+    id = "";
+    indent = "";
+    anchorIndent = "";
+    constructor(idOrGlob, out) {
+        this.idOrGlob = idOrGlob;
+        this.out = out;
+    }
+    close(endLine) {
+        if (this.start < 0) {
+            return;
+        }
+        if (matchId(this.idOrGlob, this.id)) {
+            this.out.push({
+                id: this.id,
+                startLine: this.start + 1,
+                endLine: endLine + 1,
+                indent: this.indent,
+            });
+        }
+        this.start = -1;
+        this.id = "";
+        this.indent = "";
+        this.anchorIndent = "";
+    }
+    open(start, id, indent, anchorIndent) {
+        this.start = start;
+        this.id = id;
+        this.indent = indent;
+        this.anchorIndent = anchorIndent;
+    }
+    isOpen() {
+        return this.start >= 0;
+    }
+    anchorIndentLength() {
+        return this.anchorIndent.length;
+    }
+}
+function classifyLine(line, i, fenceStart, cursor) {
+    if (line === "---") {
+        cursor.close(i);
+        return;
+    }
+    const listM = /^(\s*)-\s+id:\s*(\S+)/.exec(line);
+    if (listM !== null) {
+        /*
+         * INV-007: a `- id:` is a record boundary only when no record is open or
+         * it is a sibling-or-shallower list item; a deeper `- id:` is record body.
+         */
+        const lead = listM[1];
+        if (!cursor.isOpen() || lead.length <= cursor.anchorIndentLength()) {
+            cursor.close(i);
+            cursor.open(i, listM[2], `${lead}  `, lead);
+            return;
+        }
+    }
+    const flatM = /^(\s*)id:\s*(\S+)/.exec(line);
+    if (flatM !== null && fenceStart >= 0 && i === fenceStart + 1) {
+        cursor.close(i);
+        cursor.open(i, flatM[2], flatM[1], flatM[1]);
+        return;
+    }
+    if (flatM !== null && !cursor.isOpen()) {
+        cursor.open(i, flatM[2], flatM[1], flatM[1]);
+    }
+}
+export function findMatches(lines, idOrGlob) {
+    const out = [];
+    const cursor = new RecordCursor(idOrGlob, out);
+    let inFence = false;
+    let fenceStart = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!inFence && /^```yaml\s*$/.test(line)) {
+            inFence = true;
+            fenceStart = i;
+            continue;
+        }
+        if (inFence && /^```\s*$/.test(line)) {
+            cursor.close(i);
+            inFence = false;
+            fenceStart = -1;
+            continue;
+        }
+        if (!inFence) {
+            continue;
+        }
+        classifyLine(line, i, fenceStart, cursor);
+    }
+    return out;
+}
+export function matchId(pattern, candidate) {
+    if (pattern === candidate) {
+        return true;
+    }
+    if (!pattern.includes("*")) {
+        return false;
+    }
+    const re = new RegExp(`^${pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`);
+    return re.test(candidate);
+}

package/dist/shared/domain/SpecBlocks.d.ts

@@ -0,0 +1,12 @@
+export interface SpecBlock {
+    id: string;
+    type: string;
+    parsed: Record<string, unknown>;
+    raw: string;
+    line: number;
+}
+export declare function specBlocks(markdown: string): SpecBlock[];
+export declare function blocksById(blocks: readonly SpecBlock[], id: string): SpecBlock[];
+export declare function blocksByNeutralPrefix(blocks: readonly SpecBlock[], prefix: string): SpecBlock[];
+export declare function typedBlock(blocks: readonly SpecBlock[], id: string, type: string, specPath: string): SpecBlock;
+export declare function stringValue(block: SpecBlock, field: string, specPath: string): string;

package/dist/shared/domain/SpecBlocks.js

@@ -0,0 +1,96 @@
+import { parseDocument } from "yaml";
+import { configFailure } from "./Errors.js";
+export function specBlocks(markdown) {
+    return yamlDocuments(markdown).map((document) => specBlock(document));
+}
+export function blocksById(blocks, id) {
+    return blocks.filter((block) => block.id === id);
+}
+export function blocksByNeutralPrefix(blocks, prefix) {
+    return blocks.filter((block) => neutralId(block.id).startsWith(prefix));
+}
+export function typedBlock(blocks, id, type, specPath) {
+    const matches = blocksById(blocks, id).filter((block) => block.type === type);
+    if (matches.length === 0) {
+        throw configFailure("baseline-block-missing", `missing ${type} block: ${id}`, undefined, specPath);
+    }
+    if (matches.length > 1) {
+        throw configFailure("baseline-block-duplicate", `duplicate ${type} block: ${id}`, undefined, specPath);
+    }
+    return matches[0];
+}
+export function stringValue(block, field, specPath) {
+    const value = block.parsed[field];
+    if (typeof value !== "string" || value.length === 0) {
+        throw configFailure("config-invalid", `${block.id}.${field} must be a non-empty string`, undefined, specPath);
+    }
+    return value;
+}
+function specBlock(document) {
+    const parsed = parseDocument(document.raw, { prettyErrors: false });
+    if (parsed.errors.length > 0) {
+        const message = parsed.errors.map((error) => error.message).join("; ");
+        throw configFailure("config-invalid", `invalid YAML block at line ${document.line}`, message);
+    }
+    const value = parsed.toJS();
+    if (!isRecord(value)) {
+        throw configFailure("config-invalid", `YAML block at line ${document.line} must be an object`);
+    }
+    const id = value.id;
+    const type = value.type;
+    if (typeof id !== "string" || typeof type !== "string") {
+        throw configFailure("config-invalid", `YAML block at line ${document.line} must include string id and type`);
+    }
+    return { id, type, parsed: value, raw: document.raw, line: document.line };
+}
+function yamlDocuments(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const documents = [];
+    let isInsideYamlFence = false;
+    let fenceLines = [];
+    let fenceStartLine = 0;
+    lines.forEach((line, index) => {
+        if (!isInsideYamlFence && line.trim() === "```yaml") {
+            isInsideYamlFence = true;
+            fenceLines = [];
+            fenceStartLine = index + 1;
+            return;
+        }
+        if (isInsideYamlFence && line.trim() === "```") {
+            documents.push(...documentsInFence(fenceLines, fenceStartLine + 1));
+            isInsideYamlFence = false;
+            fenceLines = [];
+            return;
+        }
+        if (isInsideYamlFence) {
+            fenceLines.push(line);
+        }
+    });
+    return documents;
+}
+function documentsInFence(lines, firstLine) {
+    const documents = [];
+    let startIndex;
+    for (let index = 0; index < lines.length; index += 1) {
+        if (lines[index] !== "---") {
+            continue;
+        }
+        if (startIndex === undefined) {
+            startIndex = index + 1;
+            continue;
+        }
+        const raw = lines.slice(startIndex, index).join("\n").trim();
+        if (raw.length > 0) {
+            documents.push({ raw, line: firstLine + startIndex });
+        }
+        startIndex = undefined;
+    }
+    return documents;
+}
+function neutralId(id) {
+    const parts = id.split(":");
+    return parts[parts.length - 1];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/shared/domain/SpecRecord.d.ts

@@ -0,0 +1,17 @@
+export type LintTemplate = "Behavior" | "Invariant" | "Contract" | "Scenario" | "NFR" | "Constraint" | "Policy" | "Migration" | "Delta" | "GeneratedArtifact" | "ExternalDependency" | "LocalizationContract" | "Surface" | "BrownfieldBaseline" | "Partition" | "ImplementationBinding";
+export declare const NORMATIVE_TEMPLATES: ReadonlySet<LintTemplate>;
+export type LifecycleStatus = "draft" | "proposed" | "approved" | "deprecated" | "removed";
+export declare const VALID_LIFECYCLE_STATUS: ReadonlySet<LifecycleStatus>;
+export interface LintRecord {
+    id: string;
+    template: string | null;
+    lifecycleStatus: string | null;
+    approvalRecord: string | null;
+    testObligations: string[];
+    hasAliasedObligations: boolean;
+    parsed: Record<string, unknown>;
+    file: string;
+    line: number;
+    rawBlock: string;
+}
+export declare function lintRecordsFromMarkdown(file: string, markdown: string): LintRecord[];