dorfl 0.0.0 → 0.1.0

package/dist/mint-adr.js

@@ -0,0 +1,257 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { run } from './git.js';
+import { createItemThroughCas, } from './advancing-lock.js';
+import { resolveSidecarIdentity, sidecarPathFor } from './sidecar.js';
+/**
+ * The **ADR-MINT route** (prd
+ * `agentic-question-resolution-retire-disposition-vocabulary` US #2, task
+ * `agentic-apply-mint-adr-route`) — the SIBLING of {@link
+ * import('./triage-persist.js').promoteObservation}, for the agentic apply
+ * `mint-adr` verdict.
+ *
+ * Why a SIBLING and not an `adr` artifact type on `promoteObservation`
+ * (recorded `## Decisions`): `promoteObservation` is `work/`-folder-SHAPED — it
+ * targets `work/tasks/ready` / `work/prds/proposed` via `workItemRel`, and builds
+ * a task/prd body (a `## What to build` / `## Problem Statement` lead + an
+ * `## Open questions` block, with `needsAnswers` carried). An ADR is DIFFERENT in
+ * EVERY one of those: it lives in `docs/adr/` (OUTSIDE the work board, so the
+ * `work/`-layout path builder does not fit), it carries NO `needsAnswers`/open-
+ * questions block (an ADR records a SETTLED decision, the antithesis of an open
+ * question), and its body is the ADR-FORMAT shape (a context/decision/why record).
+ * Forking the body+target branch inside `promoteObservation` would make that
+ * function mean two unrelated things; a sibling that REUSES the shared CAS-create
+ * primitive (and nothing else) is the cleaner seam.
+ *
+ * It REUSES the keystone's guarantees verbatim, because both go through the SAME
+ * {@link createItemThroughCas} primitive (the new-item-creation CAS from
+ * `advancing-lock-borrow`): the source observation + its answered sidecar are
+ * `git rm`-ed IN THE SAME atomic commit as the ADR create (delete-on-promote),
+ * and a CAS LOSER — which never reaches the commit — backs off WITHOUT deleting
+ * the source (left intact for a retry). The ONLY differences from
+ * `promoteObservation` are the TARGET path (`docs/adr/<slug>.md`) and the BODY
+ * shape (the ADR record).
+ */
+function gitSoft(args, cwd, env) {
+    return run('git', args, cwd, { env });
+}
+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 ?? '';
+}
+/** Read the observation body from the tree (committed) then the working file. */
+function readItem(cwd, itemPath, env) {
+    const show = gitSoft(['show', `:${itemPath}`], cwd, env);
+    if (show.status === 0) {
+        return show.stdout;
+    }
+    try {
+        return readFileSync(join(cwd, itemPath), 'utf8');
+    }
+    catch {
+        throw new MintAdrError(`cannot read observation body for '${itemPath}' (the ADR-mint route needs the item file)`);
+    }
+}
+/** Raised for usage errors (an empty slug, an unreadable observation). */
+export class MintAdrError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MintAdrError';
+    }
+}
+/**
+ * The repo-relative `docs/adr/` home for minted ADRs. ADRs live OUTSIDE the
+ * `work/` governance tree (so they are NOT in `work-layout.ts`'s registry); this
+ * is the single literal the route roots its target on. `docs/adr/` is created
+ * lazily by {@link createItemThroughCas} (it `mkdir -p`s the target's dirname).
+ */
+export const ADR_DIR_REL = 'docs/adr';
+/** The repo-relative path of a minted ADR file: `docs/adr/<slug>.md`. */
+export function adrItemRel(slug) {
+    return `${ADR_DIR_REL}/${slug}.md`;
+}
+/**
+ * Mint a NEW, SELF-CONTAINED ADR FROM an answered observation (the agentic apply
+ * `mint-adr` verdict, US #2): CAS-create `docs/adr/<slug>.md` keyed on the new
+ * ADR's identity (its path), with the source observation + its answered sidecar
+ * `git rm`-ed IN THE SAME atomic commit. The mint is ONE commit (create + delete).
+ *
+ * The minted body is built FROM the source + the answered question(s) (see
+ * {@link buildAdrBody}) so an engineer can read the decision's WHY from the ADR
+ * ALONE — that self-containment is the PRECONDITION for the same-commit deletion
+ * of the source. An agent-drafted `adrBody` (when present) is used verbatim.
+ *
+ * The CAS-create is the new-item-creation helper ({@link createItemThroughCas}):
+ * a same-slug ADR race needs NO special case — exactly one creator lands the
+ * file, the LOSER fails the CAS (exit 2) and backs off WITHOUT deleting the
+ * source (so a retry can re-mint). The source (+ its sidecar) is deleted ONLY on a
+ * WIN, riding the winning creator's commit.
+ */
+export async function mintAdr(options) {
+    const { cwd, item, itemPath, env } = options;
+    const note = options.note ?? (() => { });
+    const { slug: obsSlug } = resolveSidecarIdentity(item);
+    const adrSlug = (options.adrSlug ?? obsSlug).trim();
+    if (adrSlug === '') {
+        return {
+            outcome: 'usage-error',
+            exitCode: 1,
+            message: `mint-adr ${item}: empty ADR slug — cannot draft an ADR`,
+        };
+    }
+    const adrPath = adrItemRel(adrSlug);
+    const by = options.by || resolveBy(cwd, env);
+    const title = (options.adrTitle ?? adrSlug).trim() || adrSlug;
+    const content = options.adrBody !== undefined && options.adrBody.trim() !== ''
+        ? renderAdrFile(adrSlug, title, options.adrBody.trim())
+        : buildAdrBody({
+            slug: adrSlug,
+            title,
+            observation: readItem(cwd, itemPath, env),
+            answers: options.answers ?? [],
+        });
+    // The source note + its answered sidecar `git rm` IN THE SAME create commit
+    // (mint = ONE atomic commit). A CAS LOSER never reaches the commit, so it
+    // leaves both INTACT for a retry (the loser-backs-off guarantee, over deletion).
+    const sidecarPath = sidecarPathFor(item);
+    const created = await createItemThroughCas({
+        path: adrPath,
+        content,
+        deletePaths: [itemPath, sidecarPath],
+        cwd,
+        arbiter: options.arbiter,
+        by,
+        dryRun: options.dryRun,
+        env,
+        note,
+        ...(options.contention !== undefined
+            ? { contention: options.contention }
+            : {}),
+    });
+    if (created.exitCode !== 0) {
+        const message = `mint-adr ${item}: the new ADR ${adrPath} ${created.outcome} the ` +
+            `create CAS (${created.message}) — backing off, the observation is left ` +
+            'intact for a retry.';
+        note(message);
+        return {
+            outcome: created.outcome === 'lost' ? 'lost' : 'contended',
+            exitCode: created.exitCode,
+            message,
+        };
+    }
+    const message = `minted ${item} → CREATED ${adrPath} (via the CAS) + DELETED the ` +
+        'observation + its sidecar in the same commit.';
+    note(message);
+    return { outcome: 'minted', exitCode: 0, adrPath, message };
+}
+/**
+ * Build a SELF-CONTAINED ADR file FROM an answered observation + its answer(s),
+ * in the repo's existing `docs/adr/` shape (recorded `## Decisions`): a `---`
+ * frontmatter fence (`title` / `status: accepted` / `created`) then a
+ * `# ADR: {title}` heading and the three ADR-FORMAT sections — **Context**
+ * (the source signal that prompted the decision), **Decision** (what was decided,
+ * from the human's answer), and **Why** (the rationale the answer carries). The
+ * decision's WHY is carried IN (the answer prose), so the ADR reads alone — the
+ * precondition for deleting the source in the same commit.
+ *
+ * The mechanism prose of the observation (everything before its first
+ * `## Open questions` heading, frontmatter dropped) seeds Context; the
+ * question(s)+answer(s) seed Decision + Why. When no answers are threaded the
+ * Decision/Why fall back to the observation's prose so the file is never empty.
+ */
+export function buildAdrBody(input) {
+    const context = mechanismOf(input.observation).trim();
+    const decisionLines = [];
+    const whyLines = [];
+    for (const { question, answer } of input.answers) {
+        const q = question.trim();
+        const a = answer.trim();
+        if (q !== '' || a !== '') {
+            decisionLines.push(`- **${q || '(question)'}** — ${a || '(no answer)'}`);
+            if (a !== '') {
+                whyLines.push(a);
+            }
+        }
+    }
+    const body = [
+        '## Context',
+        '',
+        context === ''
+            ? '(no source context was carried from the observation.)'
+            : context,
+        '',
+        '## Decision',
+        '',
+        decisionLines.length > 0
+            ? decisionLines.join('\n')
+            : '(the decision is recorded in the source context above.)',
+        '',
+        '## Why',
+        '',
+        whyLines.length > 0
+            ? whyLines.join('\n\n')
+            : 'The decision follows directly from the answered question(s) above; the source signal is preserved in this ADR (the note itself leaves by deletion, git history is the archive).',
+        '',
+    ];
+    return renderAdrFile(input.slug, input.title, body.join('\n'));
+}
+/**
+ * Wrap an ADR `body` (the markdown AFTER the frontmatter) in the repo's existing
+ * ADR file shape: a `---` frontmatter fence (`title` / `status: accepted` /
+ * `created`) then a `# ADR: {title}` heading, then the body. Mirrors the existing
+ * `docs/adr/*.md` convention (slug-named files with a frontmatter block), NOT the
+ * `NNNN-` numeric prefix the ADR-FORMAT template shows — the repo's LIVE
+ * convention wins (recorded `## Decisions`).
+ */
+function renderAdrFile(slug, title, body) {
+    const date = new Date().toISOString().slice(0, 10);
+    return [
+        '---',
+        `title: ${title}`,
+        'status: accepted',
+        `created: ${date}`,
+        '---',
+        '',
+        `# ADR: ${title}`,
+        '',
+        body.replace(/\s*$/, ''),
+        '',
+    ].join('\n');
+}
+/**
+ * The observation's mechanism PROSE: everything before its first
+ * `## Open questions` heading, with the frontmatter fence dropped. An ADR records
+ * a SETTLED decision, so an observation's open-questions scoping is deliberately
+ * NOT carried into the ADR body (unlike a promoted task/prd, which keeps the
+ * open questions live) — the answered question(s) ARE the decision.
+ */
+function mechanismOf(observation) {
+    const body = stripFrontmatter(observation);
+    const lines = body.split('\n');
+    const startIdx = lines.findIndex((l) => /^##\s+Open questions\b/i.test(l));
+    if (startIdx === -1) {
+        return body;
+    }
+    return lines.slice(0, startIdx).join('\n');
+}
+/** Strip a leading `---\n…\n---` frontmatter fence, returning the body. */
+function stripFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, '\n').replace(/^\uFEFF/, '');
+    if (!normalized.startsWith('---\n')) {
+        return normalized;
+    }
+    const lines = normalized.split('\n');
+    const closing = lines.indexOf('---', 1);
+    if (closing === -1) {
+        return normalized;
+    }
+    return lines
+        .slice(closing + 1)
+        .join('\n')
+        .replace(/^\n+/, '');
+}
+//# sourceMappingURL=mint-adr.js.map

package/dist/mint-adr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mint-adr.js","sourceRoot":"","sources":["../src/mint-adr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,SAAS,CAAC;AACrC,OAAO,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAC/B,OAAO,EAAC,GAAG,EAAiB,MAAM,UAAU,CAAC;AAC7C,OAAO,EACN,oBAAoB,GAGpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAC,sBAAsB,EAAE,cAAc,EAAC,MAAM,cAAc,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,SAAS,OAAO,CACf,IAAc,EACd,GAAW,EACX,GAAkC;IAElC,OAAO,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAC,GAAG,EAAC,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,SAAS,CAAC,GAAW,EAAE,GAAkC;IACjE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IACD,MAAM,CAAC,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAC7B,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,iFAAiF;AACjF,SAAS,QAAQ,CAChB,GAAW,EACX,QAAgB,EAChB,GAAkC;IAElC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACzD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IACD,IAAI,CAAC;QACJ,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,IAAI,YAAY,CACrB,qCAAqC,QAAQ,4CAA4C,CACzF,CAAC;IACH,CAAC;AACF,CAAC;AAED,0EAA0E;AAC1E,MAAM,OAAO,YAAa,SAAQ,KAAK;IACtC,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC5B,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAEtC,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,IAAY;IACtC,OAAO,GAAG,WAAW,IAAI,IAAI,KAAK,CAAC;AACpC,CAAC;AAsED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAuB;IACpD,MAAM,EAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAC,GAAG,OAAO,CAAC;IAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAExC,MAAM,EAAC,IAAI,EAAE,OAAO,EAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO;YACN,OAAO,EAAE,aAAa;YACtB,QAAQ,EAAE,CAAC;YACX,OAAO,EAAE,YAAY,IAAI,wCAAwC;SACjE,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC;IAC9D,MAAM,OAAO,GACZ,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;QAC7D,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACvD,CAAC,CAAC,YAAY,CAAC;YACb,IAAI,EAAE,OAAO;YACb,KAAK;YACL,WAAW,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC;YACzC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;SAC9B,CAAC,CAAC;IAEN,4EAA4E;IAC5E,0EAA0E;IAC1E,iFAAiF;IACjF,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAEzC,MAAM,OAAO,GAA+B,MAAM,oBAAoB,CAAC;QACtE,IAAI,EAAE,OAAO;QACb,OAAO;QACP,WAAW,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;QACpC,GAAG;QACH,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,EAAE;QACF,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG;QACH,IAAI;QACJ,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS;YACnC,CAAC,CAAC,EAAC,UAAU,EAAE,OAAO,CAAC,UAAU,EAAC;YAClC,CAAC,CAAC,EAAE,CAAC;KACN,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,OAAO,GACZ,YAAY,IAAI,iBAAiB,OAAO,IAAI,OAAO,CAAC,OAAO,OAAO;YAClE,eAAe,OAAO,CAAC,OAAO,2CAA2C;YACzE,qBAAqB,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,CAAC;QACd,OAAO;YACN,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW;YAC1D,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,OAAO;SACP,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GACZ,UAAU,IAAI,cAAc,OAAO,+BAA+B;QAClE,+CAA+C,CAAC;IACjD,IAAI,CAAC,OAAO,CAAC,CAAC;IACd,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,KAK5B;IACA,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,EAAC,QAAQ,EAAE,MAAM,EAAC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAChD,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;YAC1B,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,YAAY,QAAQ,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC;YACzE,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACF,CAAC;IACF,CAAC;IACD,MAAM,IAAI,GAAa;QACtB,YAAY;QACZ,EAAE;QACF,OAAO,KAAK,EAAE;YACb,CAAC,CAAC,uDAAuD;YACzD,CAAC,CAAC,OAAO;QACV,EAAE;QACF,aAAa;QACb,EAAE;QACF,aAAa,CAAC,MAAM,GAAG,CAAC;YACvB,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;YAC1B,CAAC,CAAC,yDAAyD;QAC5D,EAAE;QACF,QAAQ;QACR,EAAE;QACF,QAAQ,CAAC,MAAM,GAAG,CAAC;YAClB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;YACvB,CAAC,CAAC,iLAAiL;QACpL,EAAE;KACF,CAAC;IACF,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,IAAY,EAAE,KAAa,EAAE,IAAY;IAC/D,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACnD,OAAO;QACN,KAAK;QACL,UAAU,KAAK,EAAE;QACjB,kBAAkB;QAClB,YAAY,IAAI,EAAE;QAClB,KAAK;QACL,EAAE;QACF,UAAU,KAAK,EAAE;QACjB,EAAE;QACF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACxB,EAAE;KACF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,WAAmB;IACvC,MAAM,IAAI,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,2EAA2E;AAC3E,SAAS,gBAAgB,CAAC,OAAe;IACxC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACzE,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,OAAO,UAAU,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACxC,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;QACpB,OAAO,UAAU,CAAC;IACnB,CAAC;IACD,OAAO,KAAK;SACV,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;SAClB,IAAI,CAAC,IAAI,CAAC;SACV,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACvB,CAAC"}

package/dist/mirror-pool-scan.d.ts

@@ -0,0 +1,125 @@
+import type { Config } from './config.js';
+import { type LedgerReadStrategy } from './ledger-read.js';
+import { type ScannedItem, type ScanReport } from './scan.js';
+import { type SpecCandidate, type SelectedLifecyclePools } from './select-priority.js';
+import type { LifecyclePoolGates } from './lifecycle-pools.js';
+/**
+ * The MIRROR-SIDE eligible-pool scan — the isolated counterpart to
+ * `do-autopick`'s in-place pool scan ({@link performDoAuto}). It enumerates the
+ * SAME two pools (eligible TASKS + taskable PRDS) but reads a BARE hub mirror's
+ * committed `main` ref (`git ls-tree`/`git show`), NOT a working checkout.
+ *
+ * This is the ONE reusable enumeration unit the prd's FOLD-IN note demands: BOTH
+ * the `run` loop driver's isolated+parallel auto-pick AND the one-shot/CI
+ * `advance --remote -n` / the CI matrix consume it, so the `-n`/auto-pick rungs
+ * (both `do` and `advance`, both `run`-loop and one-shot) all call the SAME scan.
+ * A standalone `do --remote -n` then falls out as a thin caller — the scan is NOT
+ * invented twice (the existing inline `-n`×`--remote` REFUSAL in `cli.ts` is the
+ * placeholder this scan replaces; removing the refusal is the driver/caller's job).
+ *
+ * It only ENUMERATES the pool — it never claims, builds, or runs anything. `-n`
+ * stays ALWAYS SEQUENTIAL (US #25): the selection layer ({@link selectPrioritised})
+ * orders + counts; parallelism comes only from `run`'s concurrent loop or the CI
+ * matrix, never from this scan or from `-n`.
+ *
+ * It is the MIRROR-ref counterpart of `do-autopick`'s in-place scan, reusing the
+ * exact predicates rather than re-deriving them:
+ *
+ *   - **tasks** — {@link scoreItems} (the SAME eligibility scoring the in-place
+ *     `scanRepoPaths`/registry `scan` use) over the mirror's `work/backlog` +
+ *     `work/done` read via {@link LedgerReadStrategy.resolveMirrorState}.
+ *   - **taskable prds** — {@link taskableSpecs} (`autoslice-gate`'s predicate)
+ *     over the mirror's `work/prds/ready` + `work/prds/tasked` read via the mirror-ref
+ *     {@link LedgerReadStrategy.resolveMirrorSpecPool}.
+ *
+ * Per-repo policy parity: a bare mirror has no checked-out `.dorfl.json`,
+ * but the COMMITTED one is reachable on `main` (the `do --remote` per-repo seam).
+ * We layer it via {@link resolveRepoConfigFromMirror} so the same logical `work/`
+ * state yields the SAME `autoBuild`/`autoTask` decision an in-place checkout
+ * would — that is what makes the mirror scan PARITY-equal to the in-place one.
+ */
+/** What {@link scanMirrorPool} needs: which bare mirror + the global config. */
+export interface ScanMirrorPoolOptions {
+    /** The bare hub mirror directory (`<workspacesDir>/repos/<key>.git`). */
+    mirrorPath: string;
+    /**
+     * The global + default config layer. The repo's COMMITTED `.dorfl.json`
+     * (read from the mirror's `main`) is layered on top, so `autoBuild`/`autoTask`
+     * resolve per-repo exactly as the in-place scan resolves them from the checkout.
+     */
+    config: Config;
+    /**
+     * The mirror-LOCAL ref whose `work/` tree to read (default `main`). A bare hub
+     * mirror's `main` is a LOCAL branch — never `origin/main`.
+     */
+    ref?: string;
+    /**
+     * Override the read seam (tests inject a stub). Defaults to the active
+     * {@link ledgerRead} — the SAME seam the in-place scan reads through.
+     */
+    read?: LedgerReadStrategy;
+    /**
+     * Sink for a non-fatal per-repo-config read warning. The scan must never error
+     * out on a config-read fault — it falls back to global + default (the
+     * no-per-repo behaviour) and warns. (Fetch-first freshness is the CALLER's job,
+     * exactly as it is for the registry `scan`; this reads the already-fetched ref.)
+     */
+    warn?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The LIFECYCLE-POOL create-gates (task `advance-autopick-lifecycle-pools`),
+     * the internal hook the gate tasks will wire to `observationTriage` /
+     * `surfaceBlockers`. INTERIM, born OFF: omitted ⇒ BOTH create-gates OFF, so the
+     * mirror-side triage + surface sub-pools contribute NOTHING (the apply sub-pool
+     * is always-on). The mirror enumeration mirrors the in-place one exactly.
+     */
+    lifecycleGates?: LifecyclePoolGates;
+    /**
+     * The per-machine config-override map (ADR
+     * `per-machine-config-override-layer`), threaded into the mirror-side per-repo
+     * resolution so the override applies to the autopick pool scan. Default: empty.
+     */
+    override?: import('./config-override.js').ConfigOverrideMap;
+}
+/**
+ * The enumerated mirror-side pool — the isolated counterpart of `do-autopick`'s
+ * two pools. Both drivers feed `report` + `prds` into the SAME
+ * {@link selectPrioritised} (the loop driver takes all; the one-shot/CI driver
+ * bounds by a SEQUENTIAL `count`).
+ */
+export interface MirrorPoolScanResult {
+    /**
+     * The task pool as a one-repo {@link ScanReport} (the mirror is the single
+     * repo), scored through {@link scoreItems} — the SAME shape
+     * {@link selectPrioritised} consumes for the in-place scan, so the task
+     * selection is byte-identical to `run`'s.
+     */
+    report: ScanReport;
+    /** Every scanned task (eligible or not), in scan order. */
+    tasks: ScannedItem[];
+    /** Just the eligible subset of {@link tasks} (convenience for assertions/callers). */
+    eligibleTasks: ScannedItem[];
+    /**
+     * The TASKABLE SPEC pool — already filtered through `taskableSpecs`
+     * (`autoslice-gate`'s predicate). In declaration order; the selection layer
+     * does not re-gate it.
+     */
+    specs: SpecCandidate[];
+    /**
+     * The LIFECYCLE pools (task `advance-autopick-lifecycle-pools`): untriaged
+     * observations (triage), `needsAnswers`-blocked items with no all-answered
+     * sidecar (surface), and answered-sidecar items (apply). Built through the SAME
+     * shared {@link buildLifecyclePools} unit the in-place caller uses (NOT a second
+     * enumeration), so the in-place + mirror-side selections AGREE. The create-gates
+     * default OFF (interim); apply is always present. The drivers feed this straight
+     * into {@link selectPrioritised}'s `lifecycle` slot.
+     */
+    lifecycle: SelectedLifecyclePools;
+}
+/**
+ * Run the mirror-side eligible-pool scan over a single bare hub mirror. Reads
+ * both pools from its committed `main`, scores/filters them through the EXACT
+ * in-place predicates, and returns the shape both drivers consume.
+ */
+export declare function scanMirrorPool(options: ScanMirrorPoolOptions): Promise<MirrorPoolScanResult>;
+//# sourceMappingURL=mirror-pool-scan.d.ts.map

package/dist/mirror-pool-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror-pool-scan.d.ts","sourceRoot":"","sources":["../src/mirror-pool-scan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,EAAa,KAAK,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAErE,OAAO,EAIN,KAAK,WAAW,EAChB,KAAK,UAAU,EAEf,MAAM,WAAW,CAAC;AACnB,OAAO,EAEN,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACrC,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,sBAAsB,EAAE,iBAAiB,CAAC;CAC5D;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB,2DAA2D;IAC3D,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,sFAAsF;IACtF,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B;;;;OAIG;IACH,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB;;;;;;;;OAQG;IACH,SAAS,EAAE,sBAAsB,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CACnC,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAgG/B"}

package/dist/mirror-pool-scan.js

@@ -0,0 +1,104 @@
+import { ledgerRead } from './ledger-read.js';
+import { resolveRepoConfigFromMirror } from './repo-mirror.js';
+import { scoreItems, scoreSpecs, toScannedLifecycle, } from './scan.js';
+import { taskableSpecs, } from './select-priority.js';
+import { gatherLifecycleMirror } from './lifecycle-gather.js';
+import { heldTaskSlugs } from './item-lock.js';
+/**
+ * Run the mirror-side eligible-pool scan over a single bare hub mirror. Reads
+ * both pools from its committed `main`, scores/filters them through the EXACT
+ * in-place predicates, and returns the shape both drivers consume.
+ */
+export async function scanMirrorPool(options) {
+    const { mirrorPath, config, ref = 'main', env } = options;
+    const read = options.read ?? ledgerRead;
+    const warn = options.warn;
+    // Per-repo policy parity: layer the COMMITTED `.dorfl.json` from the
+    // mirror's `main` (the `do --remote` per-repo seam) onto global. Never fatal —
+    // a config-less repo or a read fault falls back to global + default.
+    let repoConfig;
+    try {
+        repoConfig = resolveRepoConfigFromMirror({
+            mirrorPath,
+            global: config,
+            env,
+            override: options.override,
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        warn?.(`could not read the target repo's config from ${mirrorPath}/main; ` +
+            `resolving from global + default. ${reason}`);
+        repoConfig = config;
+    }
+    // Pool 1 — eligible TASKS from the bare mirror's `work/backlog`+`work/done`,
+    // scored through the EXACT same `scoreItems` the in-place/registry scans use.
+    const state = await read.resolveMirrorState({ mirrorPath, ref, env });
+    const counts = { totalItems: 0, totalEligible: 0 };
+    // HELD-SLUG SUBTRACTION (prd `ledger-status-per-item-lock-refs` US #15): a bare
+    // hub mirror's arbiter is its `origin`; read the held lock refs from there and
+    // exclude those slugs from the enumerated `backlog/` pool. Non-fatal (empty set
+    // on any fault) and redundant-but-harmless while the body still moves — wired now
+    // so task #9 needs no reader change. Freshness (fetch-first) is the CALLER's job
+    // for the pool ref, exactly as it is for the config read; `heldTaskSlugs` does
+    // its own lock-ref fetch.
+    const heldSlugs = await heldTaskSlugs(mirrorPath, 'origin', env);
+    const items = scoreItems(state, repoConfig.autoBuild, counts, heldSlugs);
+    // Pool 2 — TASKABLE PRDS from the bare mirror's `work/prds/ready`+`work/prds/tasked`,
+    // filtered through `autoslice-gate`'s predicate (NOT reinvented). Read FIRST so
+    // we can populate the `specs[]` companion of `items[]` on the RepoReport below.
+    const pool = await read.resolveMirrorSpecPool({ mirrorPath, ref, env });
+    const specs = taskableSpecs({
+        candidates: pool.specs.map((p) => ({
+            repoPath: mirrorPath,
+            slug: p.slug,
+            humanOnly: p.humanOnly,
+            needsAnswers: p.needsAnswers,
+            taskedAfter: p.taskedAfter,
+        })),
+        taskedSlugs: pool.taskedSlugs,
+        autoTask: repoConfig.autoTask,
+    });
+    // The one-slug-one-folder LINT is a HUMAN-FACING surface (`scan`/`status`); this
+    // mirror-side pool scan exists only to SCORE the task/prd candidate pools for
+    // autonomous selection, never to render a dashboard, so it carries an empty lint
+    // (the duplicate surface is the user-facing `scan`/`status`, per the task). The
+    // `specs[]` companion of `items[]` is filled via the SAME `scoreSpecs` helper
+    // `scan`/`scanRepoPaths` call — so the propose-matrix `jq` (`repos[].specs[] |
+    // select(.eligibility.eligible)`) sees the same shape on every surface.
+    // Pools 3 + 4 — the LIFECYCLE pools, gathered from the SAME mirror `main` (the
+    // `needsAnswers` backlog/prds + their sidecars + `work/notes/observations/`) and built
+    // through the SHARED enumeration unit the in-place caller uses — so the in-place
+    // + mirror-side selections AGREE. Create-gates default OFF (interim); apply
+    // (consume) is always present.
+    const lifecycle = await gatherLifecycleMirror({
+        mirrorPath,
+        ref,
+        read,
+        gates: options.lifecycleGates,
+        env,
+    });
+    const repo = {
+        path: mirrorPath,
+        items,
+        specs: scoreSpecs(mirrorPath, pool, repoConfig.autoTask),
+        // The propose-matrix lifecycle pool on this mirror's `RepoReport` — the SAME
+        // `gatherLifecycleMirror` result projected onto the `scan --json` shape, so
+        // the dashboard/matrix surface agrees with the selection scoring below.
+        lifecycle: toScannedLifecycle(lifecycle),
+        ledgerDuplicates: [],
+    };
+    const report = {
+        repos: [repo],
+        totalItems: counts.totalItems,
+        totalEligible: counts.totalEligible,
+    };
+    return {
+        report,
+        tasks: items,
+        eligibleTasks: items.filter((i) => i.eligibility.eligible),
+        specs,
+        lifecycle,
+    };
+}
+//# sourceMappingURL=mirror-pool-scan.js.map

package/dist/mirror-pool-scan.js.map

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