reffy-cli 0.7.0 → 1.0.0

package/dist/plan.js

@@ -0,0 +1,298 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+function normalizeKebab(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function deriveCapabilityId(changeId) {
+    return changeId.replace(/^(add|update|remove|refactor)-/, "") || changeId;
+}
+function deriveTitle(changeId) {
+    return changeId
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function deriveRequirementTitle(title) {
+    return title.replace(/^Add\s+/i, "").replace(/^Update\s+/i, "").replace(/^Refactor\s+/i, "").trim() || title;
+}
+function pushUnique(list, value) {
+    const next = value.trim().replace(/\s+/g, " ");
+    if (!next)
+        return;
+    if (!list.includes(next))
+        list.push(next);
+}
+function collectSignals(artifactInputs) {
+    const signals = {
+        problems: [],
+        proposedFeatures: [],
+        openQuestions: [],
+        acceptanceCriteria: [],
+    };
+    for (const artifact of artifactInputs) {
+        for (const item of artifact.problem)
+            pushUnique(signals.problems, item);
+        for (const item of artifact.proposedFeatures)
+            pushUnique(signals.proposedFeatures, item);
+        for (const item of artifact.openQuestions)
+            pushUnique(signals.openQuestions, item);
+        for (const item of artifact.acceptanceCriteria)
+            pushUnique(signals.acceptanceCriteria, item);
+    }
+    return signals;
+}
+function lowerInitial(text) {
+    if (!text)
+        return text;
+    return `${text.charAt(0).toLowerCase()}${text.slice(1)}`;
+}
+function toShallStatement(value) {
+    const trimmed = value.trim().replace(/\.$/, "");
+    if (!trimmed) {
+        return "The system SHALL implement the approved behavior described by this change.";
+    }
+    if (/^the system shall\b/i.test(trimmed)) {
+        return trimmed.replace(/^the system shall\b/i, "The system SHALL").replace(/\.$/, "") + ".";
+    }
+    return `The system SHALL ${lowerInitial(trimmed)}.`;
+}
+function buildWhyText(signals, artifactCount) {
+    if (signals.problems.length === 0) {
+        return "This change is being scaffolded from indexed Reffy artifacts so the implementation plan stays connected to the ideation context captured in `.reffy/`.";
+    }
+    const summary = signals.problems.slice(0, 3).join(" ");
+    if (artifactCount > 1) {
+        return `${summary} This proposal synthesizes planning context from ${String(artifactCount)} related Reffy artifacts.`;
+    }
+    return summary;
+}
+function buildImpactText(capabilityId, signals) {
+    const codeAreas = [];
+    for (const item of signals.proposedFeatures) {
+        const lowered = item.toLowerCase();
+        if (lowered.includes("proposal"))
+            pushUnique(codeAreas, "planning scaffold generation");
+        if (lowered.includes("task"))
+            pushUnique(codeAreas, "task scaffold generation");
+        if (lowered.includes("traceability") || lowered.includes("manifest"))
+            pushUnique(codeAreas, "manifest traceability");
+        if (lowered.includes("design"))
+            pushUnique(codeAreas, "design scaffold generation");
+    }
+    const affectedCode = codeAreas.length > 0 ? codeAreas.join(", ") : "to be filled in during proposal refinement";
+    return `## Impact
+- Affected specs: \`${capabilityId}\`
+- Affected code: ${affectedCode}`;
+}
+function normalizeHeading(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9 ]+/g, "");
+}
+function extractMarkdownSections(content) {
+    const sections = {};
+    let current = "root";
+    sections[current] = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const heading = rawLine.match(/^#{1,6}\s+(.+)$/)?.[1];
+        if (heading) {
+            current = normalizeHeading(heading);
+            sections[current] ??= [];
+            continue;
+        }
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (line.startsWith("- ") || line.startsWith("* ")) {
+            sections[current].push(line.slice(2).trim());
+        }
+        else {
+            sections[current].push(line);
+        }
+    }
+    return sections;
+}
+async function loadArtifactPlanningInputs(store, artifacts) {
+    const inputs = [];
+    for (const artifact of artifacts) {
+        let content = "";
+        try {
+            content = await fs.readFile(store.getArtifactPath(artifact), "utf8");
+        }
+        catch {
+            content = "";
+        }
+        const sections = extractMarkdownSections(content);
+        inputs.push({
+            filename: artifact.filename,
+            name: artifact.name,
+            problem: [...(sections["problem"] ?? []), ...(sections["why"] ?? [])],
+            proposedFeatures: [...(sections["proposed feature"] ?? []), ...(sections["what changes"] ?? [])],
+            openQuestions: [...(sections["open questions"] ?? []), ...(sections["questions"] ?? [])],
+            acceptanceCriteria: [...(sections["acceptance criteria"] ?? []), ...(sections["success criteria"] ?? [])],
+        });
+    }
+    return inputs;
+}
+function buildProposal(title, capabilityId, artifactInputs) {
+    const signals = collectSignals(artifactInputs);
+    const references = artifactInputs.length === 0
+        ? "No Reffy references used."
+        : artifactInputs.map((artifact) => `- \`${artifact.filename}\` - planning input artifact`).join("\n");
+    const changeBullets = signals.proposedFeatures.length > 0
+        ? signals.proposedFeatures.map((item) => `- ${item}`).join("\n")
+        : `- Create or update the \`${capabilityId}\` capability.\n- Generate initial proposal, tasks, and spec delta scaffolds from selected Reffy artifacts.\n- Preserve explicit traceability back to the source planning artifacts.`;
+    return `# Change: ${title}
+
+## Why
+${buildWhyText(signals, artifactInputs.length)}
+
+## What Changes
+${changeBullets}
+
+${buildImpactText(capabilityId, signals)}
+
+## Reffy References
+${references}
+`;
+}
+function buildTasks(artifactInputs) {
+    const signals = collectSignals(artifactInputs);
+    const implementation = signals.proposedFeatures.length > 0
+        ? signals.proposedFeatures.map((item, index) => `- [ ] 1.${index + 1} ${item}`).join("\n")
+        : `- [ ] 1.1 Review selected Reffy artifacts and confirm proposal scope.
+- [ ] 1.2 Refine proposal details and technical design decisions.
+- [ ] 1.3 Implement the scoped behavior changes.
+- [ ] 1.4 Add or update tests for the changed behavior.`;
+    const verification = signals.acceptanceCriteria.length > 0
+        ? signals.acceptanceCriteria.map((item, index) => `- [ ] 2.${index + 1} Verify ${item}`).join("\n")
+        : `- [ ] 2.1 Run the relevant automated checks.
+- [ ] 2.2 Validate the change with \`reffy plan validate <change-id>\`.
+- [ ] 2.3 Review the generated ReffySpec files for correctness.`;
+    return `## 1. Implementation
+${implementation}
+
+## 2. Verification
+${verification}
+`;
+}
+function buildDesign(artifactInputs) {
+    const signals = collectSignals(artifactInputs);
+    const refs = artifactInputs.length === 0 ? "- None yet." : artifactInputs.map((artifact) => `- ${artifact.filename}`).join("\n");
+    const goalText = signals.proposedFeatures.length > 0
+        ? signals.proposedFeatures.map((goal) => `  - ${goal}`).join("\n")
+        : "  - Refine the implementation approach for this change.";
+    const questionText = signals.openQuestions.length > 0 ? signals.openQuestions.map((question) => `- ${question}`).join("\n") : "- None yet.";
+    const contextText = signals.problems.length > 0
+        ? signals.problems.slice(0, 4).map((problem) => `- ${problem}`).join("\n")
+        : "- Planning context will be refined during proposal review.";
+    const decisionText = signals.proposedFeatures.length > 0
+        ? signals.proposedFeatures.slice(0, 3).map((feature) => `- Decision: Prioritize ${lowerInitial(feature)}.\n  - Rationale: This came directly from the approved Reffy artifact set.`).join("\n")
+        : "- Decision: Scope refinement pending proposal review.\n  - Rationale: This file is an initial scaffold.";
+    return `## Context
+This design scaffold was generated from Reffy artifacts to keep planning traceable to upstream ideation instead of treating the artifacts as detached brainstorming notes.
+
+### Problem Summary
+${contextText}
+
+## Goals / Non-Goals
+- Goals:
+${goalText}
+  - Preserve traceability to the selected Reffy artifacts.
+- Non-Goals:
+  - Finalize every implementation detail before proposal review.
+
+## Decisions
+${decisionText}
+
+## Reffy Inputs
+${refs}
+
+## Open Questions
+${questionText}
+`;
+}
+function buildSpecDelta(requirementTitle, artifactInputs) {
+    const signals = collectSignals(artifactInputs);
+    const requirementText = signals.proposedFeatures[0]?.trim();
+    const scenarioWhen = signals.acceptanceCriteria[0]?.trim();
+    return `## ADDED Requirements
+### Requirement: ${requirementTitle}
+${requirementText ? toShallStatement(requirementText) : "The system SHALL implement the approved behavior described by this change."}
+
+#### Scenario: Planned change is delivered
+- **WHEN** ${scenarioWhen ? scenarioWhen.replace(/\.$/, "") : "the implementation for this change is completed"}
+- **THEN** the system behavior matches the approved proposal
+- **AND** the updated behavior is covered by verification steps
+`;
+}
+async function ensureEmptyChangeDir(changeDir, overwrite) {
+    try {
+        const existing = await fs.readdir(changeDir);
+        if (existing.length > 0 && !overwrite) {
+            throw new Error(`Change directory already exists and is not empty: ${changeDir}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+export async function createPlanScaffold(store, input) {
+    const artifacts = await store.listArtifacts();
+    const requested = new Set((input.artifactFilters ?? []).map((entry) => entry.trim()).filter(Boolean));
+    const selected = input.includeAllArtifacts || requested.size === 0
+        ? artifacts
+        : artifacts.filter((artifact) => requested.has(artifact.filename) || requested.has(artifact.id));
+    if (artifacts.length > 0 && selected.length === 0) {
+        throw new Error("No indexed artifacts matched the requested filters");
+    }
+    const changeId = normalizeKebab(input.changeId);
+    if (!changeId) {
+        throw new Error("change id must contain at least one alphanumeric character");
+    }
+    const title = input.title?.trim() || deriveTitle(changeId);
+    const capabilityId = normalizeKebab(deriveCapabilityId(changeId));
+    const artifactInputs = await loadArtifactPlanningInputs(store, selected);
+    const changeDir = path.join(store.repoRoot, DEFAULT_PLANNING_DIRNAME, "changes", changeId);
+    const specDir = path.join(changeDir, "specs", capabilityId);
+    await ensureEmptyChangeDir(changeDir, input.overwrite ?? false);
+    await fs.mkdir(specDir, { recursive: true });
+    const files = [
+        {
+            rel: path.join(DEFAULT_PLANNING_DIRNAME, "changes", changeId, "proposal.md"),
+            content: buildProposal(title, capabilityId, artifactInputs),
+        },
+        {
+            rel: path.join(DEFAULT_PLANNING_DIRNAME, "changes", changeId, "tasks.md"),
+            content: buildTasks(artifactInputs),
+        },
+        {
+            rel: path.join(DEFAULT_PLANNING_DIRNAME, "changes", changeId, "design.md"),
+            content: buildDesign(artifactInputs),
+        },
+        {
+            rel: path.join(DEFAULT_PLANNING_DIRNAME, "changes", changeId, "specs", capabilityId, "spec.md"),
+            content: buildSpecDelta(deriveRequirementTitle(title), artifactInputs),
+        },
+    ];
+    for (const file of files) {
+        const abs = path.join(store.repoRoot, file.rel);
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, file.content, "utf8");
+    }
+    const writtenFiles = files.map((file) => file.rel.split(path.sep).join("/"));
+    const linkResult = await store.linkPlanningOutputs(selected.map((artifact) => artifact.filename), writtenFiles, changeId);
+    return {
+        change_id: changeId,
+        change_dir: changeDir,
+        selected_artifacts: selected.map((artifact) => artifact.filename),
+        written_files: writtenFiles,
+        linked_artifacts: linkResult.linked,
+    };
+}

package/dist/planning-paths.d.ts

@@ -0,0 +1,18 @@
+export declare const DEFAULT_PLANNING_DIRNAME = "reffyspec";
+export declare const LEGACY_PLANNING_DIRNAME = "openspec";
+export type PlanningMode = "canonical" | "legacy" | "dual" | "new";
+export interface PlanningState {
+    canonicalDir: string;
+    legacyDir: string;
+    canonicalExists: boolean;
+    legacyExists: boolean;
+    mode: PlanningMode;
+    activeDirName: string;
+    activeDir: string;
+}
+export declare function resolveCanonicalPlanningDir(repoRoot: string): string;
+export declare function resolveLegacyPlanningDir(repoRoot: string): string;
+export declare function detectPlanningState(repoRoot: string): PlanningState;
+export declare function resolvePlanningDirName(repoRoot: string): string;
+export declare function resolvePlanningDir(repoRoot: string): string;
+export declare function looksLikePlanningDir(targetPath: string): boolean;

package/dist/planning-paths.js

@@ -0,0 +1,56 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+export const DEFAULT_PLANNING_DIRNAME = "reffyspec";
+export const LEGACY_PLANNING_DIRNAME = "openspec";
+function isDirectory(targetPath) {
+    try {
+        return statSync(targetPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveCanonicalPlanningDir(repoRoot) {
+    return path.join(repoRoot, DEFAULT_PLANNING_DIRNAME);
+}
+export function resolveLegacyPlanningDir(repoRoot) {
+    return path.join(repoRoot, LEGACY_PLANNING_DIRNAME);
+}
+export function detectPlanningState(repoRoot) {
+    const canonicalDir = resolveCanonicalPlanningDir(repoRoot);
+    const legacyDir = resolveLegacyPlanningDir(repoRoot);
+    const canonicalExists = isDirectory(canonicalDir);
+    const legacyExists = isDirectory(legacyDir);
+    let mode = "new";
+    if (canonicalExists && legacyExists) {
+        mode = "dual";
+    }
+    else if (canonicalExists) {
+        mode = "canonical";
+    }
+    else if (legacyExists) {
+        mode = "legacy";
+    }
+    const activeDirName = mode === "legacy" ? LEGACY_PLANNING_DIRNAME : DEFAULT_PLANNING_DIRNAME;
+    return {
+        canonicalDir,
+        legacyDir,
+        canonicalExists,
+        legacyExists,
+        mode,
+        activeDirName,
+        activeDir: path.join(repoRoot, activeDirName),
+    };
+}
+export function resolvePlanningDirName(repoRoot) {
+    return detectPlanningState(repoRoot).activeDirName;
+}
+export function resolvePlanningDir(repoRoot) {
+    return path.join(repoRoot, resolvePlanningDirName(repoRoot));
+}
+export function looksLikePlanningDir(targetPath) {
+    const base = path.basename(targetPath);
+    return ((base === DEFAULT_PLANNING_DIRNAME || base === LEGACY_PLANNING_DIRNAME) &&
+        existsSync(path.join(targetPath, "changes")) &&
+        existsSync(path.join(targetPath, "specs")));
+}

package/dist/planning-workspace.d.ts

@@ -0,0 +1,8 @@
+import { type PlanningState } from "./planning-paths.js";
+export interface PlanningPreparationResult {
+    state: PlanningState;
+    migrated: boolean;
+    created: boolean;
+    message?: string;
+}
+export declare function prepareCanonicalPlanningLayout(repoRoot: string): Promise<PlanningPreparationResult>;

package/dist/planning-workspace.js

@@ -0,0 +1,40 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DEFAULT_PLANNING_DIRNAME, LEGACY_PLANNING_DIRNAME, detectPlanningState, resolveCanonicalPlanningDir, } from "./planning-paths.js";
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureCanonicalPlanningStructure(repoRoot) {
+    const planningDir = resolveCanonicalPlanningDir(repoRoot);
+    let created = false;
+    if (!(await pathExists(planningDir))) {
+        created = true;
+    }
+    await fs.mkdir(path.join(planningDir, "changes", "archive"), { recursive: true });
+    await fs.mkdir(path.join(planningDir, "specs"), { recursive: true });
+    return created;
+}
+export async function prepareCanonicalPlanningLayout(repoRoot) {
+    const current = detectPlanningState(repoRoot);
+    if (current.mode === "legacy") {
+        await fs.rename(current.legacyDir, current.canonicalDir);
+        return {
+            state: detectPlanningState(repoRoot),
+            migrated: true,
+            created: false,
+            message: `Migrated ${LEGACY_PLANNING_DIRNAME}/ to ${DEFAULT_PLANNING_DIRNAME}/`,
+        };
+    }
+    const created = await ensureCanonicalPlanningStructure(repoRoot);
+    return {
+        state: detectPlanningState(repoRoot),
+        migrated: false,
+        created,
+    };
+}

package/dist/refs-paths.d.ts

@@ -1,5 +1,18 @@
 export declare const DEFAULT_REFS_DIRNAME = ".reffy";
 export declare const LEGACY_REFS_DIRNAME = ".references";
+export type WorkspaceMode = "canonical" | "legacy" | "dual" | "new";
+export interface WorkspaceState {
+    canonicalDir: string;
+    legacyDir: string;
+    canonicalExists: boolean;
+    legacyExists: boolean;
+    mode: WorkspaceMode;
+    activeDirName: string;
+    activeDir: string;
+}
 export declare function resolveRefsDirName(repoRoot: string): string;
 export declare function resolveRefsDir(repoRoot: string): string;
+export declare function resolveCanonicalRefsDir(repoRoot: string): string;
+export declare function resolveLegacyRefsDir(repoRoot: string): string;
+export declare function detectWorkspaceState(repoRoot: string): WorkspaceState;
 export declare function looksLikeRefsDir(targetPath: string): boolean;

package/dist/refs-paths.js

@@ -11,19 +11,44 @@ function isDirectory(targetPath) {
     }
 }
 export function resolveRefsDirName(repoRoot) {
-    const reffyDir = path.join(repoRoot, DEFAULT_REFS_DIRNAME);
-    if (isDirectory(reffyDir)) {
-        return DEFAULT_REFS_DIRNAME;
-    }
-    const legacyDir = path.join(repoRoot, LEGACY_REFS_DIRNAME);
-    if (isDirectory(legacyDir)) {
-        return LEGACY_REFS_DIRNAME;
-    }
-    return DEFAULT_REFS_DIRNAME;
+    return detectWorkspaceState(repoRoot).activeDirName;
 }
 export function resolveRefsDir(repoRoot) {
     return path.join(repoRoot, resolveRefsDirName(repoRoot));
 }
+export function resolveCanonicalRefsDir(repoRoot) {
+    return path.join(repoRoot, DEFAULT_REFS_DIRNAME);
+}
+export function resolveLegacyRefsDir(repoRoot) {
+    return path.join(repoRoot, LEGACY_REFS_DIRNAME);
+}
+export function detectWorkspaceState(repoRoot) {
+    const canonicalDir = resolveCanonicalRefsDir(repoRoot);
+    const legacyDir = resolveLegacyRefsDir(repoRoot);
+    const canonicalExists = isDirectory(canonicalDir);
+    const legacyExists = isDirectory(legacyDir);
+    let mode = "new";
+    if (canonicalExists && legacyExists) {
+        mode = "dual";
+    }
+    else if (canonicalExists) {
+        mode = "canonical";
+    }
+    else if (legacyExists) {
+        mode = "legacy";
+    }
+    const activeDirName = mode === "legacy" ? LEGACY_REFS_DIRNAME : DEFAULT_REFS_DIRNAME;
+    const activeDir = path.join(repoRoot, activeDirName);
+    return {
+        canonicalDir,
+        legacyDir,
+        canonicalExists,
+        legacyExists,
+        mode,
+        activeDirName,
+        activeDir,
+    };
+}
 export function looksLikeRefsDir(targetPath) {
     const base = path.basename(targetPath);
     return ((base === DEFAULT_REFS_DIRNAME || base === LEGACY_REFS_DIRNAME) &&

package/dist/spec-runtime.d.ts

@@ -0,0 +1,14 @@
+export interface SpecSummary {
+    id: string;
+    title: string;
+    spec_path: string;
+    design_path?: string;
+    purpose?: string;
+    requirement_count: number;
+}
+export interface SpecShowResult extends SpecSummary {
+    spec: string;
+    design?: string;
+}
+export declare function listSpecs(repoRoot: string): Promise<SpecSummary[]>;
+export declare function showSpec(repoRoot: string, specId: string): Promise<SpecShowResult>;

package/dist/spec-runtime.js

@@ -0,0 +1,82 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+const SPEC_HEADING_SUFFIX = " Specification";
+const PURPOSE_HEADING = "## Purpose";
+const REQUIREMENT_HEADING_PATTERN = /^###\s+Requirement:\s+(.+)$/;
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function listDirectories(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+function countRequirements(content) {
+    return content.split(/\r?\n/).filter((line) => REQUIREMENT_HEADING_PATTERN.test(line)).length;
+}
+function extractSpecTitle(content, fallback) {
+    for (const line of content.split(/\r?\n/)) {
+        if (line.startsWith("# ")) {
+            const title = line.slice(2).trim();
+            return title.endsWith(SPEC_HEADING_SUFFIX) ? title.slice(0, -SPEC_HEADING_SUFFIX.length) : title || fallback;
+        }
+    }
+    return fallback;
+}
+function extractPurpose(content) {
+    const lines = content.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.trim() === PURPOSE_HEADING);
+    if (start === -1)
+        return undefined;
+    const purposeLines = [];
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const line = lines[i]?.trim() ?? "";
+        if (!line)
+            continue;
+        if (line.startsWith("## "))
+            break;
+        purposeLines.push(line);
+    }
+    return purposeLines.length > 0 ? purposeLines.join(" ") : undefined;
+}
+async function buildSpecSummary(repoRoot, specId) {
+    const specDir = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "specs", specId);
+    const specPath = path.join(specDir, "spec.md");
+    const designPath = path.join(specDir, "design.md");
+    const content = await fs.readFile(specPath, "utf8");
+    return {
+        id: specId,
+        title: extractSpecTitle(content, specId),
+        spec_path: specPath,
+        design_path: (await pathExists(designPath)) ? designPath : undefined,
+        purpose: extractPurpose(content),
+        requirement_count: countRequirements(content),
+    };
+}
+export async function listSpecs(repoRoot) {
+    const specsRoot = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "specs");
+    const specIds = await listDirectories(specsRoot);
+    const summaries = [];
+    for (const specId of specIds) {
+        const specPath = path.join(specsRoot, specId, "spec.md");
+        if (!(await pathExists(specPath)))
+            continue;
+        summaries.push(await buildSpecSummary(repoRoot, specId));
+    }
+    return summaries.sort((a, b) => a.id.localeCompare(b.id));
+}
+export async function showSpec(repoRoot, specId) {
+    const summary = await buildSpecSummary(repoRoot, specId);
+    const design = summary.design_path ? await fs.readFile(summary.design_path, "utf8").catch(() => undefined) : undefined;
+    return {
+        ...summary,
+        spec: await fs.readFile(summary.spec_path, "utf8"),
+        design,
+    };
+}

package/dist/storage.d.ts

@@ -27,6 +27,12 @@ export declare class ReferencesStore {
         total: number;
     }>;
     validateManifest(): Promise<import("./manifest.js").ManifestValidationResult>;
+    linkPlanningOutputs(artifactFilenames: string[], outputPaths: string[], changeId: string): Promise<{
+        linked: number;
+    }>;
+    rewriteDerivedOutputPaths(pathMap: Record<string, string>): Promise<{
+        updated: number;
+    }>;
     updateArtifact(artifactId: string, input: {
         name?: string | null;
         content?: string | null;

package/dist/storage.js

@@ -198,6 +198,56 @@ export class ReferencesStore {
     async validateManifest() {
         return validateManifest(this.manifestPath, this.artifactsDir);
     }
+    async linkPlanningOutputs(artifactFilenames, outputPaths, changeId) {
+        const manifest = await this.readManifest();
+        const targets = new Set(artifactFilenames);
+        let linked = 0;
+        for (const artifact of manifest.artifacts) {
+            if (!targets.has(artifact.filename))
+                continue;
+            artifact.related_changes = Array.from(new Set([...(artifact.related_changes ?? []), changeId]));
+            artifact.derived_outputs = Array.from(new Set([...(artifact.derived_outputs ?? []), ...outputPaths]));
+            artifact.updated_at = utcNow();
+            linked += 1;
+        }
+        if (linked > 0) {
+            manifest.updated_at = utcNow();
+            await this.writeManifest(manifest);
+        }
+        return { linked };
+    }
+    async rewriteDerivedOutputPaths(pathMap) {
+        const replacements = Object.entries(pathMap);
+        if (replacements.length === 0) {
+            return { updated: 0 };
+        }
+        const manifest = await this.readManifest();
+        let updated = 0;
+        for (const artifact of manifest.artifacts) {
+            const outputs = artifact.derived_outputs ?? [];
+            if (outputs.length === 0)
+                continue;
+            let changed = false;
+            const nextOutputs = outputs.map((outputPath) => {
+                const replacement = pathMap[outputPath];
+                if (!replacement || replacement === outputPath) {
+                    return outputPath;
+                }
+                changed = true;
+                return replacement;
+            });
+            if (!changed)
+                continue;
+            artifact.derived_outputs = Array.from(new Set(nextOutputs));
+            artifact.updated_at = utcNow();
+            updated += 1;
+        }
+        if (updated > 0) {
+            manifest.updated_at = utcNow();
+            await this.writeManifest(manifest);
+        }
+        return { updated };
+    }
     async updateArtifact(artifactId, input) {
         const manifest = await this.readManifest();
         const index = manifest.artifacts.findIndex((item) => item.id === artifactId);

package/dist/types.d.ts

@@ -6,6 +6,9 @@ export interface Artifact {
     mime_type: string;
     size_bytes: number;
     tags: string[];
+    status?: string;
+    related_changes?: string[];
+    derived_outputs?: string[];
     created_at: string;
     updated_at: string;
 }