dorfl 0.0.0 → 0.1.0

package/dist/arbiter.js

@@ -0,0 +1,255 @@
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { git, run } from './git.js';
+import { encodeRepoKey } from './repo-mirror.js';
+/**
+ * The **arbiter management** primitive (ADR §7 in
+ * `docs/adr/execution-substrate-decisions.md`): provision and inspect a local
+ * `--bare` arbiter — the offline source of truth the claim/integration
+ * protocols serialize on (`scripts/CLAIM-PROTOCOL.md`).
+ *
+ * An arbiter is **precious DATA**, not state or cache: it is the very thing the
+ * deletion-safety predicate (ADR §4) proves everything else safe *against*. So:
+ *
+ *   - It is provisioned under a visible `~/git/` (config `arbitersDir`),
+ *     hierarchical (`<host>/<org>/<name>.git`), reusing the workspace repo→key
+ *     encoding (`.`→`-` per segment) — NEVER under `~/.dorfl/`, whose
+ *     `gc`/cleanup could nuke the only copy.
+ *   - It is created `git clone --bare`. A non-bare repo with `main` checked out
+ *     CANNOT be an arbiter: it rejects pushes to `main` (CLAIM-PROTOCOL), which
+ *     would silently break every claim. `init` refuses that unsafe case; `status`
+ *     flags it.
+ *
+ * This module only **provisions/locates** the arbiter (`arbiterInit` from an
+ * existing working repo, `arbiterStatus`). It does NOT claim, run, or fetch —
+ * those consume what this provides. It reuses the `repo-mirror` repo→key
+ * encoding (it does NOT duplicate it).
+ */
+/** The conventional default name for the arbiter remote in a working repo. */
+export const DEFAULT_ARBITER_REMOTE = 'arbiter';
+/**
+ * The on-disk location of the local bare arbiter for `url`:
+ * `<arbitersDir>/<host>/<org>/<name>.git` (hierarchical, reusing the
+ * `repo-mirror` repo→key encoding, with a `.git` suffix). Lives under
+ * `arbitersDir` (default `~/git`), NEVER `~/.dorfl` (ADR §7).
+ */
+export function arbiterPath(arbitersDir, url) {
+    return join(arbitersDir, `${encodeRepoKey(url)}.git`);
+}
+/** Raised when `init` cannot safely provision/locate an arbiter. */
+export class ArbiterError extends Error {
+}
+/**
+ * Provision (or locate) a local bare arbiter from a working repo and wire the
+ * repo's `<remote>` to it. Idempotent: an existing arbiter is detected and NOT
+ * clobbered (it is only re-pointed by the remote, never re-cloned). Refuses the
+ * unsafe case where the target is a non-bare repo with `main` checked out (which
+ * would reject claim pushes — CLAIM-PROTOCOL).
+ *
+ * The default path is hierarchical under `arbitersDir` (`~/git`), NEVER under
+ * `~/.dorfl` (ADR §7) — overridable via `at`.
+ */
+export function arbiterInit(options) {
+    const env = options.env;
+    const note = options.note ?? (() => { });
+    const repo = options.repo ?? options.cwd ?? process.cwd();
+    const remote = options.remote ?? DEFAULT_ARBITER_REMOTE;
+    if (run('git', ['rev-parse', '--git-dir'], repo, { env }).status !== 0) {
+        throw new ArbiterError(`not inside a git repository: ${repo}`);
+    }
+    // Resolve the destination path: explicit --at, else the hierarchical default
+    // under arbitersDir keyed off the repo's canonical file:// URL.
+    const repoUrl = `file://${repo}`;
+    const path = options.at ?? arbiterPath(arbitersDir(options), repoUrl);
+    const url = `file://${path}`;
+    // Idempotent: an existing git repo at the path is detected, validated as bare,
+    // and NEVER clobbered (no re-clone). We only ensure the remote is wired.
+    if (pathHoldsGitRepo(path)) {
+        assertBare(path, env);
+        note(`arbiter already exists at ${path} (not re-cloning) — ensuring remote.`);
+        wireRemote(repo, remote, url, env);
+        return {
+            path,
+            url,
+            remote,
+            created: false,
+            alreadyExisted: true,
+            bare: true,
+        };
+    }
+    // Refuse the unsafe case: --at points at an EXISTING non-bare repo (e.g. one
+    // with main checked out). Using it as the arbiter rejects claim pushes to
+    // main (CLAIM-PROTOCOL) — a silent, claim-breaking footgun.
+    if (existsSync(path) && pathLooksLikeWorkingTree(path)) {
+        assertBare(path, env); // throws with the clear non-bare message
+    }
+    // Provision: a bare clone of the working repo (its objects + main seed it).
+    mkdirSync(dirname(path), { recursive: true });
+    git(['clone', '--quiet', '--bare', repo, path], dirname(path), { env });
+    note(`provisioned bare arbiter at ${path}`);
+    // Wire the repo's <remote> to the new arbiter.
+    wireRemote(repo, remote, url, env);
+    return { path, url, remote, created: true, alreadyExisted: false, bare: true };
+}
+/**
+ * Read-only report of the current repo's arbiter: which remote it is, its
+ * URL/path, whether it exists and is bare, and whether `main` is reachable. It
+ * MUTATES NOTHING (no fetch, no checkout) — it reads the local remote config and
+ * inspects the arbiter repo in place. Flags the unsafe non-bare-with-main case
+ * (ADR §7 / CLAIM-PROTOCOL).
+ */
+export function arbiterStatus(options) {
+    const env = options.env;
+    const cwd = options.cwd ?? process.cwd();
+    const remote = options.remote ?? DEFAULT_ARBITER_REMOTE;
+    const urlResult = run('git', ['remote', 'get-url', remote], cwd, { env });
+    if (urlResult.status !== 0) {
+        return {
+            remote,
+            configured: false,
+            exists: false,
+            bare: false,
+            mainReachable: false,
+            unsafe: false,
+        };
+    }
+    const url = urlResult.stdout.trim();
+    const path = localPathFromUrl(url);
+    // Only a local path can be inspected in place; a remote URL (github, ssh) is
+    // reported as configured but its bare-ness/reachability is not probed here.
+    if (path === undefined) {
+        return {
+            remote,
+            configured: true,
+            url,
+            exists: false,
+            bare: false,
+            mainReachable: false,
+            unsafe: false,
+        };
+    }
+    const exists = pathHoldsGitRepo(path);
+    if (!exists) {
+        return {
+            remote,
+            configured: true,
+            url,
+            path,
+            exists: false,
+            bare: false,
+            mainReachable: false,
+            unsafe: false,
+        };
+    }
+    const bare = isBareRepo(path, env);
+    const mainReachable = run('git', ['rev-parse', '--verify', 'main'], path, {
+        env,
+    }).status === 0;
+    return {
+        remote,
+        configured: true,
+        url,
+        path,
+        exists: true,
+        bare,
+        mainReachable,
+        // Unsafe = it exists but is NOT bare (a working tree with main checked out
+        // rejects claim pushes to main — CLAIM-PROTOCOL).
+        unsafe: !bare,
+    };
+}
+/** Render an `arbiter status` report for the terminal. */
+export function formatArbiterStatus(report) {
+    const lines = [];
+    if (!report.configured) {
+        lines.push(`Arbiter: no '${report.remote}' remote configured in this repo.`);
+        lines.push(`  Run \`dorfl arbiter init --remote ${report.remote}\` to provision one,`);
+        lines.push('  or set it manually with `git remote add`.');
+        return lines.join('\n');
+    }
+    lines.push(`Arbiter remote: ${report.remote}`);
+    lines.push(`  URL:    ${report.url ?? '(unknown)'}`);
+    if (report.path !== undefined) {
+        lines.push(`  path:   ${report.path}`);
+    }
+    lines.push(`  exists: ${report.exists ? 'yes' : 'no'}`);
+    if (report.exists) {
+        lines.push(`  bare:   ${report.bare ? 'yes' : 'no'}`);
+        lines.push(`  main:   ${report.mainReachable ? 'reachable' : 'NOT reachable'}`);
+    }
+    if (report.unsafe) {
+        lines.push('');
+        lines.push('  !! UNSAFE: the arbiter is a non-bare repo (a working tree). A non-bare');
+        lines.push('     repo with `main` checked out REJECTS claim pushes to main');
+        lines.push('     (CLAIM-PROTOCOL). Re-provision a bare arbiter with `arbiter init`.');
+    }
+    else if (report.exists && !report.mainReachable) {
+        lines.push('');
+        lines.push('  !! main is not reachable on the arbiter (empty or wrong repo?).');
+    }
+    return lines.join('\n');
+}
+/** Resolve the arbiters dir from options, defaulting to `~/git`. */
+function arbitersDir(options) {
+    if (options.arbitersDir && options.arbitersDir.trim() !== '') {
+        return options.arbitersDir;
+    }
+    throw new ArbiterError('arbiterInit requires `at` or `arbitersDir` (the CLI passes the resolved config).');
+}
+/** Add the remote if absent, else set its URL (idempotent wiring). */
+function wireRemote(repo, remote, url, env) {
+    const existing = run('git', ['remote', 'get-url', remote], repo, { env });
+    if (existing.status === 0) {
+        git(['remote', 'set-url', remote, url], repo, { env });
+    }
+    else {
+        git(['remote', 'add', remote, url], repo, { env });
+    }
+}
+/** Throw a clear error if the repo at `path` is not bare (the unsafe case). */
+function assertBare(path, env) {
+    if (!isBareRepo(path, env)) {
+        throw new ArbiterError(`refusing: the arbiter at ${path} is a NON-BARE repo (a working tree). ` +
+            'A non-bare repo with `main` checked out rejects claim pushes to main ' +
+            '(CLAIM-PROTOCOL) — it cannot serve as an arbiter. Provision a bare ' +
+            'arbiter (git clone --bare) at a clean location instead.');
+    }
+}
+/** True iff `path` is (or contains) an initialised git repository. */
+function pathHoldsGitRepo(path) {
+    if (!existsSync(path)) {
+        return false;
+    }
+    // A bare repo IS a git dir; a non-bare repo has a `.git` entry. Either way,
+    // `git rev-parse --git-dir` succeeds when run inside it.
+    return run('git', ['rev-parse', '--git-dir'], path).status === 0;
+}
+/** True iff `path` exists and looks like a non-empty directory (a candidate repo). */
+function pathLooksLikeWorkingTree(path) {
+    try {
+        return readdirSync(path).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True iff the git repo at `path` is bare. */
+function isBareRepo(path, env) {
+    const result = run('git', ['rev-parse', '--is-bare-repository'], path, { env });
+    return result.status === 0 && result.stdout.trim() === 'true';
+}
+/**
+ * The local filesystem path a remote URL refers to, or `undefined` for a true
+ * remote (github/ssh/https). Handles `file://...` and a plain absolute path.
+ */
+function localPathFromUrl(url) {
+    const trimmed = url.trim();
+    if (trimmed.startsWith('file://')) {
+        return trimmed.slice('file://'.length);
+    }
+    if (trimmed.startsWith('/')) {
+        return trimmed;
+    }
+    return undefined;
+}
+//# sourceMappingURL=arbiter.js.map

package/dist/arbiter.js.map

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

package/dist/brand.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The **brand / protocol identity** single source of truth (ADR-class load-
+ * bearing strings).
+ *
+ * dorfl's name leaks into a handful of strings that are a CONTRACT with
+ * the user, the filesystem, and CI — and that BREAK SILENTLY if they drift out
+ * of sync on a rename:
+ *
+ *   - the `DORFL_` env-var prefix (a missed one is read as "unset" — the
+ *     worst kind of failure: silent);
+ *   - the `.dorfl.json` per-repo config filename;
+ *   - the `~/.dorfl/` workspaces-dir default + the `dorfl` config
+ *     dir name;
+ *   - the `.dorfl-job.json` per-job record filename;
+ *   - the `dorfl` binary / package name where referenced FROM CODE.
+ *
+ * This module derives EVERY one of those from a SINGLE base string ({@link BASE})
+ * using the same case transforms the `change-name` tool understands
+ * (https://github.com/wighawag/change-name — camelCase/constantCase/paramCase/…).
+ * Renaming the project later is then ONE edit here, not a scattered (and
+ * silently-breakable) find/replace across the codebase.
+ *
+ * SCOPE: only the PROTOCOL surface (where a miss BREAKS things). The ~600
+ * cosmetic doc/prose mentions of "dorfl" (ADRs, prds, CONTEXT.md, tasks,
+ * comments) are NOT indirected through this module — they should read as the real
+ * name and are handled at actual rebrand time by `change-name` (multi-case-aware
+ * recursive rename of file names + contents). The two are complementary: this
+ * centralizes the breakable protocol surface; `change-name` covers the cosmetic
+ * bulk. Likewise `package.json`'s `name`/`bin` are NOT indirected through a
+ * runtime constant (that is also `change-name`'s job) — {@link Brand.bin} merely
+ * exposes the SAME derived value for the code sites that reference the binary.
+ */
+/**
+ * The ONE base identity string, in `paramCase` (the natural form of the binary
+ * name). Change THIS and every derived protocol form below flips in lockstep.
+ */
+export declare const BASE = "dorfl";
+/** `dorfl` (lowercase words joined by `-`). */
+export declare function paramCase(input: string): string;
+/** `DORFL` (uppercase words joined by `_`). */
+export declare function constantCase(input: string): string;
+/**
+ * The derived brand surface. Every field is computed from {@link BASE}; none is
+ * an independent literal, so they can never drift apart.
+ */
+export interface Brand {
+    /** The base identity string (paramCase): `dorfl`. */
+    readonly base: string;
+    /** The shared env-var prefix: `constantCase(base) + '_'` ⇒ `DORFL_`. */
+    readonly envPrefix: string;
+    /** The per-repo config filename: `.{paramCase(base)}.json` ⇒ `.dorfl.json`. */
+    readonly repoConfigFilename: string;
+    /** The workspaces-dir name (a dotfile dir): `.{paramCase(base)}` ⇒ `.dorfl`. */
+    readonly workdirName: string;
+    /** The per-job record filename: `.{paramCase(base)}-job.json` ⇒ `.dorfl-job.json`. */
+    readonly jobRecordFilename: string;
+    /** The config-dir name (under `~/.config/`): `paramCase(base)` ⇒ `dorfl`. */
+    readonly configDirName: string;
+    /** The binary / package name (paramCase): `dorfl`. */
+    readonly bin: string;
+}
+/** Derive the full {@link Brand} surface from one base string. */
+export declare function deriveBrand(base: string): Brand;
+/**
+ * The live brand surface for THIS project, derived from {@link BASE}. Import the
+ * fields you need (e.g. `brand.envPrefix`, `brand.workdirName`) instead of
+ * hardcoding the literal — that is the whole point of this module.
+ */
+export declare const brand: Brand;
+//# sourceMappingURL=brand.d.ts.map

package/dist/brand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../src/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;GAGG;AACH,eAAO,MAAM,IAAI,UAAU,CAAC;AAqB5B,+CAA+C;AAC/C,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IACrB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACrB;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAW/C;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAyB,CAAC"}

package/dist/brand.js

@@ -0,0 +1,84 @@
+/**
+ * The **brand / protocol identity** single source of truth (ADR-class load-
+ * bearing strings).
+ *
+ * dorfl's name leaks into a handful of strings that are a CONTRACT with
+ * the user, the filesystem, and CI — and that BREAK SILENTLY if they drift out
+ * of sync on a rename:
+ *
+ *   - the `DORFL_` env-var prefix (a missed one is read as "unset" — the
+ *     worst kind of failure: silent);
+ *   - the `.dorfl.json` per-repo config filename;
+ *   - the `~/.dorfl/` workspaces-dir default + the `dorfl` config
+ *     dir name;
+ *   - the `.dorfl-job.json` per-job record filename;
+ *   - the `dorfl` binary / package name where referenced FROM CODE.
+ *
+ * This module derives EVERY one of those from a SINGLE base string ({@link BASE})
+ * using the same case transforms the `change-name` tool understands
+ * (https://github.com/wighawag/change-name — camelCase/constantCase/paramCase/…).
+ * Renaming the project later is then ONE edit here, not a scattered (and
+ * silently-breakable) find/replace across the codebase.
+ *
+ * SCOPE: only the PROTOCOL surface (where a miss BREAKS things). The ~600
+ * cosmetic doc/prose mentions of "dorfl" (ADRs, prds, CONTEXT.md, tasks,
+ * comments) are NOT indirected through this module — they should read as the real
+ * name and are handled at actual rebrand time by `change-name` (multi-case-aware
+ * recursive rename of file names + contents). The two are complementary: this
+ * centralizes the breakable protocol surface; `change-name` covers the cosmetic
+ * bulk. Likewise `package.json`'s `name`/`bin` are NOT indirected through a
+ * runtime constant (that is also `change-name`'s job) — {@link Brand.bin} merely
+ * exposes the SAME derived value for the code sites that reference the binary.
+ */
+/**
+ * The ONE base identity string, in `paramCase` (the natural form of the binary
+ * name). Change THIS and every derived protocol form below flips in lockstep.
+ */
+export const BASE = 'dorfl';
+// --- Case transforms (the subset of `change-name`'s vocabulary we derive from).
+//
+// Implemented locally (no runtime dependency) but NAMED for the `change-name`
+// conventions so the mapping is obvious at rebrand time. Each splits the input
+// into lowercase words, then re-joins per the target case. The base is already
+// `paramCase`, but we go through `words()` so a future base in any case still
+// derives correctly.
+/** Split an identifier (any case) into its lowercase words. */
+function words(input) {
+    return input
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase / PascalCase boundary
+        .replace(/[-_\s.]+/g, ' ') // param/snake/dot/space separators
+        .trim()
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w !== '');
+}
+/** `dorfl` (lowercase words joined by `-`). */
+export function paramCase(input) {
+    return words(input).join('-');
+}
+/** `DORFL` (uppercase words joined by `_`). */
+export function constantCase(input) {
+    return words(input)
+        .map((w) => w.toUpperCase())
+        .join('_');
+}
+/** Derive the full {@link Brand} surface from one base string. */
+export function deriveBrand(base) {
+    const param = paramCase(base);
+    return {
+        base,
+        envPrefix: constantCase(base) + '_',
+        repoConfigFilename: `.${param}.json`,
+        workdirName: `.${param}`,
+        jobRecordFilename: `.${param}-job.json`,
+        configDirName: param,
+        bin: param,
+    };
+}
+/**
+ * The live brand surface for THIS project, derived from {@link BASE}. Import the
+ * fields you need (e.g. `brand.envPrefix`, `brand.workdirName`) instead of
+ * hardcoding the literal — that is the whole point of this module.
+ */
+export const brand = deriveBrand(BASE);
+//# sourceMappingURL=brand.js.map

package/dist/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../src/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC;AAE5B,iFAAiF;AACjF,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,qBAAqB;AAErB,+DAA+D;AAC/D,SAAS,KAAK,CAAC,KAAa;IAC3B,OAAO,KAAK;SACV,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,kCAAkC;SACzE,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,mCAAmC;SAC7D,IAAI,EAAE;SACN,WAAW,EAAE;SACb,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,SAAS,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,YAAY,CAAC,KAAa;IACzC,OAAO,KAAK,CAAC,KAAK,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;AACb,CAAC;AAuBD,kEAAkE;AAClE,MAAM,UAAU,WAAW,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO;QACN,IAAI;QACJ,SAAS,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,GAAG;QACnC,kBAAkB,EAAE,IAAI,KAAK,OAAO;QACpC,WAAW,EAAE,IAAI,KAAK,EAAE;QACxB,iBAAiB,EAAE,IAAI,KAAK,WAAW;QACvC,aAAa,EAAE,KAAK;QACpB,GAAG,EAAE,KAAK;KACV,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAU,WAAW,CAAC,IAAI,CAAC,CAAC"}

package/dist/buildable-body.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The SINGLE owner of the buildable-task (and PRD-body) markdown SECTION SCHEMA
+ * (prd `centralize-buildable-task-renderer-shared-by-intake-and-promotion`, US
+ * #1/#4/#7). dorfl has TWO independent producers of a buildable task/PRD body —
+ * `intake.ts` (`renderBacklogTask`/`renderSpec`, a wrapper+fallback) and
+ * `triage-persist.ts` (`buildPromotedBody`, a structured renderer) — and until
+ * this module they each HAND-ROLLED the `## What to build` / `## Acceptance
+ * criteria` / `## Open questions` / `## Prompt` skeleton, so the schema could (and
+ * did) DRIFT apart silently (the promptless-promotion stuck-lock bug, see the
+ * origin observation
+ * `advance-promotion-builds-promptless-task-that-self-claims-stuck-2026-06-25`).
+ *
+ * This module renders only the BODY (the markdown AFTER the frontmatter fence) —
+ * the part both producers actually share. Each producer keeps its OWN frontmatter
+ * writer (intake stamps `issue:`/`originTrust:`; promotion stamps `needsAnswers:`/
+ * `blockedBy:`) and its OWN writer/integration mode (intake's branch+PR front
+ * door; promotion's triage-local CAS create) — only the section skeleton is
+ * centralized here.
+ *
+ * The two producers are ASYMMETRIC, and that asymmetry is expressed by the
+ * renderer's inputs rather than by two divergent bodies:
+ *
+ *   - intake's DEFAULT-SCAFFOLD skeleton (used ONLY when the intake agent drafted
+ *     no body) is `## What to build` + `## Acceptance criteria` + a thin default
+ *     `## Prompt`. Reproduced by passing all three.
+ *   - promotion's structured body is `## What to build` (the mechanism prose) +
+ *     optional `## Open questions` + a `## Prompt` seeded (blockquoted) from the
+ *     mechanism prose, and NO `## Acceptance criteria`. Reproduced by omitting
+ *     `acceptanceCriteria` and passing the open-questions block + the seed prose.
+ *
+ * Symmetrically, {@link renderSpecBody} owns the FULL PRD section schema both PRD
+ * producers need: intake's default PRD scaffold is `## Problem Statement` +
+ * `## Solution` + `## User Stories` (reproduced by passing all three), while
+ * promotion's structured PRD body is `## Problem Statement` + optional
+ * `## Open questions` (reproduced by omitting `solution`/`userStories`). Each
+ * optional section is emitted only when its input is non-empty.
+ *
+ * `## Prompt` is TASK-ONLY: a PRD is not dispatched by `do`/`run`, so a PRD body
+ * carries none (the symmetric reason the task body MUST carry one — the consumer
+ * `extractPromptSection`/`resolveTask` in `prompt.ts` throws "has no '## Prompt'
+ * section" at dispatch time without it). {@link renderTaskBody} always emits a
+ * `## Prompt`; {@link renderSpecBody} never does.
+ *
+ * NOTE (extract-only): this module is a PURE ADDITION. Neither producer is rewired
+ * here — that is the two follow-on tasks (kept file-orthogonal so each proves its
+ * own output is byte-for-byte preserved). This task lands the renderer + its
+ * golden-shape test ONLY.
+ */
+export interface RenderTaskBodyInput {
+    /**
+     * The `## What to build` prose. For intake's default scaffold this is the task
+     * title; for promotion it is the observation's mechanism/fix prose. When empty,
+     * a placeholder keeps the section non-empty.
+     */
+    whatToBuild: string;
+    /**
+     * The `## Acceptance criteria` block (markdown, e.g. a `- [ ]` checklist).
+     * OMIT it (or pass empty) to drop the section entirely — promotion's structured
+     * body carries no acceptance section, intake's default scaffold does.
+     */
+    acceptanceCriteria?: string;
+    /**
+     * The `## Open questions` block (markdown). OMIT it (or pass empty) to drop the
+     * section — intake's default scaffold has none, a promoted observation carries
+     * its transcribed open questions here.
+     */
+    openQuestions?: string;
+    /**
+     * The `## Prompt` body, supplied UNQUOTED — the renderer blockquotes it (the
+     * `> `-prefixed shape `extractPromptSection` strips back off). This is the
+     * task-only dispatchability section; it is ALWAYS emitted (a placeholder seeds
+     * it when empty) so a rendered task never fails the missing-`## Prompt` guard.
+     */
+    prompt: string;
+}
+/**
+ * Render a buildable TASK body (the markdown AFTER the frontmatter fence). Emits,
+ * in order: `## What to build`, `## Acceptance criteria` (only when given),
+ * `## Open questions` (only when given), and ALWAYS `## Prompt` (blockquoted).
+ *
+ * The output passes `extractPromptSection`/`resolveTask` without the
+ * "has no '## Prompt' section" throw, because `## Prompt` is unconditional and
+ * never empty. The caller wraps this body with its own frontmatter.
+ *
+ * FENCE↔HEADING BOUNDARY: this renderer starts at its first heading with NO
+ * leading blank line — the caller's frontmatter serializer owns the single blank
+ * line between the closing `---` fence and this first heading (ratified in
+ * `docs/adr/frontmatter-owns-fence-to-heading-blank-line.md`). Do NOT add a
+ * leading blank here; that would reintroduce the fence-spacing drift class.
+ */
+export declare function renderTaskBody(input: RenderTaskBodyInput): string;
+export interface RenderSpecBodyInput {
+    /**
+     * The `## Problem Statement` prose. For intake's default scaffold this is the
+     * issue-transform line; for promotion it is the observation's mechanism prose.
+     * When empty, a placeholder keeps the section non-empty.
+     */
+    problemStatement: string;
+    /**
+     * The `## Solution` prose (markdown). OMIT it (or pass empty) to drop the
+     * section — promotion's structured PRD body carries no Solution section, intake's
+     * default PRD scaffold does.
+     */
+    solution?: string;
+    /**
+     * The `## User Stories` block (markdown, e.g. a numbered list). OMIT it (or pass
+     * empty) to drop the section — promotion's structured PRD body carries no User
+     * Stories section, intake's default PRD scaffold does.
+     */
+    userStories?: string;
+    /**
+     * The `## Open questions` block (markdown). OMIT it (or pass empty) to drop the
+     * section. A PRD carries NO `## Prompt` (it is not dispatched).
+     */
+    openQuestions?: string;
+}
+/**
+ * Render a PRD body (the markdown AFTER the frontmatter fence). Emits, in the
+ * canonical order, `## Problem Statement`, then `## Solution`, `## User Stories`,
+ * and `## Open questions` (each only when its input is given), and NEVER a
+ * `## Prompt` — a PRD is a north-star doc, not a dispatchable task. The symmetric twin of
+ * {@link renderTaskBody}, owning the FULL SPEC section schema both producers need
+ * (intake's default scaffold supplies Problem Statement + Solution + User Stories;
+ * promotion's structured body supplies Problem Statement + optional Open
+ * questions) so the two artifact shapes cannot drift apart.
+ *
+ * FENCE↔HEADING BOUNDARY: same convention as {@link renderTaskBody} — no leading
+ * blank; the frontmatter serializer owns the `\n\n` after the closing `---` fence
+ * (see `docs/adr/frontmatter-owns-fence-to-heading-blank-line.md`).
+ */
+export declare function renderSpecBody(input: RenderSpecBodyInput): string;
+//# sourceMappingURL=buildable-body.d.ts.map

package/dist/buildable-body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildable-body.d.ts","sourceRoot":"","sources":["../src/buildable-body.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAUH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CA2BjE;AAED,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CA0BjE"}