dorfl 0.0.0 → 0.1.0

package/dist/sidecar-apply.js

@@ -0,0 +1,111 @@
+import { mkdirSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { run } from './git.js';
+import { setNeedsAnswersMarker } from './frontmatter.js';
+import { allAnswered, serialiseSidecar, sidecarPathFor, } from './sidecar.js';
+/** Raised for usage errors (a torn mode, a missing repo). */
+export class ApplyAtomicError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApplyAtomicError';
+    }
+}
+function gitSoft(args, cwd, env) {
+    return run('git', args, cwd, { env });
+}
+function gitHard(args, cwd, env) {
+    const result = run('git', args, cwd, { env });
+    if (result.status !== 0) {
+        throw new ApplyAtomicError(`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result;
+}
+function resolveBy(cwd, env) {
+    const name = gitSoft(['config', 'user.name'], cwd, env);
+    if (name.status === 0 && name.stdout.trim() !== '') {
+        return name.stdout.trim();
+    }
+    const e = env ?? process.env;
+    return e.USER ?? e.USERNAME ?? '';
+}
+/**
+ * Apply an answer batch ATOMICALLY: rewrite the item body + the sidecar in ONE
+ * commit, and on full resolution clear `needsAnswers` AND delete the sidecar in
+ * that SAME commit. Returns the produced commit + the outcome.
+ *
+ * The resolution decision is DERIVED from the model (`allAnswered` ⇒ resolve) —
+ * the entries are the source of truth, never the frontmatter mirror. A supplied
+ * {@link ApplyAtomicOptions.mode} must AGREE with that derived state, else the
+ * apply throws (it refuses to publish a torn invariant: a `resolve` that leaves
+ * pending entries, or a `repause` that leaves none).
+ */
+export function applyAtomic(options) {
+    const { cwd, itemPath, itemBody, sidecar, env } = options;
+    const note = options.note ?? (() => { });
+    if (gitSoft(['rev-parse', '--git-dir'], cwd, env).status !== 0) {
+        throw new ApplyAtomicError('not inside a git repository');
+    }
+    const resolved = allAnswered(sidecar);
+    if (options.mode === 'resolve' && !resolved) {
+        throw new ApplyAtomicError('applyAtomic mode=resolve but the sidecar still has pending entries — ' +
+            'refusing to clear needsAnswers + delete the sidecar with open questions');
+    }
+    if (options.mode === 'repause' && resolved) {
+        throw new ApplyAtomicError('applyAtomic mode=repause but every sidecar entry is answered — ' +
+            'a fully-answered sidecar must resolve (clear needsAnswers + delete)');
+    }
+    const sidecarPath = sidecarPathFor(sidecar.item);
+    const itemAbs = join(cwd, itemPath);
+    const sidecarAbs = join(cwd, sidecarPath);
+    const by = options.by || resolveBy(cwd, env);
+    const touched = [itemPath];
+    if (resolved) {
+        // Full resolution: write the (optionally-updated) body with needsAnswers
+        // CLEARED, and DELETE the sidecar — one commit, the invariant holds after.
+        const baseBody = itemBody ?? readItem(itemAbs, cwd, itemPath, env);
+        const cleared = setNeedsAnswersMarker(baseBody, false);
+        writeFileSync(itemAbs, cleared);
+        // Remove the sidecar file from the tree (it may already be absent on a
+        // no-sidecar resolve, in which case rm is a no-op for the index).
+        rmSync(sidecarAbs, { force: true });
+        touched.push(sidecarPath);
+    }
+    else {
+        // Re-pause: write the updated body (if any) and the updated sidecar; leave
+        // needsAnswers: true. The sidecar stays present with its pending entries.
+        if (itemBody !== undefined) {
+            writeFileSync(itemAbs, setNeedsAnswersMarker(itemBody, true));
+        }
+        mkdirSync(dirname(sidecarAbs), { recursive: true });
+        writeFileSync(sidecarAbs, serialiseSidecar(sidecar));
+        touched.push(sidecarPath);
+    }
+    // Stage exactly the two paths and commit them TOGETHER (one atomic commit).
+    gitHard(['add', '--', ...touched], cwd, env);
+    const subject = resolved
+        ? `advance: resolve ${sidecar.item} (by ${by})`
+        : `advance: apply ${sidecar.item} (by ${by})`;
+    gitHard(['commit', '--quiet', '-m', subject], cwd, env);
+    const commit = gitHard(['rev-parse', 'HEAD'], cwd, env).stdout.trim();
+    note(subject);
+    return {
+        outcome: resolved ? 'resolved' : 'repaused',
+        commit,
+        sidecarPath,
+    };
+}
+/** Read the item body from disk (the resolve path with no supplied body). */
+function readItem(itemAbs, cwd, itemPath, env) {
+    const show = gitSoft(['show', `:${itemPath}`], cwd, env);
+    if (show.status === 0) {
+        return show.stdout;
+    }
+    // Fall back to the working-tree file (uncommitted item).
+    try {
+        return readFileSync(itemAbs, 'utf8');
+    }
+    catch {
+        throw new ApplyAtomicError(`cannot read item body for '${itemPath}' (supply itemBody)`);
+    }
+}
+//# sourceMappingURL=sidecar-apply.js.map

package/dist/sidecar-apply.js.map

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

package/dist/sidecar.d.ts

@@ -0,0 +1,245 @@
+/**
+ * The **question/answer SIDECAR contract** (prd `advance-loop`, task
+ * `advance-sidecar-contract`) — the one genuinely-new piece of the `advance`
+ * family. A strict, tooling-OWNED per-item file `work/questions/<type>-<slug>.md`
+ * carrying per-entry answered-state, so the tooling fully owns the Q&A artifact
+ * (no fragile round-trip parse of human-authored prose in the item body).
+ *
+ * This module is the FORMAT + the in-memory model + the pure read/write/append/
+ * derived-`allAnswered` operations. The ATOMIC apply (mutate the item body AND
+ * the sidecar in ONE commit) lives in {@link applyAtomic} (`sidecar-apply.ts`).
+ * It builds NOTHING above the contract — no tick, no verb, no lock, no rungs;
+ * later tasks of the family consume these.
+ *
+ * # On-disk text format (REFORMATTED — ADR `question-sidecar-human-readable-format`)
+ *
+ * The sidecar is the HUMAN-FACING surface of the answer loop: humans read the
+ * question and write the answer in this file, very often through the GitHub web
+ * UI. The original `key: |` YAML-block-scalar format rendered as run-together
+ * noise on GitHub (literal `|` pipes, collapsed indentation). The on-disk format
+ * is now **real Markdown with machine state in HTML comments**:
+ *
+ *   - An IDENTITY HTML comment at the top carries `item`/`type`/`slug`/
+ *     `allAnswered` (`<!-- dorfl-sidecar: item=... type=... slug=... allAnswered=... -->`).
+ *   - Per entry: a `## Qn` heading (entry separator + answer boundary), a BOLD
+ *     question line, a BLOCKQUOTE context, an ITALIC suggested-default
+ *     (`_Suggested default: …_`), a per-entry HTML COMMENT carrying
+ *     `id=…` (and an explicit `answered=…` OVERRIDE when it disagrees with the
+ *     answer-derived predicate), a fixed answer marker
+ *     `**Your answer** (write below this line):`, then the human's answer prose.
+ *     (The `disposition=…` field is RETIRED — task
+ *     `agentic-apply-retire-disposition-vocabulary`; an entry is binary, and a
+ *     stale `disposition=` token in an old sidecar is parsed away.)
+ *   - The answer is HEADING-DELIMITED: it spans from the answer marker up to
+ *     the next entry `## ` heading (NOT a `---` rule), so a literal `---`
+ *     inside an answer cannot break parsing.
+ *
+ * GitHub renders HTML comments as nothing, so the machine state is invisible to
+ * the human and unbreakable by their edit. The human just types prose under the
+ * answer marker with no format knowledge.
+ *
+ * Round-trip is **SEMANTIC** (model-equal, not byte-equal): a parse → serialise
+ * canonicalises whitespace; the MODEL (entries, ids, answers, answered-state) is
+ * preserved. The load-bearing rules are kept:
+ *
+ *   - **Identity-keyed, NOT folder-keyed.** The path is derived PURELY from the
+ *     item's NAMESPACED identity (`<type>-<slug>`, `:`→`-` for the filename),
+ *     using {@link parseSlugArg} (the `slug-namespace.ts` resolver) as the single
+ *     source of truth for the identity. There is NO back-pointer field in the
+ *     item body — the only in-body signal is the existing `needsAnswers` flag —
+ *     so the sidecar survives the item's `git mv`s between lifecycle folders
+ *     with no lock-step move.
+ *   - **The answered predicate (MAINTAINER-RESOLVED §1):** a non-empty
+ *     `answer` ⇒ ANSWERED, with an explicit `answered=…` HTML-comment field as
+ *     an OVERRIDE. The override is encoded in the per-entry HTML comment ONLY
+ *     when it DISAGREES with the derived predicate (an empty answer with
+ *     `answered=true`, or a non-empty answer with `answered=false`); otherwise
+ *     the field is omitted so a tolerant "human only types under the answer
+ *     marker" edit cannot be re-interpreted as a sticky override on the next
+ *     parse.
+ *   - **`allAnswered` is DERIVED** — recomputed from the entries on every
+ *     serialise; the classifier MAY read it for a cheap scan but MUST NOT trust
+ *     it over the entries.
+ *   - **Entry ids are stable + monotonic** (`q1`, `q2`, …), NEVER reused.
+ *     APPEND adds `qN+1` and never mutates an existing answered entry (the
+ *     sidecar is the item's full Q&A history).
+ */
+/**
+ * The item-types a sidecar can key onto (the slug-namespace + obs).
+ *
+ * HARD CUTOVER (spec `prd-to-spec-vocabulary-cutover-and-migration-command`,
+ * contract step): the legacy `'prd'` type member is GONE — the parent-spec type
+ * is `'spec'` only. A `spec:<slug>` identity keys onto the `spec-<slug>`
+ * lock/sidecar entry. The on-disk `prd-<slug>.md` sidecar FILE (dorfl's
+ * not-yet-converted data) is still probed by {@link sidecarPathCandidates} as a
+ * legacy file-path fallback — that is a DATA alias the migration command removes,
+ * NOT this type member.
+ */
+export type SidecarType = 'spec' | 'task' | 'observation';
+/**
+ * The optional, machine-only `kind` AXIS on a question entry — the dispatch
+ * signal the answered-question apply rung reads to choose deterministic-action
+ * (`merge`, `stuck`) vs agentic-content (`triage`, `spec`) routing WITHOUT
+ * sniffing the shape of another field. Absent ⇒ the existing binary content
+ * entry (every pre-`kind` sidecar parses + renders byte-identically).
+ *
+ * INTERIM PRIMITIVE — REMOVE when question sidecars move to KIND-BASED
+ * SUBFOLDERS (`work/questions/merge/`, …), where the folder ENCODES the kind
+ * and this per-entry field is redundant. See the observation
+ * `questions-folder-rename-and-kind-axis-prefix-vs-subfolder-2026-06-21` + idea
+ * `folder-taxonomy-and-prd-edit-handshake`. Built deliberately as a single
+ * typed field read in exactly ONE place (the apply dispatch, a later task) so
+ * the folder-cutover can DELETE it in one move.
+ *
+ * A mistyped/unknown `kind=` token parses to `undefined` (silent-on-malformed,
+ * mirroring the retired `disposition` precedent), never a throw, never a
+ * coerce.
+ */
+export type SidecarKind = 'merge' | 'stuck' | 'triage' | 'spec';
+/** One question entry in the sidecar (the per-entry source of truth). */
+export interface SidecarEntry {
+    /** Stable, monotonic id (`q1`, `q2`, …); never reused once minted. */
+    id: string;
+    /** The question, verbatim. */
+    question: string;
+    /** Inline context so the human need not open the item. Empty when absent. */
+    context: string;
+    /** Optional suggested default (the surface-questions humility aid). */
+    default?: string;
+    /**
+     * The human's answer; empty/absent while unanswered. A NON-EMPTY answer ⇒
+     * answered (see {@link isEntryAnswered}).
+     */
+    answer: string;
+    /**
+     * The explicit `answered` OVERRIDE, when the human/tooling wrote one. `true`
+     * forces answered; `false` overrides a non-empty answer back to unanswered.
+     * `undefined` ⇒ no override (the answered-ness derives from `answer`).
+     */
+    answeredOverride?: boolean;
+    /**
+     * Optional dispatch axis (see {@link SidecarKind}). Absent ⇒ the existing
+     * binary content entry. INTERIM — removable once question sidecars move to
+     * kind-based SUBFOLDERS.
+     */
+    kind?: SidecarKind;
+}
+/** The parsed sidecar: identity frontmatter + ordered entries. */
+export interface SidecarModel {
+    /** The NAMESPACED identity (`spec:autotask`, `task:foo`, `observation:bar`). */
+    item: string;
+    /** The item type (redundant with the filename; explicit for the parser). */
+    type: SidecarType;
+    /** The bare slug. */
+    slug: string;
+    /** The ordered question entries (the source of truth for answered-state). */
+    entries: SidecarEntry[];
+}
+/** Raised for a structurally-invalid sidecar the parser cannot trust. */
+export declare class SidecarParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Is this entry ANSWERED? The MAINTAINER-RESOLVED §1 predicate: a non-empty
+ * `answer` ⇒ answered, with the explicit `answered=…` override (carried in the
+ * per-entry HTML comment) winning when present. An explicit `answered=false`
+ * overrides a non-empty answer back to unanswered; an explicit `answered=true`
+ * forces answered even with an empty answer.
+ */
+export declare function isEntryAnswered(entry: SidecarEntry): boolean;
+/** Every entry that is NOT yet answered (derived from the entries). */
+export declare function pendingEntries(model: SidecarModel): SidecarEntry[];
+/**
+ * Is the WHOLE sidecar answered? DERIVED from the entries (never read off the
+ * identity comment mirror). An EMPTY sidecar (no entries) is NOT all-answered —
+ * a sidecar with no open questions should not exist (it would be deleted on
+ * full resolution), so `allAnswered` over zero entries is `false`, keeping the
+ * "pending ⇒ NO-OP" classifier honest.
+ */
+export declare function allAnswered(model: SidecarModel): boolean;
+/** The resolved identity of a sidecar: `{type, slug, item}`. */
+export interface SidecarIdentity {
+    type: SidecarType;
+    slug: string;
+    /** The canonical namespaced identity (`<namespace>:<slug>`). */
+    item: string;
+}
+/**
+ * Resolve a namespaced-identity argument (`spec:autotask`, `task:foo`,
+ * `observation:bar`, `obs:bar`, or a bare `<slug>` = task) into its
+ * `{type, slug, item}`. PURE string work over {@link parseSlugArg} — the
+ * resolver is the single source of truth for the task/spec split; the sidecar
+ * extends it with the `observation` namespace.
+ */
+export declare function resolveSidecarIdentity(identity: string): SidecarIdentity;
+/**
+ * Derive the sidecar PATH `work/questions/<type>-<slug>.md` from the item's
+ * namespaced identity. The identity is the single source of truth; `:`→`-` for
+ * the filename. Accepts the same forms as {@link resolveSidecarIdentity}.
+ */
+export declare function sidecarPathFor(identity: string): string;
+/**
+ * The ordered candidate sidecar PATHS a READER should probe for `identity`: the
+ * canonical {@link sidecarPathFor} path FIRST, then any legacy-data fallback that
+ * may still be on disk before the migration command converts it.
+ *
+ * MIGRATE step (prd `prd-to-spec-vocabulary-cutover-and-migration-command`): the
+ * producer side now emits `spec:<slug>`, so {@link sidecarPathFor} resolves
+ * `work/questions/spec-<slug>.md`. But the ON-DISK sidecar is still the legacy
+ * `work/questions/prd-<slug>.md` until `dorfl prd-to-spec` renames the DATA. So a
+ * `spec`-typed identity ALSO probes the legacy `prd-<slug>.md` as a fallback, and
+ * a reader takes the FIRST candidate that exists. This is a FILE-PATH DATA alias
+ * the migration command removes (it converts `prd-<slug>.md → spec-<slug>.md` on
+ * disk); it is NOT the `SlugNamespace`/`SidecarType` `'prd'` type member. Every
+ * non-`spec` type has a single candidate (its canonical path), unchanged.
+ */
+export declare function sidecarPathCandidates(identity: string): string[];
+/**
+ * Parse a sidecar document into its typed model. The on-disk format is the
+ * human-readable Markdown + HTML-comments form (see the module doc); the
+ * identity comment lives at the top, each entry opens with a `## ` heading, and
+ * the answer is heading-delimited (everything between the answer marker and the
+ * next `## ` heading is the answer). TOLERANT of the human typing only under
+ * the answer marker: a non-empty answer ⇒ answered (no comment edit needed).
+ */
+export declare function parseSidecar(text: string): SidecarModel;
+/**
+ * Serialise a model to its CANONICAL human-readable Markdown text. The identity
+ * HTML comment at the top carries `item`/`type`/`slug` + the derived
+ * `allAnswered` mirror; each entry is a `## Qn` heading, a bold question line,
+ * a blockquote context (when non-empty), an italic suggested-default (when
+ * present), a per-entry HTML comment carrying `id` (and an explicit `answered`
+ * override when it disagrees with the derived predicate), the fixed answer
+ * marker, then the answer prose. Round-trip is SEMANTIC:
+ * `parseSidecar(serialiseSidecar(m))` recovers an equal MODEL; re-serialising
+ * canonicalises the text.
+ */
+export declare function serialiseSidecar(model: SidecarModel): string;
+/** A new question to append (no id — the appender mints the next monotonic id). */
+export interface NewQuestion {
+    question: string;
+    context?: string;
+    default?: string;
+    /**
+     * Optional dispatch {@link SidecarKind} the surfacer stamps so the apply
+     * rung can route a runner-ACTION question (`merge`, `stuck`) to the
+     * deterministic dispatch vs a CONTENT question (`triage`, `spec`) to the
+     * agentic `decide()` path. INTERIM — removable once kind-subfolders land.
+     */
+    kind?: SidecarKind;
+}
+/**
+ * Append `newQuestions` to the model, minting `qN+1…` ids off the highest
+ * existing id. NEVER overwrites or mutates an existing entry (answered or not) —
+ * the sidecar is the item's full Q&A history. Appending flips a previously-
+ * `allAnswered` sidecar back to not-all-answered (the new entries are pending).
+ * Returns a NEW model (the input is not mutated).
+ */
+export declare function appendQuestions(model: SidecarModel, newQuestions: NewQuestion[]): SidecarModel;
+/**
+ * Build a fresh sidecar model for `identity` carrying `newQuestions` (ids minted
+ * `q1…`). The first-pass constructor the surface-question rung uses before there
+ * is any sidecar to append to.
+ */
+export declare function newSidecar(identity: string, newQuestions: NewQuestion[]): SidecarModel;
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../src/sidecar.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAShE,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC5B,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC5B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,IAAI,EAAE,WAAW,CAAC;IAClB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,yEAAyE;AACzE,qBAAa,iBAAkB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAK5D;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,EAAE,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAExD;AAgCD,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAiBxE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAOhE;AAgND;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAqDvD;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAkD5D;AAID,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,WAAW,EAAE,GACzB,YAAY,CAkBd;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACzB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,WAAW,EAAE,GACzB,YAAY,CASd"}