dorfl 0.0.0 → 0.1.0

package/dist/surface-gate.js

@@ -0,0 +1,206 @@
+import { NullHarness } from './harness.js';
+import { launchWithOptionalWatch } from './agent-launch.js';
+import { boundaryLine } from './watch-session.js';
+import { extractJsonObjectSpan } from './verdict-json.js';
+import { parseableJsonContractPrompt } from './review-verdict.js';
+/** Raised when the surface agent ran but produced no parseable emit. */
+export class SurfaceParseError extends Error {
+}
+/**
+ * Parse the `surface-questions` SKILL's emitted questions out of the surface
+ * agent's textual output. The skill emits a `{item, questions:[…]}` JSON object
+ * (the agent may wrap it in prose / a fenced block), so we extract the first JSON
+ * object carrying a `questions` field and validate its shape. An EMPTY
+ * `questions` list is VALID (the honest "no open judgement" result). Throws
+ * {@link SurfaceParseError} when no valid emit is present (the caller treats an
+ * unparseable emit as an error — never a silent "surfaced nothing").
+ *
+ * The emit MAY also carry a free-prose `note` field (the surface counterpart of
+ * the verdict's `review`): a HOME inside the object for the agent's reasoning /
+ * findings so it never needs to write prose AROUND the JSON (the cause of the
+ * "no parseable {questions}" trailing-chatter failure — observation
+ * `surface-rung-agent-emits-no-parseable-questions`). The engine does not
+ * persist `note`, so it is simply IGNORED here (like every unrecognised field);
+ * the prompt's job is to give the prose a place to go, not the parser's to keep
+ * it.
+ */
+export function parseSurfaceEmit(output) {
+    const span = extractJsonObjectSpan(output, 'questions');
+    if (span === undefined) {
+        throw new SurfaceParseError('surface agent produced no parseable {questions} result');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(output.slice(span.start, span.end));
+    }
+    catch (err) {
+        throw new SurfaceParseError(`surface emit was not valid JSON: ${err.message}`);
+    }
+    return validateEmit(parsed);
+}
+/** Validate a parsed object is a `{item?, questions:[…]}` shape; normalise it. */
+function validateEmit(parsed) {
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new SurfaceParseError('surface emit was not an object');
+    }
+    const obj = parsed;
+    if (!Array.isArray(obj.questions)) {
+        throw new SurfaceParseError('surface emit had no `questions` array (an empty array is valid; absence is not)');
+    }
+    const questions = obj.questions.map((q) => {
+        const item = (typeof q === 'object' && q !== null ? q : {});
+        const question = {
+            question: typeof item.question === 'string' ? item.question : '',
+        };
+        if (typeof item.context === 'string' && item.context !== '') {
+            question.context = item.context;
+        }
+        if (typeof item.default === 'string' && item.default !== '') {
+            question.default = item.default;
+        }
+        return question;
+    });
+    return {
+        ...(typeof obj.item === 'string' ? { item: obj.item } : {}),
+        // A question with an EMPTY `question` string carries no judgement — drop it
+        // (the agent may have emitted a placeholder), so an all-empty list is the
+        // same honest "no open judgement" as an empty array.
+        questions: questions.filter((q) => q.question.trim() !== ''),
+    };
+}
+/**
+ * Convert the emitted questions to the {@link NewQuestion} shape the engine
+ * appends to the sidecar — a 1:1 field map (the emit shape IS the sidecar
+ * authoring shape, by design), so the engine persists with ZERO translation.
+ */
+export function toNewQuestions(emit) {
+    return emit.questions.map((q) => {
+        const nq = { question: q.question };
+        if (q.context !== undefined) {
+            nq.context = q.context;
+        }
+        if (q.default !== undefined) {
+            nq.default = q.default;
+        }
+        return nq;
+    });
+}
+/**
+ * Render the surface-agent PROMPT: instruct a fresh-context agent to apply the
+ * **surface-questions discipline** (`work/protocol/SURFACE-PROTOCOL.md`) to ONE
+ * `work/` item and to EMIT a single `{item, questions}` JSON object (so
+ * {@link parseSurfaceEmit} can read it). The discipline body (the two laws —
+ * GATHER-only / PERSIST-NEVER — the humility rule, the composed sources, the
+ * emitted-question shape) lives in `SURFACE-PROTOCOL.md` — NOT inlined here
+ * (task `surface-protocol-doc-and-prompt`). The shape's source of truth is
+ * {@link parseSurfaceEmit}; the doc DESCRIBES it (D2).
+ *
+ * This builder owns ONLY the PER-BUILDER framing: who you are (a fresh-context
+ * question-surfacer, the engine's surface-question rung), what you are
+ * surfacing (ONE namespaced item), and the required JSON output shape. It
+ * MIRRORS {@link buildReviewPrompt}: a fresh-context agent that EDITS nothing
+ * and EMITS a single structured object the ENGINE routes/persists.
+ */
+export function buildSurfacePrompt(item) {
+    return [
+        `You are a FRESH-CONTEXT question-surfacer for the work/ item "${item}".`,
+        `Apply the surface-questions discipline defined in`,
+        `\`work/protocol/SURFACE-PROTOCOL.md\` (the in-band, protocol-native`,
+        `surface-questions protocol every set-up repo carries; the human-facing`,
+        `pointer is \`skills/surface-questions/SKILL.md\`) to this ONE item:`,
+        `formulate its open questions and EMIT them. Its two laws, its humility`,
+        `aid, the composed sources you draw from, and the emitted-question shape`,
+        `ALL live in that doc — read them there.`,
+        `The skill JUDGES; the engine PERSISTS.`,
+        ``,
+        `Do NOT edit any files, run no git — you EMIT questions only.`,
+        ``,
+        `Your investigation may be substantial (you compose review's verdict, you`,
+        `probe an observation against current reality). Put ANY explanation,`,
+        `reasoning, or "here is what I found" prose IN the \`note\` field of the JSON`,
+        `below — that is its home. This MIRRORS Gate-2's verdict, which carries its`,
+        `human-readable prose in a \`review\` field for exactly this reason: with a`,
+        `channel for prose INSIDE the object, you never need to write anything`,
+        `around it.`,
+        ``,
+        `The single JSON object below MUST be your FINAL and ONLY output. Do NOT`,
+        `narrate your process ("Let me check…"), do NOT add any remark, summary, or`,
+        `sign-off BEFORE or AFTER it, and do NOT take any further turn once you have`,
+        `emitted it — emitting the object is how you finish. A trailing chatty turn`,
+        `after the object strands the run (the reader sees only your last turn).`,
+        ``,
+        `Output ONLY a single JSON object of this exact shape (no prose OUTSIDE it;`,
+        `see \`SURFACE-PROTOCOL.md\` → "The emitted question shape" for the`,
+        `prose-described contract this mirrors). The example below is EXPANDED over`,
+        `several lines for READABILITY, but you MUST emit it MINIFIED — ONE single`,
+        `line, no newlines between the keys:`,
+        ``,
+        '```json',
+        `{"item": "${item}",`,
+        ` "questions": [`,
+        `   {"question": "…",`,
+        `    "context": "…",`,
+        `    "default": "… (optional; omit if none)"}`,
+        ` ],`,
+        ` "note": "… (optional; your reasoning / findings prose lives HERE, not outside the object)"}`,
+        '```',
+        ``,
+        `An EMPTY \`questions\` array is a VALID, honest result (no open judgement) —`,
+        `emit the object with \`"questions": []\` (put WHY in \`note\`); do NOT replace`,
+        `it with a prose explanation. Absence of the field is NOT valid.`,
+        ``,
+        // The SHARED defensive-JSON contract (the same hardening Gate-2's verdict
+        // prompt carries) — the surface rung hit the IDENTICAL unparseable-emit
+        // failure the verdict gate did, so it reuses the one contract rather than
+        // staying the lone un-hardened seam. The longest field is `note` (the free
+        // prose channel, the surface counterpart of the verdict's `review`).
+        parseableJsonContractPrompt('result', 'note'),
+    ].join('\n');
+}
+/**
+ * The PRODUCTION surface gate: launch the `surface-questions` SKILL as a
+ * fresh-context agent through the EXISTING harness seam, routing the
+ * `surfaceModel` override via `LaunchInput.model` (the §13 model-routing intent —
+ * NOT a new mechanism), then parse the emitted `{item, questions}`. It is the
+ * DIRECT mirror of `harnessReviewGate`: a SEPARATE harness launch (fresh context
+ * = not the engine's session) in the same checkout `cwd`, fed
+ * {@link buildSurfacePrompt}; the model flows through `LaunchInput.model`, which
+ * each adapter injects natively. The surface uses a DISTINCT session id
+ * (`<item>-surface`) so its session never collides with a build/review session.
+ */
+export function harnessSurfaceGate(options = {}) {
+    const harness = options.harness ?? new NullHarness();
+    const readOutput = options.readOutput ?? ((output) => output ?? '');
+    return async (input) => {
+        if (input.watch === true) {
+            const sink = input.watchSink ??
+                ((line) => process.stderr.write(`${line}\n`));
+            sink(boundaryLine(`surface — gathering questions for ${input.item}…`, input.color ?? false));
+        }
+        // A safe session-id stem (the namespaced identity has a `:` that is not a
+        // valid path stem). The same `:`→`-` convention the sidecar/lock identity uses.
+        const sessionId = `${input.item.replace(/:/g, '-')}-surface`;
+        const launched = await launchWithOptionalWatch({
+            harness,
+            dir: input.cwd,
+            slug: input.item,
+            command: options.agentCmd ?? '',
+            prompt: buildSurfacePrompt(input.item),
+            model: input.surfaceModel,
+            sessionId,
+            sessionsDir: input.sessionsDir,
+            watch: input.watch,
+            watchSink: input.watchSink,
+            color: input.color,
+            env: input.env,
+        });
+        if (!launched.ok) {
+            throw new SurfaceParseError(`surface agent launch failed${launched.detail ? `: ${launched.detail}` : ''}`);
+        }
+        // Read the emit from the agent's ANSWER channel (`output`), NOT `detail`
+        // (empty on success). An empty/absent output → parseSurfaceEmit throws → the
+        // engine surfaces nothing and reports it (never a silent success).
+        return parseSurfaceEmit(readOutput(launched.output));
+    };
+}
+//# sourceMappingURL=surface-gate.js.map

package/dist/surface-gate.js.map

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

package/dist/surface-persist.d.ts

@@ -0,0 +1,86 @@
+import { type NewQuestion } from './sidecar.js';
+/**
+ * The engine-owned SURFACE PERSIST (prd `advance-loop`, task
+ * `advance-rung-surface`, US #15/33) — the half of the surface rung the ENGINE
+ * owns (the skill JUDGES, the engine PERSISTS). Given the questions the
+ * `surface-questions` skill EMITTED (gathered by `surface-gate.ts`'s spawn), the
+ * engine writes them to the sidecar `work/questions/<type>-<slug>.md` and sets
+ * `needsAnswers:true` on the item body — in ONE commit, exactly as the review
+ * gate persists a verdict and `applyAtomic` resolves an answer batch in one
+ * commit.
+ *
+ * It is the SIBLING of {@link import('./sidecar-apply.js').applyAtomic}: that is
+ * the APPLY rung's one-commit primitive (resolve/re-pause); this is the SURFACE
+ * rung's one-commit primitive (append-or-create + set `needsAnswers`). Kept in a
+ * SEPARATE module so the surface rung's persist and the apply rung's persist stay
+ * file-orthogonal (the rung bodies land in different tasks).
+ *
+ * The load-bearing rules (the task's acceptance criteria):
+ *
+ *   - **Append-never-overwrite (US #15).** When a sidecar ALREADY exists, the new
+ *     questions are APPENDED ({@link appendQuestions} mints `qN+1…`), NEVER
+ *     overwriting an existing (answered or unanswered) entry. A re-surface that
+ *     adds questions to a previously-all-answered sidecar FLIPS it back to
+ *     not-all-answered (the appended entries are pending).
+ *   - **Set `needsAnswers:true` atomically (invariant 1).** The item body's
+ *     `needsAnswers` flag is set to `true` in the SAME commit the sidecar is
+ *     written, so the `needsAnswers:true ⟺ active sidecar` invariant holds the
+ *     instant the commit lands.
+ *   - **Identity-keyed sidecar path.** The sidecar path derives PURELY from the
+ *     item's namespaced identity ({@link sidecarPathFor}) — it survives the item's
+ *     `git mv`s with no lock-step move.
+ *
+ * This is the LOCAL one-commit primitive over a working tree (the
+ * throwaway-git-repo test pattern the apply/lock tests use). The `advancing` CAS
+ * lock that makes this WINNER-ONLY is held by `performAdvance` BEFORE this is
+ * called — so the expensive spawn + this persist are both POST-lock. This module
+ * does NOT race the arbiter; that is the lock's job.
+ */
+export interface SurfacePersistOptions {
+    /** Working clone/worktree the persist commits in. */
+    cwd: string;
+    /** The namespaced item identity (`task:foo` / `prd:bar` / `observation:baz`). */
+    item: string;
+    /**
+     * The item file path RELATIVE to `cwd` (e.g. `work/backlog/foo.md`). The
+     * `needsAnswers:true` flag is set on THIS file; the sidecar path is derived
+     * from the identity, NOT from this path.
+     */
+    itemPath: string;
+    /** The questions the `surface-questions` skill emitted (engine appends them). */
+    questions: NewQuestion[];
+    /** Advisory committer id for the commit subject. Defaults to git user.name. */
+    by?: string;
+    /** Environment for child git processes. */
+    env?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+}
+export interface SurfacePersistResult {
+    /** `surfaced` (questions written + needsAnswers set) or `nothing` (empty emit). */
+    outcome: 'surfaced' | 'nothing';
+    /** The commit sha the persist produced (`undefined` on a `nothing` no-op). */
+    commit?: string;
+    /** The sidecar path (relative to `cwd`) the persist touched. */
+    sidecarPath: string;
+    /** How many entries the sidecar carries after this persist. */
+    entryCount: number;
+}
+/** Raised for usage errors (a missing repo, an unreadable item). */
+export declare class SurfacePersistError extends Error {
+    constructor(message: string);
+}
+/**
+ * Persist the SURFACED questions ATOMICALLY: APPEND them to the existing sidecar
+ * (or CREATE it first-pass), and set `needsAnswers:true` on the item body — ONE
+ * commit. An EMPTY question set is a clean NO-OP (no sidecar written, the item
+ * untouched): the honest "no open judgement" result the skill is allowed to
+ * emit; nothing to commit, so `needsAnswers` is NOT set.
+ *
+ * Append-never-overwrite: when a sidecar exists, the new questions are APPENDED
+ * (never mutating an answered entry); a re-surface flips a previously-all-answered
+ * sidecar back to not-all-answered. Returns the produced commit + the resulting
+ * entry count.
+ */
+export declare function persistSurfacedQuestions(options: SurfacePersistOptions): SurfacePersistResult;
+//# sourceMappingURL=surface-persist.d.ts.map

package/dist/surface-persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-persist.d.ts","sourceRoot":"","sources":["../src/surface-persist.ts"],"names":[],"mappings":"AAIA,OAAO,EAMN,KAAK,WAAW,EAEhB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,MAAM,WAAW,qBAAqB;IACrC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACpC,mFAAmF;IACnF,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,oEAAoE;AACpE,qBAAa,mBAAoB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI3B;AAiCD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,qBAAqB,GAC5B,oBAAoB,CA2EtB"}

package/dist/surface-persist.js

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { run } from './git.js';
+import { parseFrontmatter, setNeedsAnswersMarker } from './frontmatter.js';
+import { appendQuestions, newSidecar, parseSidecar, serialiseSidecar, sidecarPathFor, } from './sidecar.js';
+/** Raised for usage errors (a missing repo, an unreadable item). */
+export class SurfacePersistError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SurfacePersistError';
+    }
+}
+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 SurfacePersistError(`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 ?? '';
+}
+/**
+ * Persist the SURFACED questions ATOMICALLY: APPEND them to the existing sidecar
+ * (or CREATE it first-pass), and set `needsAnswers:true` on the item body — ONE
+ * commit. An EMPTY question set is a clean NO-OP (no sidecar written, the item
+ * untouched): the honest "no open judgement" result the skill is allowed to
+ * emit; nothing to commit, so `needsAnswers` is NOT set.
+ *
+ * Append-never-overwrite: when a sidecar exists, the new questions are APPENDED
+ * (never mutating an answered entry); a re-surface flips a previously-all-answered
+ * sidecar back to not-all-answered. Returns the produced commit + the resulting
+ * entry count.
+ */
+export function persistSurfacedQuestions(options) {
+    const { cwd, item, itemPath, questions, env } = options;
+    const note = options.note ?? (() => { });
+    if (gitSoft(['rev-parse', '--git-dir'], cwd, env).status !== 0) {
+        throw new SurfacePersistError('not inside a git repository');
+    }
+    const sidecarPath = sidecarPathFor(item);
+    const sidecarAbs = join(cwd, sidecarPath);
+    // Build the post-persist sidecar model: APPEND to an existing one (never
+    // overwrite), else CREATE first-pass. Read the current sidecar from the tree
+    // so the append is over the COMMITTED history (identity-keyed, folder-agnostic).
+    let model;
+    const existing = readExistingSidecar(sidecarAbs);
+    if (existing !== undefined) {
+        model = appendQuestions(existing, questions);
+    }
+    else {
+        model = newSidecar(item, questions);
+    }
+    // An empty emit ⇒ the sidecar would carry no entries: surface NOTHING (the
+    // honest result). Do NOT write a sidecar or set `needsAnswers` — a sidecar with
+    // no open questions should not exist (it keeps invariant 1 + the "pending ⇒
+    // NO-OP" classifier honest).
+    if (model.entries.length === 0) {
+        const message = `surface ${item}: no open judgement — nothing surfaced (no sidecar written).`;
+        note(message);
+        return { outcome: 'nothing', sidecarPath, entryCount: 0 };
+    }
+    // Set `needsAnswers:true` on the item body (the only in-body signal — the
+    // sidecar path is identity-derived, no back-pointer). The item file may not
+    // have a `needsAnswers` line yet (and may be fence-less — observations are born
+    // that way); `setNeedsAnswersMarker` prepends a fence when needed and is
+    // idempotent otherwise.
+    const itemAbs = join(cwd, itemPath);
+    const itemBody = readItem(itemAbs, cwd, itemPath, env);
+    const flagged = setNeedsAnswersMarker(itemBody, true);
+    // DEFENSE IN DEPTH (the `sidecar-without-needsAnswers` guard): the surface
+    // commit is only atomic if the flag ACTUALLY landed. If — for any reason — the
+    // flag did not parse back as `true` (e.g. a degenerate body the marker writer
+    // cannot annotate), ABORT BEFORE writing the sidecar, so we never produce the
+    // torn invariant (sidecar present, flag absent) a later tick refuses to advance.
+    if (parseFrontmatter(flagged).needsAnswers !== true) {
+        throw new SurfacePersistError(`surface ${item}: could not set needsAnswers:true on '${itemPath}' ` +
+            `(the item body could not be annotated) — refusing to write the sidecar ` +
+            `without the flag (that would tear the needsAnswers ⟺ sidecar invariant).`);
+    }
+    writeFileSync(itemAbs, flagged);
+    // Write the appended/created sidecar.
+    mkdirSync(dirname(sidecarAbs), { recursive: true });
+    writeFileSync(sidecarAbs, serialiseSidecar(model));
+    // Stage exactly the two paths and commit them TOGETHER (one atomic commit) —
+    // the sidecar write + the `needsAnswers:true` flip land in the SAME commit, so
+    // `needsAnswers:true ⟺ active sidecar` holds the instant it lands.
+    const by = options.by || resolveBy(cwd, env);
+    gitHard(['add', '--', itemPath, sidecarPath], cwd, env);
+    const subject = `advance: surface ${item} (${model.entries.length} question(s), by ${by})`;
+    gitHard(['commit', '--quiet', '-m', subject], cwd, env);
+    const commit = gitHard(['rev-parse', 'HEAD'], cwd, env).stdout.trim();
+    note(subject);
+    return {
+        outcome: 'surfaced',
+        commit,
+        sidecarPath,
+        entryCount: model.entries.length,
+    };
+}
+/** Read + parse the existing sidecar (from the tree, then the working file). */
+function readExistingSidecar(sidecarAbs) {
+    if (!existsSync(sidecarAbs)) {
+        return undefined;
+    }
+    return parseSidecar(readFileSync(sidecarAbs, 'utf8'));
+}
+/** Read the item body from the tree (committed) then the working-tree file. */
+function readItem(itemAbs, cwd, itemPath, env) {
+    const show = gitSoft(['show', `:${itemPath}`], cwd, env);
+    if (show.status === 0) {
+        return show.stdout;
+    }
+    try {
+        return readFileSync(itemAbs, 'utf8');
+    }
+    catch {
+        throw new SurfacePersistError(`cannot read item body for '${itemPath}' (the surface rung needs the item file)`);
+    }
+}
+//# sourceMappingURL=surface-persist.js.map

package/dist/surface-persist.js.map

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