agent-sdd 1.0.3

package/dist/features/finalize/application/RunFinalize.js

@@ -0,0 +1,98 @@
+import { rewriteApproval, } from "../../../shared/domain/SpecApprovalRewrite.js";
+import { lintRecordsFromMarkdown } from "../../../shared/domain/SpecRecord.js";
+import { validateFinalizeGraph, } from "../domain/ValidateFinalizeGraph.js";
+export async function runFinalize(cwd, planId, ports) {
+    const config = await ports.config.config(cwd);
+    const load = await ports.plans.load(cwd, config.plansDir, planId);
+    if (load.kind === "no-active-plan") {
+        return { kind: "no-active-plan" };
+    }
+    if (load.kind === "invalid-plan-file") {
+        return {
+            kind: "invalid-plan",
+            planId: load.planId,
+            sourcePath: load.sourcePath,
+            reason: load.reason,
+        };
+    }
+    const plan = load.plan;
+    const entries = await ports.files.resolveSpecFiles(cwd, config.lint.specFiles);
+    const records = entries.flatMap((e) => lintRecordsFromMarkdown(e.path, e.content));
+    const violations = validateFinalizeGraph(records, plan.pendingAttestations);
+    if (violations.length > 0) {
+        return { kind: "graph-violation", planId: plan.planId, violations };
+    }
+    /*
+     * INV-012: apply each attestation as a rewriteApproval against the matching
+     * record; abort before writing if any attestation fails to match.
+     */
+    const applied = applyAttestations(entries, plan.pendingAttestations, ports.clock.now());
+    if (applied.missingIds.length > 0) {
+        return {
+            kind: "no-id-match",
+            planId: plan.planId,
+            missingIds: applied.missingIds,
+        };
+    }
+    const { fileContent, finalizedIds } = applied;
+    const filesChanged = [];
+    const batch = [];
+    for (const e of entries) {
+        const next = fileContent.get(e.path);
+        if (next !== undefined && next !== e.content) {
+            batch.push({ path: e.path, content: next });
+            filesChanged.push(e.path);
+        }
+    }
+    await ports.files.writeBatch(cwd, batch);
+    const archive = await ports.plans.archive(cwd, config.plansDir, plan.planId);
+    return {
+        kind: "finalized",
+        planId: plan.planId,
+        finalizedIds,
+        filesChanged,
+        archivedPath: archive.archivedPath,
+    };
+}
+function applyAttestations(entries, attestations, when) {
+    const fileContent = new Map();
+    for (const e of entries) {
+        fileContent.set(e.path, e.content);
+    }
+    const finalizedIds = [];
+    const missingIds = [];
+    for (const a of attestations) {
+        const req = {
+            id: a.id,
+            approver: a.approverIdentity,
+            ownerRole: a.ownerRole,
+            changeRequest: a.changeRequest,
+            scope: a.scope,
+            targetStatus: a.targetStatus,
+            reviewedTestOracle: a.reviewedTestOracle ?? null,
+        };
+        const reqWhen = new Date(a.timestamp);
+        const reqClock = isNaN(reqWhen.valueOf()) ? when : reqWhen;
+        let matched = false;
+        for (const e of entries) {
+            const current = fileContent.get(e.path);
+            if (current === undefined) {
+                continue;
+            }
+            const result = rewriteApproval(current, req, reqClock);
+            if (result.matched.length === 0) {
+                continue;
+            }
+            fileContent.set(e.path, result.newContent);
+            matched = true;
+            for (const m of result.matched) {
+                finalizedIds.push(m.id);
+            }
+            break;
+        }
+        if (!matched) {
+            missingIds.push(a.id);
+        }
+    }
+    return { fileContent, finalizedIds, missingIds };
+}

package/dist/features/finalize/domain/ValidateFinalizeGraph.d.ts

@@ -0,0 +1,9 @@
+import type { LintRecord } from "../../../shared/domain/SpecRecord.js";
+import type { PendingAttestation } from "../../../shared/domain/PlanFile.js";
+export interface GraphViolation {
+    flippedId: string;
+    referencesId: string;
+    referencesStatus: string;
+    via: "members" | "policy_refs" | "target_ids" | "surface_ref";
+}
+export declare function validateFinalizeGraph(records: ReadonlyArray<LintRecord>, plan: ReadonlyArray<PendingAttestation>): GraphViolation[];

package/dist/features/finalize/domain/ValidateFinalizeGraph.js

@@ -0,0 +1,86 @@
+/*
+ * BEH-024 / BEH-025 / INV-012: prospective graph validator for `sdd finalize`
+ * — refuse if any flipped record would still reference a <approved ID after
+ * applying every pending attestation. See spec record for rationale.
+ */
+const TERMINAL_STATUSES = new Set(["approved", "deprecated", "removed"]);
+export function validateFinalizeGraph(records, plan) {
+    const byId = new Map();
+    for (const r of records) {
+        byId.set(r.id, r);
+    }
+    const planTargets = new Map();
+    for (const a of plan) {
+        planTargets.set(a.id, a.targetStatus);
+    }
+    const out = [];
+    for (const a of plan) {
+        if (a.targetStatus !== "approved") {
+            continue;
+        }
+        const rec = byId.get(a.id);
+        if (rec === undefined) {
+            continue;
+        } /* missing record is caught elsewhere */
+        for (const ref of refsOf(rec)) {
+            const refRec = byId.get(ref.id);
+            const refStatus = effectiveStatus(refRec, planTargets.get(ref.id));
+            if (refStatus === null) {
+                continue;
+            } /* missing referenced record — not a graph violation */
+            if (TERMINAL_STATUSES.has(refStatus)) {
+                continue;
+            }
+            out.push({
+                flippedId: a.id,
+                referencesId: ref.id,
+                referencesStatus: refStatus,
+                via: ref.via,
+            });
+        }
+    }
+    return out;
+}
+function effectiveStatus(rec, planTarget) {
+    if (rec === undefined) {
+        return null;
+    }
+    return planTarget ?? rec.lifecycleStatus ?? "draft";
+}
+function refsOf(rec) {
+    const out = [];
+    const v = rec.parsed;
+    /* Surface.members[] */
+    const members = v.members;
+    if (Array.isArray(members)) {
+        for (const m of members) {
+            if (typeof m === "string") {
+                out.push({ id: m, via: "members" });
+            }
+        }
+    }
+    /* surface_ref */
+    const surfaceRef = v.surface_ref;
+    if (typeof surfaceRef === "string") {
+        out.push({ id: surfaceRef, via: "surface_ref" });
+    }
+    /* policy_refs[] */
+    const policyRefs = v.policy_refs;
+    if (Array.isArray(policyRefs)) {
+        for (const p of policyRefs) {
+            if (typeof p === "string") {
+                out.push({ id: p, via: "policy_refs" });
+            }
+        }
+    }
+    /* target_ids[] (Migration / Delta) */
+    const targetIds = v.target_ids;
+    if (Array.isArray(targetIds)) {
+        for (const t of targetIds) {
+            if (typeof t === "string") {
+                out.push({ id: t, via: "target_ids" });
+            }
+        }
+    }
+    return out;
+}

package/dist/features/finalize/ports/inbound/FinalizeCommand.d.ts

@@ -0,0 +1,7 @@
+import type { CommandResult, OutputFormat } from "../../../../shared/domain/CliOutput.js";
+export interface FinalizeRequest {
+    planId?: string;
+}
+export interface FinalizeCommand {
+    execute(cwd: string, req: FinalizeRequest, format: Exclude<OutputFormat, "yaml">): Promise<CommandResult>;
+}

package/dist/features/finalize/ports/inbound/FinalizeCommand.js

@@ -0,0 +1 @@
+export {};

package/dist/features/finalize/ports/outbound/FinalizeClock.d.ts

@@ -0,0 +1,3 @@
+export interface FinalizeClock {
+    now(): Date;
+}

package/dist/features/finalize/ports/outbound/FinalizeClock.js

@@ -0,0 +1 @@
+export {};

package/dist/features/finalize/ports/outbound/FinalizeConfigPort.d.ts

@@ -0,0 +1,4 @@
+import type { SddConfig } from "../../../../shared/domain/Config.js";
+export interface FinalizeConfigPort {
+    config(repoRoot: string): Promise<SddConfig>;
+}

package/dist/features/finalize/ports/outbound/FinalizeConfigPort.js

@@ -0,0 +1 @@
+export {};

package/dist/features/finalize/ports/outbound/FinalizeFileSystem.d.ts

@@ -0,0 +1,14 @@
+export interface SpecFileEntry {
+    path: string;
+    content: string;
+}
+export interface FinalizeFileSystem {
+    resolveSpecFiles(repoRoot: string, patterns: readonly string[]): Promise<SpecFileEntry[]>;
+    /** Atomic batch write: either every (path, content) pair lands or none.
+     *  Implementations write to .tmp files and then rename in a deterministic
+     *  order so a mid-flight failure leaves the working tree byte-stable. */
+    writeBatch(repoRoot: string, entries: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>): Promise<void>;
+}

package/dist/features/finalize/ports/outbound/FinalizeFileSystem.js

@@ -0,0 +1 @@
+export {};

package/dist/features/finalize/ports/outbound/PlanRepo.d.ts

@@ -0,0 +1,21 @@
+import type { PlanFileShape } from "../../../../shared/domain/PlanFile.js";
+export type PlanLoad = {
+    kind: "found";
+    plan: PlanFileShape;
+    sourcePath: string;
+} | {
+    kind: "no-active-plan";
+} | {
+    kind: "invalid-plan-file";
+    planId: string;
+    sourcePath: string;
+    reason: string;
+};
+export interface PlanRepo {
+    load(repoRoot: string, plansDir: string, planId: string | undefined): Promise<PlanLoad>;
+    /** Atomically move the plan file to <plansDir>/finalized/<plan_id>.yaml.
+     *  Also clears <plansDir>/.active if it pointed at this plan_id. */
+    archive(repoRoot: string, plansDir: string, planId: string): Promise<{
+        archivedPath: string;
+    }>;
+}

package/dist/features/finalize/ports/outbound/PlanRepo.js

@@ -0,0 +1 @@
+export {};

package/dist/features/install/adapters/inbound/CliInstallHandler.d.ts

@@ -0,0 +1,8 @@
+import { type CommandResult } from "../../../../shared/domain/CliOutput.js";
+import { type InstallPorts } from "../../application/InstallRules.js";
+import type { InstallCommand, InstallOptions, InstallTarget } from "../../ports/inbound/InstallCommand.js";
+export declare class CliInstallHandler implements InstallCommand {
+    private readonly ports;
+    constructor(ports: InstallPorts);
+    execute(target: InstallTarget, options: InstallOptions, format: "json" | "human"): Promise<CommandResult>;
+}

package/dist/features/install/adapters/inbound/CliInstallHandler.js

@@ -0,0 +1,54 @@
+import { ok } from "../../../../shared/domain/CliOutput.js";
+import { installRules, } from "../../application/InstallRules.js";
+export class CliInstallHandler {
+    ports;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    async execute(target, options, format) {
+        const outcome = await installRules(target, options.dryRun, this.ports, options.scope);
+        return format === "json" ? toJson(outcome) : toHuman(outcome);
+    }
+}
+function toJson(outcome) {
+    if (!outcome.ok) {
+        const body = JSON.stringify({
+            format_version: 1,
+            ok: false,
+            reason: outcome.reason,
+            detail: outcome.message,
+        });
+        return { exitCode: outcome.exitCode, stdout: `${body}\n`, stderr: "" };
+    }
+    return ok(JSON.stringify({
+        format_version: 1,
+        ok: true,
+        dry_run: outcome.dryRun,
+        scope: outcome.scope,
+        targets: outcome.targets,
+        actions: outcome.actions.map((a) => ({
+            target: a.target,
+            kind: a.kind,
+            op: a.op,
+            path: a.path,
+            note: a.note,
+        })),
+    }));
+}
+function toHuman(outcome) {
+    if (!outcome.ok) {
+        return {
+            exitCode: outcome.exitCode,
+            stdout: "",
+            stderr: `${outcome.reason}: ${outcome.message}\n`,
+        };
+    }
+    const header = outcome.dryRun
+        ? `sdd install (dry run) — ${outcome.targets.join(", ")}: ${outcome.actions.length} action(s) planned`
+        : `sdd install — ${outcome.targets.join(", ")}: ${outcome.actions.length} action(s) applied`;
+    const lines = outcome.actions.map((a) => {
+        const note = a.note ? `  (${a.note})` : "";
+        return `  ${a.op.padEnd(11)} ${a.target.padEnd(6)} ${a.path}${note}`;
+    });
+    return ok([header, ...lines].join("\n"));
+}

package/dist/features/install/adapters/outbound/NodeInstallSource.d.ts

@@ -0,0 +1,7 @@
+import type { InstallSource } from "../../ports/outbound/InstallSource.js";
+export declare class NodeInstallSource implements InstallSource {
+    private readonly rulesRoot;
+    constructor(rulesRoot?: string);
+    manifestText(): Promise<string | null>;
+    readArtifact(source: string): Promise<string | null>;
+}

package/dist/features/install/adapters/outbound/NodeInstallSource.js

@@ -0,0 +1,24 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const DEFAULT_RULES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "..", "rules");
+export class NodeInstallSource {
+    rulesRoot;
+    constructor(rulesRoot = DEFAULT_RULES_ROOT) {
+        this.rulesRoot = rulesRoot;
+    }
+    manifestText() {
+        return readTextOrNull(resolve(this.rulesRoot, "manifest.json"));
+    }
+    readArtifact(source) {
+        return readTextOrNull(resolve(this.rulesRoot, source));
+    }
+}
+async function readTextOrNull(absPath) {
+    try {
+        return await readFile(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/features/install/adapters/outbound/NodeInstallTargetFs.d.ts

@@ -0,0 +1,7 @@
+import type { InstallTargetFs } from "../../ports/outbound/InstallTargetFs.js";
+export declare class NodeInstallTargetFs implements InstallTargetFs {
+    homeRoot(): string;
+    projectRoot(): string;
+    readText(absPath: string): Promise<string | null>;
+    writeText(absPath: string, content: string, executable: boolean): Promise<void>;
+}

package/dist/features/install/adapters/outbound/NodeInstallTargetFs.js

@@ -0,0 +1,30 @@
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import process from "node:process";
+export class NodeInstallTargetFs {
+    homeRoot() {
+        const override = process.env.SDD_INSTALL_HOME;
+        return override !== undefined && override.length > 0 ? override : homedir();
+    }
+    projectRoot() {
+        return process.cwd();
+    }
+    async readText(absPath) {
+        try {
+            return await readFile(absPath, "utf8");
+        }
+        catch {
+            return null;
+        }
+    }
+    async writeText(absPath, content, executable) {
+        await mkdir(dirname(absPath), { recursive: true });
+        const tmp = `${absPath}.tmp.${process.pid}.${Date.now()}`;
+        await writeFile(tmp, content, "utf8");
+        if (executable) {
+            await chmod(tmp, 0o755);
+        }
+        await rename(tmp, absPath);
+    }
+}

package/dist/features/install/application/InstallRules.d.ts

@@ -0,0 +1,10 @@
+import type { InstallAction, InstallOutcome } from "../domain/InstallResult.js";
+import { type InstallScope, type InstallTarget } from "../domain/InstallTarget.js";
+import type { InstallSource } from "../ports/outbound/InstallSource.js";
+import type { InstallTargetFs } from "../ports/outbound/InstallTargetFs.js";
+export type { InstallAction, InstallOutcome };
+export interface InstallPorts {
+    source: InstallSource;
+    fs: InstallTargetFs;
+}
+export declare function installRules(target: InstallTarget, dryRun: boolean, ports: InstallPorts, scope?: InstallScope): Promise<InstallOutcome>;

package/dist/features/install/application/InstallRules.js

@@ -0,0 +1,73 @@
+import { buildPlan, homePath, installLayout, } from "../domain/InstallPlan.js";
+import { agentsFor, } from "../domain/InstallTarget.js";
+import { ManifestError, parseManifest } from "../domain/RuleManifest.js";
+export async function installRules(target, dryRun, ports, scope = "user") {
+    const manifestText = await ports.source.manifestText();
+    if (manifestText === null) {
+        return {
+            ok: false,
+            exitCode: 1,
+            reason: "manifest-missing",
+            message: "packaged rules/manifest.json was not found",
+        };
+    }
+    let manifest;
+    try {
+        manifest = parseManifest(manifestText);
+    }
+    catch (error) {
+        if (error instanceof ManifestError) {
+            return {
+                ok: false,
+                exitCode: 1,
+                reason: "manifest-invalid",
+                message: error.message,
+            };
+        }
+        throw error;
+    }
+    const agents = agentsFor(target);
+    const sources = new Map();
+    for (const artifact of manifest.artifacts) {
+        if (!artifact.targets.some((t) => agents.includes(t)) ||
+            sources.has(artifact.source)) {
+            continue;
+        }
+        const content = await ports.source.readArtifact(artifact.source);
+        if (content === null) {
+            return {
+                ok: false,
+                exitCode: 1,
+                reason: "artifact-missing",
+                message: `packaged rule file was not found: ${artifact.source}`,
+            };
+        }
+        sources.set(artifact.source, content);
+    }
+    const layout = installLayout(scope);
+    const home = scope === "project" ? ports.fs.projectRoot() : ports.fs.homeRoot();
+    const writes = [];
+    const actions = [];
+    for (const agent of agents) {
+        const existing = {
+            claudeMd: agent === "claude"
+                ? await ports.fs.readText(homePath(home, layout.claudeMemoryRel))
+                : null,
+            settingsJson: agent === "claude"
+                ? await ports.fs.readText(homePath(home, ".claude/settings.json"))
+                : null,
+            agentsMd: agent === "codex"
+                ? await ports.fs.readText(homePath(home, layout.codexMemoryRel))
+                : null,
+        };
+        const plan = buildPlan(manifest, agent, sources, existing, home, scope);
+        writes.push(...plan.writes);
+        actions.push(...plan.actions);
+    }
+    if (!dryRun) {
+        for (const write of writes) {
+            await ports.fs.writeText(write.absPath, write.content, write.executable);
+        }
+    }
+    return { ok: true, dryRun, scope, targets: [...agents], actions };
+}

package/dist/features/install/domain/InstallPlan.d.ts

@@ -0,0 +1,27 @@
+import type { AgentTarget, InstallScope } from "./InstallTarget.js";
+import type { InstallAction } from "./InstallResult.js";
+import type { RuleManifest } from "./RuleManifest.js";
+export interface PlannedWrite {
+    absPath: string;
+    content: string;
+    executable: boolean;
+}
+export interface ExistingTargetFiles {
+    claudeMd: string | null;
+    settingsJson: string | null;
+    agentsMd: string | null;
+}
+export interface InstallPlanResult {
+    writes: PlannedWrite[];
+    actions: InstallAction[];
+}
+export interface InstallLayout {
+    claudeMemoryRel: string;
+    codexMemoryRel: string;
+    claudeImportPrefix: string;
+    codexRulePrefix: string;
+    hookCommand(home: string, source: string): string;
+}
+export declare function installLayout(scope: InstallScope): InstallLayout;
+export declare function buildPlan(manifest: RuleManifest, agent: AgentTarget, sources: ReadonlyMap<string, string>, existing: ExistingTargetFiles, home: string, scope?: InstallScope): InstallPlanResult;
+export declare function homePath(home: string, relPath: string): string;