@shrkcrft/generator 0.1.0-alpha.1

package/dist/spec/spec-io.js

@@ -0,0 +1,176 @@
+/**
+ * Read/write helpers for spec.md / spec.json / events.jsonl.
+ *
+ * Pure filesystem layer. Validation lives elsewhere; this module only
+ * reads/writes the on-disk artifacts. The directory layout is
+ * `.sharkcraft/specs/<id>/`:
+ *
+ *   spec.md           — frontmatter + body, authoritative
+ *   spec.json         — derived canonical view
+ *   plan.json         — signed combined plan (after `implement --write-plan`)
+ *   verification.json — most recent verify report (after `verify`)
+ *   events.jsonl      — append-only log of `spec` operations
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { deriveSpecJson } from "./spec-derive.js";
+import { splitSpecMd } from "./spec-frontmatter.js";
+import { SPEC_EVENTS_SCHEMA_V1 } from "./spec-model.js";
+export const SPECS_DIR_RELATIVE = '.sharkcraft/specs';
+export function specsRoot(projectRoot) {
+    return nodePath.join(projectRoot, SPECS_DIR_RELATIVE);
+}
+export function specDir(projectRoot, id) {
+    return nodePath.join(specsRoot(projectRoot), id);
+}
+export function specMdPath(projectRoot, id) {
+    return nodePath.join(specDir(projectRoot, id), 'spec.md');
+}
+export function specJsonPath(projectRoot, id) {
+    return nodePath.join(specDir(projectRoot, id), 'spec.json');
+}
+export function specPlanPath(projectRoot, id) {
+    return nodePath.join(specDir(projectRoot, id), 'plan.json');
+}
+export function specVerificationPath(projectRoot, id) {
+    return nodePath.join(specDir(projectRoot, id), 'verification.json');
+}
+export function specEventsPath(projectRoot, id) {
+    return nodePath.join(specDir(projectRoot, id), 'events.jsonl');
+}
+export function listSpecIds(projectRoot) {
+    const root = specsRoot(projectRoot);
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(root)) {
+        const full = nodePath.join(root, entry);
+        let s = null;
+        try {
+            s = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (s?.isDirectory()) {
+            const md = nodePath.join(full, 'spec.md');
+            if (existsSync(md))
+                out.push(entry);
+        }
+    }
+    out.sort().reverse();
+    return out;
+}
+export function writeSpecMd(projectRoot, id, body) {
+    try {
+        mkdirSync(specDir(projectRoot, id), { recursive: true });
+        writeFileSync(specMdPath(projectRoot, id), body.endsWith('\n') ? body : body + '\n', 'utf8');
+        return ok(undefined);
+    }
+    catch (e) {
+        return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, 'Failed to write spec.md', { cause: e }));
+    }
+}
+export function readSpecMd(projectRoot, id) {
+    const p = specMdPath(projectRoot, id);
+    if (!existsSync(p)) {
+        return err(new AppErrorImpl(ERROR_CODES.NOT_FOUND, `Spec not found: ${id} (expected ${p})`));
+    }
+    try {
+        return ok(readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        return err(new AppErrorImpl(ERROR_CODES.FILE_READ_ERROR, `Failed to read spec.md for ${id}`, { cause: e }));
+    }
+}
+export function writeSpecJson(projectRoot, id, json) {
+    try {
+        mkdirSync(specDir(projectRoot, id), { recursive: true });
+        writeFileSync(specJsonPath(projectRoot, id), JSON.stringify(json, null, 2) + '\n', 'utf8');
+        return ok(undefined);
+    }
+    catch (e) {
+        return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, 'Failed to write spec.json', { cause: e }));
+    }
+}
+export function readSpecJson(projectRoot, id) {
+    const p = specJsonPath(projectRoot, id);
+    if (!existsSync(p)) {
+        return err(new AppErrorImpl(ERROR_CODES.NOT_FOUND, `spec.json not found for ${id}`));
+    }
+    try {
+        const raw = readFileSync(p, 'utf8');
+        return ok(JSON.parse(raw));
+    }
+    catch (e) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Invalid spec.json for ${id}`, { cause: e }));
+    }
+}
+/**
+ * Convenience: parse spec.md, derive spec.json, return both. Does NOT
+ * read or write the cached spec.json on disk — caller decides.
+ */
+export function loadSpec(projectRoot, id) {
+    const raw = readSpecMd(projectRoot, id);
+    if (!raw.ok)
+        return err(raw.error);
+    const parsed = splitSpecMd(raw.value);
+    if (!parsed.ok)
+        return err(parsed.error);
+    const derived = deriveSpecJson(parsed.value);
+    if (!derived.ok)
+        return err(derived.error);
+    return ok({ spec: derived.value, body: parsed.value.body });
+}
+export function appendSpecEvent(projectRoot, id, event) {
+    try {
+        mkdirSync(specDir(projectRoot, id), { recursive: true });
+        const entry = {
+            schema: SPEC_EVENTS_SCHEMA_V1,
+            ts: event.ts ?? new Date().toISOString(),
+            specId: id,
+            operation: event.operation,
+            ...(event.verdict !== undefined ? { verdict: event.verdict } : {}),
+            ...(event.details !== undefined ? { details: event.details } : {}),
+        };
+        appendFileSync(specEventsPath(projectRoot, id), JSON.stringify(entry) + '\n', 'utf8');
+        return ok(undefined);
+    }
+    catch (e) {
+        return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, 'Failed to append spec event', { cause: e }));
+    }
+}
+export function readSpecEvents(projectRoot, id) {
+    const p = specEventsPath(projectRoot, id);
+    if (!existsSync(p))
+        return [];
+    try {
+        const raw = readFileSync(p, 'utf8');
+        const out = [];
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            try {
+                out.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Skip malformed lines.
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+export function persistSpecArtifacts(input) {
+    const mdRes = writeSpecMd(input.projectRoot, input.id, input.md);
+    if (!mdRes.ok)
+        return err(mdRes.error);
+    const jsonRes = writeSpecJson(input.projectRoot, input.id, input.json);
+    if (!jsonRes.ok)
+        return err(jsonRes.error);
+    return ok(undefined);
+}

package/dist/spec/spec-model.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `sharkcraft.spec/v1` model + structural validation.
+ *
+ * The spec frontmatter is the authoritative source of truth; the markdown
+ * body is inert documentation. `spec.json` is the canonical machine-
+ * readable view, derived deterministically (see `spec-derive.ts`).
+ *
+ * Structural validation lives here so the generator package can validate
+ * a spec without pulling in the inspector. Cross-registry validation
+ * (rule / knowledge / template / verification command resolution) lives
+ * in `@shrkcrft/inspector`.
+ */
+export declare const SPEC_SCHEMA_V1 = "sharkcraft.spec/v1";
+export declare const SPEC_EVENTS_SCHEMA_V1 = "sharkcraft.spec-events/v1";
+export declare enum SpecStatus {
+    Draft = "draft",
+    Review = "review",
+    Implementing = "implementing",
+    Implemented = "implemented",
+    Verified = "verified",
+    Abandoned = "abandoned"
+}
+export declare const SPEC_STATUS_VALUES: readonly SpecStatus[];
+export interface ISpecAcceptanceCriterion {
+    readonly id: string;
+    readonly text: string;
+    readonly verifiedBy: readonly string[];
+}
+export interface ISpecAffectedAreas {
+    readonly files: readonly string[];
+    readonly packages: readonly string[];
+    readonly layers: readonly string[];
+}
+export interface ISpecProposedTemplate {
+    readonly templateId: string;
+    readonly variables: Readonly<Record<string, string>>;
+    readonly note?: string;
+}
+export interface ISpecRisk {
+    readonly id: string;
+    readonly text: string;
+    readonly mitigation?: string;
+}
+export interface ISpecExternalLinks {
+    readonly issue?: string | null;
+    readonly pr?: string | null;
+}
+export interface ISpecBoundaryPrediction {
+    readonly from: string;
+    readonly to: string;
+    readonly reason: string;
+}
+export interface ISpecVerificationCommandRef {
+    readonly id: string;
+}
+export interface ISpecPlanRef {
+    readonly planPath: string;
+    readonly planHash: string;
+    readonly signedAt?: string;
+}
+/**
+ * The canonical machine-readable view of a spec. Derived from `spec.md`
+ * frontmatter. The `bodyHash` / `frontmatterHash` are sha256 hex digests.
+ */
+export interface ISpecJson {
+    readonly schema: typeof SPEC_SCHEMA_V1;
+    readonly id: string;
+    readonly slug: string;
+    readonly title: string;
+    readonly status: SpecStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly intent: string;
+    readonly motivation: string;
+    readonly acceptanceCriteria: readonly ISpecAcceptanceCriterion[];
+    readonly affectedAreas: ISpecAffectedAreas;
+    readonly relevantRules: readonly string[];
+    readonly relevantKnowledge: readonly string[];
+    readonly relevantPaths: readonly string[];
+    readonly proposedTemplates: readonly ISpecProposedTemplate[];
+    readonly risks: readonly ISpecRisk[];
+    readonly outOfScope: readonly string[];
+    readonly externalLinks: ISpecExternalLinks;
+    readonly boundariesCheck: {
+        readonly predicted: readonly ISpecBoundaryPrediction[];
+    };
+    readonly verificationCommands: readonly ISpecVerificationCommandRef[];
+    readonly plan?: ISpecPlanRef;
+    readonly frontmatterHash: string;
+    readonly bodyHash: string;
+    /** Unknown frontmatter keys preserved so review reports can flag them. */
+    readonly unknownKeys: readonly string[];
+}
+export interface ISpecValidationIssue {
+    readonly code: string;
+    readonly severity: 'error' | 'warning' | 'info';
+    readonly field: string;
+    readonly message: string;
+}
+/**
+ * The structural validation pass — does NOT touch external registries.
+ * Returns `errors` for blocking problems, `warnings` for advisory ones.
+ * Cross-registry checks (do the referenced rule/knowledge/template ids
+ * resolve?) live in `@shrkcrft/inspector`.
+ */
+export interface ISpecStructuralValidation {
+    readonly errors: readonly ISpecValidationIssue[];
+    readonly warnings: readonly ISpecValidationIssue[];
+}
+export declare function knownTopLevelKeys(): readonly string[];
+/** Default spec body length cap, in bytes. */
+export declare const DEFAULT_SPEC_BODY_MAX_BYTES = 16384;
+export declare function validateSpecStructural(spec: ISpecJson, body: string, options?: {
+    bodyMaxBytes?: number;
+}): ISpecStructuralValidation;
+export declare function isSpecIdShape(id: string): boolean;
+//# sourceMappingURL=spec-model.d.ts.map

package/dist/spec/spec-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-model.d.ts","sourceRoot":"","sources":["../../src/spec/spec-model.ts"],"names":[],"mappings":"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"}

package/dist/spec/spec-model.js

@@ -0,0 +1,225 @@
+/**
+ * `sharkcraft.spec/v1` model + structural validation.
+ *
+ * The spec frontmatter is the authoritative source of truth; the markdown
+ * body is inert documentation. `spec.json` is the canonical machine-
+ * readable view, derived deterministically (see `spec-derive.ts`).
+ *
+ * Structural validation lives here so the generator package can validate
+ * a spec without pulling in the inspector. Cross-registry validation
+ * (rule / knowledge / template / verification command resolution) lives
+ * in `@shrkcrft/inspector`.
+ */
+export const SPEC_SCHEMA_V1 = 'sharkcraft.spec/v1';
+export const SPEC_EVENTS_SCHEMA_V1 = 'sharkcraft.spec-events/v1';
+export var SpecStatus;
+(function (SpecStatus) {
+    SpecStatus["Draft"] = "draft";
+    SpecStatus["Review"] = "review";
+    SpecStatus["Implementing"] = "implementing";
+    SpecStatus["Implemented"] = "implemented";
+    SpecStatus["Verified"] = "verified";
+    SpecStatus["Abandoned"] = "abandoned";
+})(SpecStatus || (SpecStatus = {}));
+export const SPEC_STATUS_VALUES = Object.freeze([
+    SpecStatus.Draft,
+    SpecStatus.Review,
+    SpecStatus.Implementing,
+    SpecStatus.Implemented,
+    SpecStatus.Verified,
+    SpecStatus.Abandoned,
+]);
+const KNOWN_TOP_LEVEL_KEYS = Object.freeze([
+    'schema',
+    'id',
+    'slug',
+    'title',
+    'status',
+    'createdAt',
+    'updatedAt',
+    'intent',
+    'motivation',
+    'acceptanceCriteria',
+    'affectedAreas',
+    'relevantRules',
+    'relevantKnowledge',
+    'relevantPaths',
+    'proposedTemplates',
+    'risks',
+    'outOfScope',
+    'externalLinks',
+    'boundariesCheck',
+    'verificationCommands',
+    'plan',
+]);
+export function knownTopLevelKeys() {
+    return KNOWN_TOP_LEVEL_KEYS;
+}
+/** Default spec body length cap, in bytes. */
+export const DEFAULT_SPEC_BODY_MAX_BYTES = 16384;
+export function validateSpecStructural(spec, body, options = {}) {
+    const errors = [];
+    const warnings = [];
+    if (spec.schema !== SPEC_SCHEMA_V1) {
+        errors.push({
+            code: 'unsupported-schema',
+            severity: 'error',
+            field: 'schema',
+            message: `Spec schema must be ${SPEC_SCHEMA_V1} (got ${String(spec.schema)})`,
+        });
+    }
+    if (!isSpecIdShape(spec.id)) {
+        errors.push({
+            code: 'invalid-spec-id',
+            severity: 'error',
+            field: 'id',
+            message: `Spec id must match <YYYY-MM-DD>-<slug> (got "${spec.id}")`,
+        });
+    }
+    if (!spec.slug || !/^[a-z0-9][a-z0-9-]*$/.test(spec.slug)) {
+        errors.push({
+            code: 'invalid-slug',
+            severity: 'error',
+            field: 'slug',
+            message: `Slug must be kebab-case (got "${spec.slug}")`,
+        });
+    }
+    if (!spec.title || spec.title.trim().length === 0) {
+        errors.push({
+            code: 'missing-title',
+            severity: 'error',
+            field: 'title',
+            message: 'title must be a non-empty string',
+        });
+    }
+    if (!SPEC_STATUS_VALUES.includes(spec.status)) {
+        errors.push({
+            code: 'invalid-status',
+            severity: 'error',
+            field: 'status',
+            message: `status must be one of ${SPEC_STATUS_VALUES.join(', ')} (got "${String(spec.status)}")`,
+        });
+    }
+    if (!isIsoTimestamp(spec.createdAt)) {
+        errors.push({
+            code: 'invalid-created-at',
+            severity: 'error',
+            field: 'createdAt',
+            message: `createdAt must be an ISO-8601 timestamp (got "${spec.createdAt}")`,
+        });
+    }
+    if (!isIsoTimestamp(spec.updatedAt)) {
+        errors.push({
+            code: 'invalid-updated-at',
+            severity: 'error',
+            field: 'updatedAt',
+            message: `updatedAt must be an ISO-8601 timestamp (got "${spec.updatedAt}")`,
+        });
+    }
+    if (!spec.intent || spec.intent.trim().length === 0) {
+        errors.push({
+            code: 'missing-intent',
+            severity: 'error',
+            field: 'intent',
+            message: 'intent must be a non-empty string',
+        });
+    }
+    if (!spec.motivation || spec.motivation.trim().length === 0) {
+        errors.push({
+            code: 'missing-motivation',
+            severity: 'error',
+            field: 'motivation',
+            message: 'motivation must be a non-empty string',
+        });
+    }
+    if (!Array.isArray(spec.acceptanceCriteria) || spec.acceptanceCriteria.length === 0) {
+        errors.push({
+            code: 'missing-acceptance-criteria',
+            severity: 'error',
+            field: 'acceptanceCriteria',
+            message: 'acceptanceCriteria must contain at least one entry',
+        });
+    }
+    else {
+        const seen = new Set();
+        for (let i = 0; i < spec.acceptanceCriteria.length; i++) {
+            const ac = spec.acceptanceCriteria[i];
+            if (!ac.id) {
+                errors.push({
+                    code: 'acceptance-missing-id',
+                    severity: 'error',
+                    field: `acceptanceCriteria[${i}].id`,
+                    message: 'each acceptance criterion needs an id',
+                });
+                continue;
+            }
+            if (seen.has(ac.id)) {
+                errors.push({
+                    code: 'acceptance-duplicate-id',
+                    severity: 'error',
+                    field: `acceptanceCriteria[${i}].id`,
+                    message: `duplicate acceptance criterion id "${ac.id}"`,
+                });
+            }
+            seen.add(ac.id);
+            if (!ac.text || ac.text.trim().length === 0) {
+                errors.push({
+                    code: 'acceptance-missing-text',
+                    severity: 'error',
+                    field: `acceptanceCriteria[${i}].text`,
+                    message: `acceptance criterion "${ac.id}" needs text`,
+                });
+            }
+        }
+    }
+    for (let i = 0; i < spec.proposedTemplates.length; i++) {
+        const t = spec.proposedTemplates[i];
+        if (!t.templateId) {
+            errors.push({
+                code: 'template-missing-id',
+                severity: 'error',
+                field: `proposedTemplates[${i}].templateId`,
+                message: 'each proposed template needs a templateId',
+            });
+        }
+    }
+    for (let i = 0; i < spec.verificationCommands.length; i++) {
+        const v = spec.verificationCommands[i];
+        if (!v.id) {
+            errors.push({
+                code: 'verification-missing-id',
+                severity: 'error',
+                field: `verificationCommands[${i}].id`,
+                message: 'each verification command reference needs an id',
+            });
+        }
+    }
+    for (const k of spec.unknownKeys) {
+        warnings.push({
+            code: 'unknown-frontmatter-key',
+            severity: 'warning',
+            field: k,
+            message: `Unknown frontmatter key "${k}" — preserved but unrecognised`,
+        });
+    }
+    const maxBytes = options.bodyMaxBytes ?? DEFAULT_SPEC_BODY_MAX_BYTES;
+    const bodyBytes = Buffer.byteLength(body, 'utf8');
+    if (bodyBytes > maxBytes) {
+        warnings.push({
+            code: 'body-too-long',
+            severity: 'warning',
+            field: 'body',
+            message: `spec body is ${bodyBytes} bytes; recommended max is ${maxBytes}. Specs must stay short — force structure.`,
+        });
+    }
+    return { errors, warnings };
+}
+export function isSpecIdShape(id) {
+    return /^\d{4}-\d{2}-\d{2}-[a-z0-9][a-z0-9-]*$/.test(id);
+}
+function isIsoTimestamp(s) {
+    if (typeof s !== 'string' || s.length === 0)
+        return false;
+    const t = new Date(s).getTime();
+    return Number.isFinite(t);
+}

package/dist/spec/spec-scaffold.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Render a `spec.md` scaffold from grounded inputs.
+ *
+ * The engine does NOT write the prose. The scaffold leaves
+ * intent / motivation / acceptanceCriteria / risks deliberately
+ * empty (with placeholder text the human / agent fills in). The
+ * grounding fields (relevantRules / relevantKnowledge /
+ * relevantPaths / proposedTemplates / verificationCommands) are
+ * pre-populated from the recommender outputs the caller provides.
+ *
+ * Output is the markdown text of `spec.md`. Pure function; no IO.
+ */
+export interface IRenderSpecMdInput {
+    readonly id: string;
+    readonly slug: string;
+    readonly title: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly issue?: string | null;
+    readonly relevantRules: readonly string[];
+    readonly relevantKnowledge: readonly string[];
+    readonly relevantPaths: readonly string[];
+    readonly affectedPackages: readonly string[];
+    readonly proposedTemplates: ReadonlyArray<{
+        readonly templateId: string;
+        readonly variables: Readonly<Record<string, string>>;
+        readonly note?: string;
+    }>;
+    readonly verificationCommandIds: readonly string[];
+}
+export declare function renderSpecMd(input: IRenderSpecMdInput): string;
+//# sourceMappingURL=spec-scaffold.d.ts.map

package/dist/spec/spec-scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-scaffold.d.ts","sourceRoot":"","sources":["../../src/spec/spec-scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC;QACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;IACH,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAiF9D"}

package/dist/spec/spec-scaffold.js

@@ -0,0 +1,106 @@
+/**
+ * Render a `spec.md` scaffold from grounded inputs.
+ *
+ * The engine does NOT write the prose. The scaffold leaves
+ * intent / motivation / acceptanceCriteria / risks deliberately
+ * empty (with placeholder text the human / agent fills in). The
+ * grounding fields (relevantRules / relevantKnowledge /
+ * relevantPaths / proposedTemplates / verificationCommands) are
+ * pre-populated from the recommender outputs the caller provides.
+ *
+ * Output is the markdown text of `spec.md`. Pure function; no IO.
+ */
+import { SPEC_SCHEMA_V1, SpecStatus } from "./spec-model.js";
+export function renderSpecMd(input) {
+    const lines = [];
+    lines.push('---');
+    lines.push(`schema: ${SPEC_SCHEMA_V1}`);
+    lines.push(`id: ${input.id}`);
+    lines.push(`slug: ${input.slug}`);
+    lines.push(`title: ${quoteIfNeeded(input.title)}`);
+    lines.push(`status: ${SpecStatus.Draft}`);
+    lines.push(`createdAt: ${input.createdAt}`);
+    lines.push(`updatedAt: ${input.updatedAt}`);
+    lines.push('');
+    lines.push('intent: |');
+    lines.push('  TODO: one-paragraph statement of what is being built.');
+    lines.push('');
+    lines.push('motivation: |');
+    lines.push('  TODO: why now. The forcing function. Cross-link to issue if any.');
+    lines.push('');
+    lines.push('acceptanceCriteria:');
+    lines.push('  - id: ac-1');
+    lines.push('    text: TODO: replace with a concrete, testable acceptance criterion.');
+    lines.push('    verifiedBy:');
+    lines.push('      - tests');
+    lines.push('');
+    lines.push('affectedAreas:');
+    lines.push('  files:');
+    lines.push('  packages:');
+    for (const p of input.affectedPackages)
+        lines.push(`    - ${quoteIfNeeded(p)}`);
+    lines.push('  layers:');
+    lines.push('');
+    lines.push('relevantRules:');
+    for (const r of input.relevantRules)
+        lines.push(`  - ${quoteIfNeeded(r)}`);
+    lines.push('');
+    lines.push('relevantKnowledge:');
+    for (const k of input.relevantKnowledge)
+        lines.push(`  - ${quoteIfNeeded(k)}`);
+    lines.push('');
+    lines.push('relevantPaths:');
+    for (const p of input.relevantPaths)
+        lines.push(`  - ${quoteIfNeeded(p)}`);
+    lines.push('');
+    lines.push('proposedTemplates:');
+    for (const t of input.proposedTemplates) {
+        lines.push(`  - templateId: ${quoteIfNeeded(t.templateId)}`);
+        lines.push('    variables:');
+        for (const [k, v] of Object.entries(t.variables)) {
+            lines.push(`      ${k}: ${quoteIfNeeded(v)}`);
+        }
+        if (t.note !== undefined) {
+            lines.push(`    note: ${quoteIfNeeded(t.note)}`);
+        }
+    }
+    lines.push('');
+    lines.push('risks:');
+    lines.push('  - id: r-1');
+    lines.push('    text: TODO: identify a real risk this change introduces.');
+    lines.push('    mitigation: TODO: how the change mitigates it.');
+    lines.push('');
+    lines.push('outOfScope:');
+    lines.push('  - TODO: enumerate explicit non-goals.');
+    lines.push('');
+    lines.push('externalLinks:');
+    lines.push(`  issue: ${input.issue ? quoteIfNeeded(input.issue) : 'null'}`);
+    lines.push('  pr: null');
+    lines.push('');
+    lines.push('boundariesCheck:');
+    lines.push('  predicted:');
+    lines.push('');
+    lines.push('verificationCommands:');
+    for (const id of input.verificationCommandIds) {
+        lines.push(`  - id: ${quoteIfNeeded(id)}`);
+    }
+    lines.push('---');
+    lines.push('');
+    lines.push(`# ${input.title}`);
+    lines.push('');
+    lines.push('Body is free-form markdown. Architecture sketches, decision notes, design hazards.');
+    lines.push('Specs must stay short — force structure. Keep this section under the configured byte cap.');
+    lines.push('');
+    return lines.join('\n');
+}
+function quoteIfNeeded(s) {
+    // Bare strings are safe iff they contain no `:`, `#`, leading `-`,
+    // and only printable ASCII besides whitespace.
+    if (s.length === 0)
+        return '""';
+    if (/[:#\n\r\t]/.test(s))
+        return JSON.stringify(s);
+    if (s.startsWith('-') || s.startsWith('?') || s.startsWith('!'))
+        return JSON.stringify(s);
+    return s;
+}

package/dist/synthetic-plan.d.ts

@@ -0,0 +1,14 @@
+import { type IFileChange } from './file-change.js';
+import type { IGenerationPlan } from './generation-plan.js';
+import type { ISavedPlan } from './saved-plan.js';
+export declare const SYNTHETIC_TEMPLATE_PREFIX = "__";
+export declare function isSyntheticTemplateId(templateId: string): boolean;
+export declare function evaluateSavedPlanInPlace(plan: ISavedPlan, projectRoot: string): IGenerationPlan;
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { IGenerationSummary } from './generation-plan.js';
+export interface ISyntheticWriteResult {
+    summary: IGenerationSummary;
+    written: readonly IFileChange[];
+}
+export declare function writeSyntheticPlan(plan: IGenerationPlan): Result<ISyntheticWriteResult, AppError>;
+//# sourceMappingURL=synthetic-plan.d.ts.map

package/dist/synthetic-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthetic-plan.d.ts","sourceRoot":"","sources":["../src/synthetic-plan.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,MAAM,GAClB,eAAe,CAsCjB;AAuBD,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,GACpB,MAAM,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAsCzC"}