bareloop 0.14.0 → 0.16.0

package/src/codeversion.js

@@ -0,0 +1,155 @@
+// F118 (parked half) — the run→code direction. The commit→run direction
+// (prompt-commit-check's `Failure:` line citing a run id) landed same-day;
+// this is the other half: a run's own spine never recorded which version of
+// bareloop's code it ran under, so a replay could not tell which prompts
+// were in force. Report-only, $0, no shell — same posture as the F117
+// verdictType/model stamp this rides beside (src/run.js:303).
+//
+// NEVER shells out to git: `run` is the one locked verb (hamr's law), and a
+// library growing a shell seam just to read a report field is exactly the
+// kind of capability creep that doctrine exists to block. Everything below
+// is a plain file read of `.git`'s own on-disk layout.
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// this module lives at <pkgRoot>/src/codeversion.js
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * `.git` at a package root can be a FILE, not a directory — `git worktree
+ * add` makes every worktree's own `.git` a one-line pointer file
+ * (`gitdir: <path>`, absolute or relative to the worktree root) at the
+ * per-worktree git dir living under the main checkout's `.git/worktrees/
+ * <name>/` (measured directly: `git worktree add <tmp> HEAD --detach`
+ * against this repo). Resolves that file to the real per-worktree git dir;
+ * returns the plain `.git` directory path unchanged when it already is one,
+ * and `null` when `.git` is absent (an npm install) or the pointer file
+ * can't be read/parsed.
+ * @param {string} pkgRoot
+ * @returns {string|null}
+ */
+function resolveGitDir(pkgRoot) {
+  const dotGit = join(pkgRoot, '.git');
+  if (!existsSync(dotGit)) return null;
+  const st = statSync(dotGit);
+  if (st.isDirectory()) return dotGit;
+  if (!st.isFile()) return null;
+  const contents = readFileSync(dotGit, 'utf8').trim();
+  const m = /^gitdir:\s*(.+)$/.exec(contents);
+  if (!m) return null;
+  const target = m[1].trim();
+  return target.startsWith('/') ? target : join(pkgRoot, target);
+}
+
+/**
+ * A worktree's own git dir (from {@link resolveGitDir}) holds HEAD but never
+ * refs — branches/`packed-refs` are shared, and live in the MAIN checkout's
+ * `.git`, whose path is this worktree git dir's own `commondir` file (one
+ * line, a path RELATIVE TO THIS GIT DIR — measured directly: this repo's own
+ * worktree fixture wrote `../..`, which from `.git/worktrees/<name>/`
+ * resolves back to the repo's real `.git`). A normal (non-worktree) git dir
+ * carries no `commondir` file at all and IS already the common dir.
+ * @param {string} gitDir
+ * @returns {string}
+ */
+function resolveCommonDir(gitDir) {
+  const commondirPath = join(gitDir, 'commondir');
+  if (!existsSync(commondirPath)) return gitDir;
+  try {
+    const rel = readFileSync(commondirPath, 'utf8').trim();
+    if (!rel) return gitDir;
+    return rel.startsWith('/') ? rel : join(gitDir, rel);
+  } catch {
+    return gitDir;
+  }
+}
+
+/**
+ * Resolve a ref name (e.g. "refs/heads/main") to a sha by reading the loose
+ * ref file, falling back to `packed-refs` when the branch has been packed
+ * (measured: this repo's own `.git/packed-refs` carries `main` but not every
+ * branch — a loose ref can legitimately be absent while the branch is real).
+ * @param {string} gitDir
+ * @param {string} refName
+ * @returns {string|null}
+ */
+function resolveRef(gitDir, refName) {
+  const loose = join(gitDir, refName);
+  if (existsSync(loose)) {
+    try {
+      const sha = readFileSync(loose, 'utf8').trim();
+      return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+    } catch {
+      return null;
+    }
+  }
+  const packed = join(gitDir, 'packed-refs');
+  if (!existsSync(packed)) return null;
+  try {
+    const lines = readFileSync(packed, 'utf8').split('\n');
+    for (const line of lines) {
+      if (line.startsWith('#')) continue;
+      const [sha, ref] = line.trim().split(' ');
+      if (ref === refName && sha && /^[0-9a-f]{40}$/.test(sha)) return sha;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Report-only stamp of the bareloop code this process is running as. Never
+ * throws — an unreadable package.json or absent `.git` reads as `null`,
+ * honestly, rather than crashing a caller over a report field.
+ * @returns {{ version: string|null, sha: string|null, dirty: null }}
+ */
+export function codeVersion() {
+  let version = null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+    version = typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    version = null;
+  }
+
+  let sha = null;
+  try {
+    // only a dev checkout carries a `.git` at all (directory OR the
+    // `gitdir:` pointer file a worktree checkout leaves instead) — an
+    // npm-installed copy has neither, and this reads that absence as
+    // "unknown", never fakes one
+    const gitDir = resolveGitDir(PKG_ROOT);
+    if (gitDir !== null) {
+      const headPath = join(gitDir, 'HEAD');
+      const head = readFileSync(headPath, 'utf8').trim();
+      const m = /^ref:\s*(\S+)$/.exec(head);
+      if (m) {
+        // branches/packed-refs are shared across worktrees and live in the
+        // COMMON git dir, never the per-worktree one HEAD itself came from
+        sha = resolveRef(resolveCommonDir(gitDir), m[1]);
+      } else if (/^[0-9a-f]{40}$/.test(head)) {
+        // detached HEAD: a bare 40-hex sha directly in the file
+        sha = head;
+      }
+    }
+  } catch {
+    sha = null;
+  }
+
+  // dirty: uncommitted-changes state cannot be known without a shell
+  // (`git status`/`git diff`) — reported as unknown, never faked as false.
+  return { version, sha, dirty: null };
+}
+
+/**
+ * First 8 characters of a sha, or null. Mirrors the short-sha convention
+ * `replay.js` already uses for `specHash` (`s.specHash.slice(0, 8)`).
+ * @param {string|null|undefined} sha
+ * @returns {string|null}
+ */
+export function shortSha(sha) {
+  return typeof sha === 'string' && sha.length > 0 ? sha.slice(0, 8) : null;
+}

package/src/index.js

@@ -233,6 +233,12 @@ export { closeStagesOf } from './plan.js';
 // writes nothing to the spine; `runBehaviour` computes, `formatBehaviour`
 // renders the printable block.
 export { runBehaviour, formatBehaviour } from './behaviour.js';
+// PRD build-list item 6 — generic run replay: point it at a run's spine (+
+// its gate-audit sidecar) and get the whole story back as one object
+// (`replayRun`) or one printable page (`formatReplay`). Reads only, mints no
+// verdict, writes nothing to the spine — reuses `runBehaviour` rather than
+// re-implementing the tool-call count.
+export { replayRun, formatReplay } from './replay.js';
 // M4b — the interview, the refusal, the composition, and D9's three gates.
 // `prepareSigning` returns the resolved spec's HASH and the seed evidence; it
 // never signs — the approvals array and the human's word are unchanged.
@@ -240,3 +246,9 @@ export {
   runInterview, authorCloseForJob, assembleSpec, prepareSigning, refusalEvents, refuseLockedKind,
   GENRE, REFUSAL_LIB, REFUSAL_CATEGORY, AUTHORED_SPEC_FIELDS,
 } from './authorjob.js';
+// PRD build-list item 5 (TODO #8) — the prompt-register inventory: every file
+// known to carry model-facing prompt/instruction text, and the predicate a
+// commit-message check (`scripts/prompt-commit-check.mjs`) uses to decide
+// whether a changed file is one. The ONE place this list lives; exported so
+// bareloop.context.md can point an adopter here instead of re-deriving it.
+export { PROMPT_REGISTERS, isPromptFile } from './promptregisters.js';

package/src/ledger.js

@@ -479,7 +479,7 @@ export function rateProvenance(record) {
  * Re-spelled rather than imported (src/run.js imports this module's siblings and a cycle
  * buys nothing here) — `tests/ledger.test.js` asserts the two spellings agree, because a
  * spend-slicing instrument that misses a writer is the F45 class this list exists to avoid. */
-const SPEND_RECORD_TYPES = Object.freeze(['worker-round', 'judge-round', 'worker-turn']);
+export const SPEND_RECORD_TYPES = Object.freeze(['worker-round', 'judge-round', 'worker-turn']);
 
 /** @typedef {{rounds: number, usd: number, unpricedRounds: number}} ProvenanceBucket */
 

package/src/promptregisters.js

@@ -0,0 +1,93 @@
+// THE PROMPT REGISTER INVENTORY — build-list item 5 (PRD TODO #8), Q9 answered
+// (hamr, 2026-08-25): "a check". A commit that changes a prompt register must
+// say, in its message, the failure that caused the change, what it addresses,
+// and what it corrects — doctrine already stated once ("a frozen rule without
+// a wired detector is prose", docs/product/2026-08-23-agreed-build-list.md:187-189)
+// so convention-only was rejected. This module is the ONE place that inventory
+// lives: `scripts/prompt-commit-check.mjs` reads it to decide which commits the
+// rule applies to, and this file's own doc-comment is where a human reads it.
+//
+// The inventory is FILE-scoped, not const-scoped. Several of the files below
+// hold more than one named prompt const, and at least two (authorscout.js,
+// cardauthor.js) also build a model-facing prompt INLINE inside a function
+// (template literals, not a top-level const) rather than assembling one from a
+// named export. A const-scoped check would silently miss those; a file-scoped
+// one does not, because the whole file is in scope once it appears here. The
+// `name` field on each entry is documentation only — grepped to the byte range
+// that motivated it — and carries no weight in `isPromptFile`.
+//
+// Verified against source 2026-08-25 (grepped for exported/module-level string
+// consts that read as model-facing instruction text, and separately for inline
+// template-literal prompts built inside a function). Files checked and found to
+// carry NO prompt content: src/plan.js, src/validate.js, src/kinds.js,
+// src/text.js, src/declaredclose.js, src/calibrate.js, src/index.js (the last
+// is the barrel export only).
+
+/**
+ * One entry in the prompt-register inventory: a file known to carry
+ * model-facing prompt/instruction text, and the name(s) that live there for a
+ * human reading this file. `name` may point at a named const OR at a function
+ * that builds a prompt inline (e.g. `scoutPrompt()`) — the check only ever
+ * keys on `file`.
+ * @typedef {{file: string, name: string}} PromptRegisterEntry
+ */
+
+/** @type {ReadonlyArray<PromptRegisterEntry>} */
+export const PROMPT_REGISTERS = Object.freeze([
+  // src/authorscout.js — the read-only repo-survey scout that opens authoring
+  Object.freeze({ file: 'src/authorscout.js', name: 'SCOUT_SYSTEM' }),
+  Object.freeze({ file: 'src/authorscout.js', name: 'SCOUT_RECOVERY_PROMPT' }),
+  Object.freeze({ file: 'src/authorscout.js', name: 'scoutPrompt() (inline template, not a const)' }),
+
+  // src/authorflow.js — the declaration-authoring turn (system + revise/re-ask)
+  Object.freeze({ file: 'src/authorflow.js', name: 'AUTHOR_SYSTEM' }),
+  Object.freeze({ file: 'src/authorflow.js', name: 'REVISE_INSTRUCTION' }),
+  Object.freeze({ file: 'src/authorflow.js', name: 'STRUCTURE_INSTRUCTION_TOOL' }),
+  Object.freeze({ file: 'src/authorflow.js', name: 'STRUCTURE_INSTRUCTION_TEXT' }),
+
+  // src/judged.js — the softgreen judge's locate prompt (spine + per-rule asks)
+  Object.freeze({ file: 'src/judged.js', name: 'PROMPT_HEAD' }),
+  Object.freeze({ file: 'src/judged.js', name: 'PROMPT_TAIL' }),
+  Object.freeze({ file: 'src/judged.js', name: 'JUDGE_RULES[*].ask (per-rule fragments)' }),
+  Object.freeze({ file: 'src/judged.js', name: 'locatePrompt() (inline template, not a const)' }),
+
+  // src/cardauthor.js — compiles a person's own words into a judged rubric
+  Object.freeze({ file: 'src/cardauthor.js', name: 'COMPILE_SYSTEM' }),
+  Object.freeze({ file: 'src/cardauthor.js', name: 'cardCasesPrompt() (inline template, not a const)' }),
+
+  // src/readshim.js — the capped/deduplicating read shim's worker-facing strategy
+  Object.freeze({ file: 'src/readshim.js', name: 'READ_SHIM_STRATEGY' }),
+  Object.freeze({ file: 'src/readshim.js', name: 'READ_SHIM_DIFF_STRATEGY' }),
+
+  // src/tools.js — the worker tool menu: personas, retrieval/edit/component strategy
+  Object.freeze({ file: 'src/tools.js', name: 'PERSONA_TOOLS' }),
+  Object.freeze({ file: 'src/tools.js', name: 'RETRIEVAL_STRATEGY' }),
+  Object.freeze({ file: 'src/tools.js', name: 'EDIT_STRATEGY' }),
+  Object.freeze({ file: 'src/tools.js', name: 'COMPONENT_STRATEGIES' }),
+  Object.freeze({ file: 'src/tools.js', name: 'strategyFor() (assembles per-grant strategy prose)' }),
+  Object.freeze({ file: 'src/tools.js', name: 'LINE_SPACE (module-private, not exported)' }),
+  Object.freeze({ file: 'src/tools.js', name: 'PERSONA (module-private, not exported, currently unreferenced)' }),
+
+  // src/planrun.js — the native-surface read-truncation strategy line
+  Object.freeze({ file: 'src/planrun.js', name: 'NATIVE_READ_STRATEGY' }),
+]);
+
+/** The distinct file paths carrying prompt registers, repo-root-relative with
+ * forward slashes — derived from `PROMPT_REGISTERS` so the set can never drift
+ * from the entries above. @type {ReadonlySet<string>} */
+const PROMPT_FILES = new Set(PROMPT_REGISTERS.map((e) => e.file));
+
+/**
+ * True when `path` names one of the inventoried prompt-register files. Accepts
+ * either a repo-root-relative path (`src/tools.js`) or an absolute/relative
+ * path ending in one (`/home/x/bareloop/src/tools.js`, `./src/tools.js`) — git
+ * hands the check root-relative paths, but a caller working from an absolute
+ * path should not have to strip the prefix itself.
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isPromptFile(path) {
+  if (typeof path !== 'string' || path === '') return false;
+  const normalized = path.replace(/\\/g, '/');
+  return [...PROMPT_FILES].some((f) => normalized === f || normalized.endsWith(`/${f}`));
+}