productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/packetIndexEntry.d.ts

@@ -0,0 +1,3 @@
+import type { PacketIndexEntry } from "./packetIndex.js";
+export declare function readPacketInput(dir: string, file: "tasks.yaml" | "spec.md"): string;
+export declare function derivePacketEntry(root: string, dir: string): PacketIndexEntry;

package/dist-public/src/packetIndexEntry.js

@@ -0,0 +1,128 @@
+// Per-packet index derivation (cli-performance-v0 R-001).
+//
+// One module on purpose: the serial path in packetIndex.ts and the worker
+// threads (packetIndexWorker.ts) must run the exact same reader, or the two
+// paths drift. Each packet's tasks.yaml is read once and parsed once, spec.md
+// is read once, and every derivation below consumes those single results —
+// previously five reads + two YAML parses per packet (720 readFileSync across
+// 141 packets, with 68% of self-time in the YAML parser).
+//
+// Pure with respect to the repo tree: reads only the packet's own files (plus
+// the retired-packet verdict tail of events.jsonl). Throws on malformed input;
+// callers decide the rendering.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "./vendorYaml.js";
+import { isRetired } from "./packetLifecycle.js";
+import { derivePacketStatusFromInputs } from "./packetStatus.js";
+import { deriveSpecDecisionSignals } from "./specDecisionSignals.js";
+export function readPacketInput(dir, file) {
+    try {
+        return readFileSync(path.join(dir, file), "utf8");
+    }
+    catch (error) {
+        // Mirror the shared reader's canonical missing-file message so a packet
+        // whose file vanishes between listing and reading renders the same error
+        // row `derivePacketStatus` produced before the refactor (exported for the
+        // malformed-input tests that pin this message).
+        if (error.code === "ENOENT")
+            throw new Error(`${file} missing in ${dir}`);
+        throw error;
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function str(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+// The task list comes from the shared derivePacketStatus reader (D-002), fed
+// the already-parsed tasks.yaml; the only field this index still reads from
+// that document directly is `updated`.
+function updatedFromTasksDoc(tasksDoc) {
+    return str(asRecord(tasksDoc).updated);
+}
+function readIntent(specText) {
+    let inIntent = false;
+    for (const line of specText.split(/\r?\n/)) {
+        if (/^##\s+/.test(line)) {
+            inIntent = /^##\s+Intent\s*$/i.test(line);
+            continue;
+        }
+        if (inIntent && line.trim() !== "") {
+            const sentence = line.trim().split(/(?<=[.!?])\s/)[0];
+            return sentence.length > 180 ? `${sentence.slice(0, 177)}...` : sentence;
+        }
+    }
+    return null;
+}
+function readDecisionSignals(root, packetDir, specText) {
+    return deriveSpecDecisionSignals(specText, path.relative(root, path.join(packetDir, "spec.md")));
+}
+function bucketOf(s) {
+    // A retirement verdict outranks task math: a killed packet with 0/7 done is
+    // not "open" backlog, it is retired intent (packet-lifecycle-v0 R-003).
+    if (isRetired(s.lifecycle))
+        return "retired";
+    if (s.tasks.total > 0 && s.tasks.done === s.tasks.total)
+        return "proven";
+    if (s.tasks.done === 0 && s.tasks.doing === 0)
+        return "open";
+    return "progress";
+}
+// Derive one packet's index entry: the single-pass read/parse/derive unit.
+// A malformed packet never throws out of here — it renders as an error row
+// (blank status + the error message), exactly as the index always rendered.
+export function derivePacketEntry(root, dir) {
+    try {
+        // Single pass (R-001): read tasks.yaml once, parse it once, read spec.md
+        // once — every derivation below consumes those results.
+        const tasksDoc = parseYaml(readPacketInput(dir, "tasks.yaml"));
+        const specText = readPacketInput(dir, "spec.md");
+        const status = derivePacketStatusFromInputs(dir, { tasksDoc, specText });
+        return {
+            ...status,
+            updated: updatedFromTasksDoc(tasksDoc),
+            intent: readIntent(specText),
+            decision_signals: readDecisionSignals(root, dir, specText),
+            bucket: bucketOf(status),
+        };
+    }
+    catch (error) {
+        const blank = {
+            packet: path.basename(dir),
+            spec_id: path.basename(dir),
+            title: null,
+            lifecycle: null,
+            lifecycle_stored: null,
+            lifecycle_effective: "in_flight",
+            lifecycle_drift: false,
+            stage: null,
+            mode: null,
+            tasks: { total: 0, done: 0, doing: 0, blocked: 0, todo: 0, dropped: 0 },
+            proof: { checks_total: 0, checks_done: 0 },
+            requirements: { total: 0, covered: 0 },
+            requirement_priorities: {},
+            completed: [],
+            task_list: [],
+            blocked: [],
+            stale: [],
+            open_questions: [],
+            next_action: { kind: "none", reason: "Packet status could not be read." },
+            decision_findings: [],
+            next: null,
+            drift: { restamp: false },
+            verdict: null,
+            deep_checked: false,
+        };
+        return {
+            ...blank,
+            updated: null,
+            intent: null,
+            decision_signals: deriveSpecDecisionSignals(""),
+            task_list: [],
+            bucket: "open",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist-public/src/packetIndexServe.d.ts

@@ -0,0 +1,13 @@
+import { type Server } from "node:http";
+import { type PacketIndexEntry } from "./packetIndex.js";
+export declare const DEFAULT_SERVE_PORT = 8000;
+export declare const DEFAULT_SERVE_HOST = "127.0.0.1";
+export declare function indexStateHash(index: PacketIndexEntry[]): string;
+export declare function injectLiveReload(html: string, pollMs?: number): string;
+export interface ServeOptions {
+    port?: number;
+    pollMs?: number;
+    host?: string;
+    deriveIndex?: (root: string) => PacketIndexEntry[];
+}
+export declare function serveIndex(root: string, options?: ServeOptions): Server;

package/dist-public/src/packetIndexServe.js

@@ -0,0 +1,113 @@
+// Live mode for the packet index (packet_index_v0). Serves the same
+// self-contained HTML that `--html` writes, but re-rendered from each packet's
+// tasks.yaml on every request, and tells the browser to reload only when the
+// derived spec state actually changes — so an open rollover does not collapse on
+// a timer. Read-only: it renders from disk and writes nothing.
+import { createServer } from "node:http";
+import { createHash } from "node:crypto";
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { derivePacketIndex, renderIndexHtml } from "./packetIndex.js";
+export const DEFAULT_SERVE_PORT = 8000;
+// Bind to loopback by default: the dashboard is unauthenticated, so it must not
+// be reachable from the local network (security-review-remediation-v0 R-003).
+export const DEFAULT_SERVE_HOST = "127.0.0.1";
+const DEFAULT_POLL_MS = 2000;
+// A content fingerprint of the derived index. The browser reloads only when this
+// changes, so formatting-stable polls never thrash the page.
+export function indexStateHash(index) {
+    return createHash("sha1").update(JSON.stringify(index)).digest("hex");
+}
+// Inject a poll-and-reload client before </body>. It reloads only when the state
+// hash changes, preserving scroll and open rollovers until something moves.
+export function injectLiveReload(html, pollMs = DEFAULT_POLL_MS) {
+    const script = [
+        "<script>",
+        "(function(){var last=null;",
+        "function tick(){",
+        "fetch('/__state',{cache:'no-store'}).then(function(r){return r.json();}).then(function(s){",
+        "if(last!==null&&s.hash!==last){location.reload();return;}",
+        "last=s.hash;setTimeout(tick," + pollMs + ");",
+        "}).catch(function(){setTimeout(tick," + pollMs + ");});",
+        "}tick();})();",
+        "</script>",
+    ].join("");
+    return html.includes("</body>") ? html.replace("</body>", `${script}\n</body>`) : html + script;
+}
+// A cheap fingerprint of everything derivePacketIndex reads: the recursive
+// shape of <root>/specs, hashed from each file's relative path, mtime, and
+// size. Statting ~3 files per packet is far cheaper than re-reading and
+// re-parsing them, so an unchanged specs tree (the common case for an open
+// dashboard) can skip re-derivation entirely (cli-performance-v0 R-004).
+// Deterministic within the walk: entries are sorted so directory order never
+// leaks into the hash. Throws (ENOENT) when specs/ is missing — the request
+// handler's generic 500 path, same as a failing derivation.
+function specsTreeFingerprint(root) {
+    const specsDir = path.join(root, "specs");
+    const hash = createHash("sha1");
+    const walk = (dir, rel) => {
+        const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1));
+        for (const entry of entries) {
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs, relPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const stats = statSync(abs);
+            hash.update(`${relPath}\0${stats.mtimeMs}\0${stats.size}\0`);
+        }
+    };
+    walk(specsDir, "");
+    return hash.digest("hex");
+}
+// Start the live dashboard server and return the listening server so callers
+// (and tests) can read its address and close it. The index is derived from disk
+// at most once per change to the specs tree: a state check re-derives only when
+// the fingerprint moves, and the page render reuses the same derivation — so
+// uncommitted tasks.yaml edits still show up immediately, but an unchanged poll
+// costs a directory stat walk, not a full re-derivation (cli-performance-v0 R-004).
+export function serveIndex(root, options = {}) {
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    const derive = options.deriveIndex ?? derivePacketIndex;
+    // Per-server cache, not module state: parallel servers (tests, two roots)
+    // must never see each other's derivations.
+    let cache = null;
+    const derivedState = () => {
+        const fingerprint = specsTreeFingerprint(root);
+        if (cache && cache.fingerprint === fingerprint)
+            return cache;
+        const index = derive(root);
+        cache = { fingerprint, index, hash: indexStateHash(index) };
+        return cache;
+    };
+    const server = createServer((req, res) => {
+        const url = (req.url ?? "/").split("?")[0];
+        try {
+            if (url === "/__state") {
+                res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+                res.end(JSON.stringify({ hash: derivedState().hash }));
+                return;
+            }
+            if (url === "/" || url === "/packet-index.html" || url === "/index.html") {
+                const html = injectLiveReload(renderIndexHtml(derivedState().index), pollMs);
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+                res.end(html);
+                return;
+            }
+            res.writeHead(404, { "content-type": "text/plain" });
+            res.end("not found");
+        }
+        catch (error) {
+            // Never disclose internals (stack traces, filesystem paths) to the client.
+            // Log the detail server-side for the operator; return a generic message.
+            console.error("packet-index dashboard render error:", error instanceof Error ? (error.stack ?? error.message) : String(error));
+            res.writeHead(500, { "content-type": "text/plain" });
+            res.end("dashboard render error");
+        }
+    });
+    server.listen(options.port ?? DEFAULT_SERVE_PORT, options.host ?? DEFAULT_SERVE_HOST);
+    return server;
+}

package/dist-public/src/packetIndexWorker.d.ts

@@ -0,0 +1,7 @@
+export interface PacketIndexWorkerData {
+    root: string;
+    dirs: string[];
+    sab: SharedArrayBuffer;
+    slotBase: number;
+    regionBytes: number;
+}

package/dist-public/src/packetIndexWorker.js

@@ -0,0 +1,45 @@
+// Worker entry for the packet index's parallel per-packet derivation
+// (cli-performance-v0 R-001).
+//
+// Message-free by design: the parent blocks synchronously in Atomics.wait
+// (derivePacketIndex must stay synchronous for its callers), so it could not
+// receive a postMessage while blocked. Results instead cross through this
+// worker's SharedArrayBuffer slot: header cell (0 pending, 1 done, 2 failed),
+// a byte-length cell, then the JSON-encoded entries.
+//
+// Each packet is still read once and parsed once (derivePacketEntry); workers
+// only split the packets across cores.
+import { workerData } from "node:worker_threads";
+import { derivePacketEntry } from "./packetIndexEntry.js";
+// Slot layout: [Int32 header][Int32 byteLength][Uint8 region].
+const LENGTH_OFFSET = 4;
+const REGION_OFFSET = 8;
+const DONE = 1;
+const FAILED = 2;
+function finish(sab, slotBase, state, payload) {
+    const header = new Int32Array(sab, slotBase, 1);
+    if (payload) {
+        new Int32Array(sab, slotBase + LENGTH_OFFSET, 1)[0] = payload.byteLength;
+        new Uint8Array(sab, slotBase + REGION_OFFSET, payload.byteLength).set(payload);
+    }
+    Atomics.store(header, 0, state);
+    Atomics.notify(header, 0);
+}
+try {
+    const data = workerData;
+    const entries = data.dirs.map((dir) => derivePacketEntry(data.root, dir));
+    const encoded = new TextEncoder().encode(JSON.stringify(entries));
+    const capacity = data.regionBytes - REGION_OFFSET;
+    if (encoded.byteLength > capacity) {
+        // Chunk too large for its slot: flag it and let the parent fall back to
+        // the serial path rather than truncating output.
+        finish(data.sab, data.slotBase, FAILED);
+    }
+    else {
+        finish(data.sab, data.slotBase, DONE, encoded);
+    }
+}
+catch {
+    const data = workerData;
+    finish(data.sab, data.slotBase, FAILED);
+}

package/dist-public/src/packetLifecycle.d.ts

@@ -0,0 +1,30 @@
+import { type JsonObject } from "./packetWrite.js";
+export declare const VERDICT_STATES: readonly ["parked", "killed", "active", "done"];
+export type VerdictState = (typeof VERDICT_STATES)[number];
+export declare const RETIRED_LIFECYCLES: Set<string>;
+export declare function isRetired(lifecycle: string | null | undefined): lifecycle is "parked" | "killed";
+export declare const TERMINAL_LIFECYCLES: Set<string>;
+export declare function isTerminal(lifecycle: string | null | undefined): boolean;
+export declare const LIFECYCLE_EVENT_TYPE = "com.adaptivespec.packet.lifecycle_changed";
+export type VerdictOptions = {
+    packetDir: string;
+    state: VerdictState;
+    reason: string;
+    actor?: {
+        type?: string;
+        id?: string;
+    };
+    now?: Date;
+};
+export type VerdictResult = {
+    event: JsonObject;
+    from: string | null;
+    to: VerdictState;
+};
+export declare function recordVerdict(options: VerdictOptions): VerdictResult;
+export type VerdictRecord = {
+    state: string;
+    reason: string | null;
+    at: string | null;
+};
+export declare function latestVerdict(packetDir: string, limit?: number): VerdictRecord | null;

package/dist-public/src/packetLifecycle.js

@@ -0,0 +1,127 @@
+// Packet lifecycle verdicts (packet-lifecycle-v0).
+//
+// productfoo could already say todo/doing/done/blocked — but not "we decided not to
+// do this." Abandonment is a verdict, and a tool whose thesis is that verdicts
+// carry reasons needs a recorded, reversible way to retire intent. Two terminal
+// states close that gap:
+//   - parked: still plausible, deliberately deferred; may come back.
+//   - killed: the idea is dead or superseded; it will not come back as-is.
+// Completion is the third terminal verdict (packet-lifecycle-truth-v0 R-003):
+//   - done: the work shipped and its proofs are in — the same audited
+//     mechanism as retirement, so every terminal transition rides one trail.
+// All REQUIRE a reason (R-002): an unreasoned verdict is exactly the silent
+// bookkeeping this module exists to prevent. `active` reopens a terminal packet
+// (also with a reason), so every transition is reversible and auditable.
+//
+// The verdict lives in two places, written together:
+//   - spec.md frontmatter `lifecycle:` — the canonical stamp the status/index
+//     readers already consume;
+//   - a `com.adaptivespec.packet.lifecycle_changed` event carrying {from, to,
+//     reason} — the append-only audit trail (and B1-guarded via appendEvent).
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { appendEvent } from "./packetWrite.js";
+export const VERDICT_STATES = ["parked", "killed", "active", "done"];
+export const RETIRED_LIFECYCLES = new Set(["parked", "killed"]);
+export function isRetired(lifecycle) {
+    return typeof lifecycle === "string" && RETIRED_LIFECYCLES.has(lifecycle);
+}
+// Terminal states end a packet's story: retirement (parked/killed) and
+// completion (done, plus the legacy `built` stamp some packets carry). A
+// terminal header is a recorded disposition, so the lifecycle-truth reader
+// (packet-lifecycle-truth-v0 R-001) never flags it as drift over task math —
+// a parked packet at 0% tasks is a decision, not a contradiction.
+export const TERMINAL_LIFECYCLES = new Set(["parked", "killed", "done", "built"]);
+export function isTerminal(lifecycle) {
+    return typeof lifecycle === "string" && TERMINAL_LIFECYCLES.has(lifecycle);
+}
+export const LIFECYCLE_EVENT_TYPE = "com.adaptivespec.packet.lifecycle_changed";
+// --- Frontmatter restamp -----------------------------------------------------
+// Rewrites only the `lifecycle:` (and `updated:`) lines inside the leading
+// frontmatter block; every other byte of spec.md is preserved. A missing
+// lifecycle line is inserted before the closing delimiter rather than guessed
+// into position.
+function restampFrontmatter(specPath, lifecycle, isoDate) {
+    const text = readFileSync(specPath, "utf8");
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---")
+        throw new Error(`spec.md has no YAML frontmatter to restamp: ${specPath}`);
+    let close = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === "---") {
+            close = i;
+            break;
+        }
+    }
+    if (close === -1)
+        throw new Error(`spec.md frontmatter never closes: ${specPath}`);
+    let from = null;
+    let stamped = false;
+    for (let i = 1; i < close; i += 1) {
+        const m = lines[i].match(/^lifecycle:\s*(\S+)/);
+        if (m) {
+            from = m[1];
+            lines[i] = `lifecycle: ${lifecycle}`;
+            stamped = true;
+        }
+        else if (/^updated:\s*/.test(lines[i])) {
+            lines[i] = `updated: ${isoDate}`;
+        }
+    }
+    if (!stamped) {
+        lines.splice(close, 0, `lifecycle: ${lifecycle}`);
+    }
+    writeFileSync(specPath, lines.join("\n"));
+    return { from };
+}
+export function recordVerdict(options) {
+    if (!VERDICT_STATES.includes(options.state)) {
+        throw new Error(`invalid verdict state: ${options.state} (expected ${VERDICT_STATES.join(" | ")})`);
+    }
+    const reason = options.reason?.trim();
+    if (!reason) {
+        throw new Error(`a ${options.state} verdict requires --reason: the reason is the product record, not decoration`);
+    }
+    const specPath = path.join(options.packetDir, "spec.md");
+    if (!existsSync(specPath) || !existsSync(path.join(options.packetDir, "tasks.yaml"))) {
+        throw new Error(`not a packet directory (missing spec.md or tasks.yaml): ${options.packetDir}`);
+    }
+    const now = options.now ?? new Date();
+    const { from } = restampFrontmatter(specPath, options.state, now.toISOString().slice(0, 10));
+    // Event second: if the stamp threw (bad frontmatter), no ledger line is left
+    // claiming a verdict that spec.md does not carry.
+    const event = appendEvent({
+        packetDir: options.packetDir,
+        type: LIFECYCLE_EVENT_TYPE,
+        data: { from, to: options.state, reason },
+        actor: options.actor,
+        now,
+    });
+    return { event, from, to: options.state };
+}
+// Latest lifecycle_changed event, scanned from the ledger tail. Bounded and
+// skip-on-malformed like every other ledger read; returns null when no verdict
+// event exists (e.g. a hand-stamped frontmatter with no trail).
+export function latestVerdict(packetDir, limit = 500) {
+    const eventsPath = path.join(packetDir, "events.jsonl");
+    if (!existsSync(eventsPath))
+        return null;
+    const lines = readFileSync(eventsPath, "utf8").split(/\r?\n/).filter((l) => l.trim());
+    for (const line of lines.slice(-limit).reverse()) {
+        try {
+            const e = JSON.parse(line);
+            if (e.type !== LIFECYCLE_EVENT_TYPE)
+                continue;
+            const data = (e.data ?? {});
+            return {
+                state: typeof data.to === "string" ? data.to : "unknown",
+                reason: typeof data.reason === "string" ? data.reason : null,
+                at: typeof e.time === "string" ? e.time : null,
+            };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}

package/dist-public/src/packetReconcile.d.ts

@@ -0,0 +1,73 @@
+import { type SourceId } from "./sourceIngress.js";
+export type JsonObject = Record<string, unknown>;
+export type Task = {
+    id: string;
+    agreement: string;
+    status?: string;
+    touches?: string[];
+};
+export type ChangedFileClass = {
+    path: string;
+    state: "agreed" | "unagreed" | "unmapped";
+    mapped_tasks: string[];
+    mapped_task_agreements: Record<string, string>;
+};
+export type ReconcileOptions = {
+    packetDir: string;
+    root: string;
+    changedFiles?: string[];
+    gitDiff?: boolean;
+    taskNoun?: string;
+    jiraEvidencePath?: string;
+};
+export type ReconcileReport = {
+    spec_id: unknown;
+    packet: string;
+    changed_files: Array<{
+        path: string;
+        state: "agreed" | "unagreed" | "unmapped";
+        mapped_tasks: string[];
+        mapped_task_agreements: Record<string, string>;
+    }>;
+    findings: JsonObject[];
+    summary: string;
+    work_system?: JiraWorkSystemReport;
+};
+export declare function parseReconcileArgs(args: string[]): {
+    changedFiles: string[];
+    gitDiff: boolean;
+    jiraEvidencePath?: string;
+};
+export declare function gitChangedFiles(root: string): string[];
+export declare function classifyChangedFiles(tasks: Task[], changedFileInputs: string[], noun?: string): {
+    changed_files: ChangedFileClass[];
+    findings: JsonObject[];
+};
+export type JiraEvidenceFixture = {
+    provider: "jira";
+    site: string;
+    observed_at: string;
+    scope: unknown;
+    issues: Array<{
+        issue: unknown;
+        cites_task?: string;
+    }>;
+};
+export type JiraWorkSystemReport = {
+    source_id: SourceId;
+    site: string;
+    observed_at: string;
+    scope: string;
+    admitted: number;
+    excluded: number;
+    findings: JsonObject[];
+    task_conclusions: JsonObject[];
+};
+export declare const JIRA_STALE_DAYS = 30;
+export declare function jiraWorkSystemReconcile(opts: {
+    packetDir: string;
+    fixture: JiraEvidenceFixture;
+    tasks: Task[];
+}): JiraWorkSystemReport;
+export declare function readJiraEvidenceFixture(root: string, fixturePath: string): JiraEvidenceFixture;
+export declare function reconcilePacket(options: ReconcileOptions): ReconcileReport;