autonomous-sdlc-harness 0.2.0 → 0.4.1

package/dist/retrieval/runtime.js

@@ -1,7 +1,8 @@
 /**
  * How the docs-retrieval packages reach this CLI: the optional peer set, the machine cache paths the
  * runtime installation and the model weights live at, the one predicate for "is the runtime
- * installed?", the loader and the entry resolver.
+ * installed?", the predicate for which peers this installation cannot resolve from its own location,
+ * the loader and the entry resolver.
  *
  * **The rule this module exists to enforce: a retrieval package is loaded only by a dynamic `import()`
  * in this module, and only on a path that retrieves.** The packages are optional peers
@@ -15,12 +16,17 @@
  * location. So `init` installs the peers and this CLI, at its own version, into
  * {@link retrievalRuntimeDir}, and nothing in this package resolves a peer against a second base.
  *
- * **The declared mirror.** `cli/templates/scripts/docs-search-server.sh` is the one mirror of three
- * literals this module owns — {@link RETRIEVAL_CACHE_DIRNAME}, {@link RETRIEVAL_RUNTIME_DIRNAME} and
- * {@link RUNTIME_CLI_RELATIVE} — spelled there as the path
- * `$(hr_cache_dir)/retrieval/runtime/node_modules/autonomous-sdlc-harness/dist/cli.js`, which it
- * `exec`s. `hr_cache_dir` itself mirrors `machineCacheDir()`, declared in `machine/paths.ts` →
- * choice 2. A change to any of the three literals is an edit to that script in the same change; a
+ * **The declared mirrors.** Two files outside the package spell literals this module owns:
+ * - `cli/templates/scripts/docs-search-server.sh` mirrors all three — {@link RETRIEVAL_CACHE_DIRNAME},
+ *   {@link RETRIEVAL_RUNTIME_DIRNAME} and {@link RUNTIME_CLI_RELATIVE} — as the path
+ *   `$(hr_cache_dir)/retrieval/runtime/node_modules/autonomous-sdlc-harness/dist/cli.js`, which it
+ *   `exec`s. `hr_cache_dir` itself mirrors `machineCacheDir()`, declared in `machine/paths.ts` →
+ *   choice 2.
+ * - `cli/templates/github/workflows/harness-run.yml` mirrors {@link RETRIEVAL_CACHE_DIRNAME} in the
+ *   `actions/cache` path `${XDG_CACHE_HOME:-$HOME/.cache}/autonomous-sdlc-harness/retrieval`, in both
+ *   the `run` and the `warm` job; its prefix mirrors `machineCacheDir()`, declared in the same choice.
+ *
+ * A change to a mirrored literal is an edit to every file that mirrors it, in the same change; a
  * mirror this header does not declare is a defect (`.claude/context/conventions.md` →
  * `## Configuration is the source of truth…`, the persisted-key bullet).
  */
@@ -28,7 +34,7 @@ import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { HarnessError, internal } from '../core/errors.js';
 import { isJsonObject, readJsonFile } from '../core/json.js';
-import { packageRoot } from '../core/paths.js';
+import { ownManifest, ownManifestString, packageRoot } from '../core/paths.js';
 import { machineCacheDir } from '../machine/paths.js';
 /** The directory under `machineCacheDir()` every retrieval artifact lives in. */
 export const RETRIEVAL_CACHE_DIRNAME = 'retrieval';
@@ -48,21 +54,6 @@ export function retrievalRuntimeDir() {
 export function retrievalModelCacheDir() {
     return join(machineCacheDir(), RETRIEVAL_CACHE_DIRNAME, RETRIEVAL_MODELS_DIRNAME);
 }
-/** This package's own manifest, which a packaging fault alone can make unreadable. */
-function ownManifest() {
-    const manifestPath = join(packageRoot(), 'package.json');
-    const manifest = readJsonFile(manifestPath);
-    if (!isJsonObject(manifest))
-        throw internal(`this CLI's own manifest could not be read at ${manifestPath}`);
-    return manifest;
-}
-/** A string field of this package's own manifest. */
-export function ownManifestString(key) {
-    const value = ownManifest()[key];
-    if (typeof value !== 'string' || value === '')
-        throw internal(`this CLI's own manifest carries no ${key}`);
-    return value;
-}
 /**
  * Every `peerDependencies` entry of this package's own manifest whose `peerDependenciesMeta` marks it
  * optional. The manifest is the single declaration of the set; no package name is typed here.
@@ -140,6 +131,37 @@ export async function loadRetrievalModule(specifier) {
         throw new HarnessError(`docs retrieval needs the optional package ${name}, which this installation cannot load. Run \`npx autonomous-sdlc-harness init\` in a repository with docs.retrieval on: it installs the package into ${retrievalRuntimeDir()}, and the retrieval commands run from that installation`);
     }
 }
+/**
+ * The name of every {@link retrievalPeers} entry `import.meta.resolve` throws on, in manifest order.
+ * Any throw counts — a missing module, a package-path error, a resolve hook's refusal. It resolves
+ * and loads nothing.
+ *
+ * It resolves from this module's own location, the base {@link loadRetrievalModule}'s `import()`
+ * resolves from, so an empty answer means the loader finds every peer.
+ *
+ * It is **not** the answer to "is the runtime installed?" — that is {@link retrievalRuntimeState}'s,
+ * and `doctor`'s `retrieval-dependencies` deliberately does not consult this one
+ * (`cli/src/doctor/checks.ts` → `RETRIEVAL_DEPENDENCIES_CHECK`'s doc comment).
+ *
+ * Call it only on a retrieval path: a resolve hook sees `import.meta.resolve` too.
+ *
+ * Consumers: {@link retrievalCliEntry} and, outside the package, the docs-retrieval eval's refusal —
+ * `evals/docs-retrieval/index-build.mjs` → `assertRealModelsAreAvailable` and
+ * `evals/docs-retrieval/check-floor.mjs` → `checkFloor`.
+ */
+export function unresolvedRetrievalPeers() {
+    return retrievalPeers()
+        .filter(({ name }) => {
+        try {
+            import.meta.resolve(name);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    })
+        .map(({ name }) => name);
+}
 /**
  * The CLI entry a non-serving retrieval child process runs: this installation's `dist/cli.js` when
  * `import.meta.resolve` succeeds for every peer (resolution only), otherwise the runtime's entry when
@@ -154,16 +176,7 @@ export async function loadRetrievalModule(specifier) {
  * `retrieval-index` probe).
  */
 export function retrievalCliEntry() {
-    const resolvesHere = retrievalPeers().every(({ name }) => {
-        try {
-            import.meta.resolve(name);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    });
-    if (resolvesHere)
+    if (unresolvedRetrievalPeers().length === 0)
         return { entry: join(packageRoot(), 'dist', 'cli.js'), source: 'this-installation' };
     const runtimeEntry = join(retrievalRuntimeDir(), RUNTIME_CLI_RELATIVE);
     return existsSync(runtimeEntry) ? { entry: runtimeEntry, source: RETRIEVAL_RUNTIME_DIRNAME } : undefined;

package/dist/retrieval/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/retrieval/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,iFAAiF;AACjF,MAAM,CAAC,MAAM,uBAAuB,GAAG,WAAW,CAAC;AAEnD,kFAAkF;AAClF,MAAM,CAAC,MAAM,yBAAyB,GAAG,SAAS,CAAC;AAEnD,0EAA0E;AAC1E,MAAM,wBAAwB,GAAG,QAAQ,CAAC;AAE1C,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG,kDAAkD,CAAC;AAEvF,gFAAgF;AAChF,MAAM,4BAA4B,GAAG,OAAO,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC;AAE5E,8FAA8F;AAC9F,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,CAAC,eAAe,EAAE,EAAE,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AACrF,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,CAAC,eAAe,EAAE,EAAE,uBAAuB,EAAE,wBAAwB,CAAC,CAAC;AACpF,CAAC;AAED,sFAAsF;AACtF,SAAS,WAAW;IAClB,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC5C,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC;QAAE,MAAM,QAAQ,CAAC,gDAAgD,YAAY,EAAE,CAAC,CAAC;IAC5G,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,iBAAiB,CAAC,GAAuB;IACvD,MAAM,KAAK,GAAG,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE;QAAE,MAAM,QAAQ,CAAC,sCAAsC,GAAG,EAAE,CAAC,CAAC;IAC3G,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IAC9C,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACzB,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1D,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAC3D,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,+FAA+F;AAC/F,SAAS,iBAAiB,CAAC,OAAe;IACxC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,4BAA4B,EAAE,cAAc,CAAC,CAAC,CAAC;QAC3F,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IACtC,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,IAAI,OAAO,KAAK,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;QACjG,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,cAAc,EAAE,EAAE,CAAC;QACxC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC/D,CAAC;AAED,iGAAiG;AACjG,SAAS,SAAS,CAAC,SAAiB;IAClC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAI,SAAiB;IAC5D,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACzD,MAAM,QAAQ,CAAC,qCAAqC,SAAS,2CAA2C,CAAC,CAAC;IAC5G,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAM,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAAsC,EAAE,IAAI,KAAK,sBAAsB;YAAE,MAAM,KAAK,CAAC;QAC1F,MAAM,IAAI,YAAY,CACpB,6CAA6C,IAAI,wJAAwJ,mBAAmB,EAAE,yDAAyD,CACxR,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB;IAG/B,MAAM,YAAY,GAAG,cAAc,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE;QACvD,IAAI,CAAC;YACH,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC,CAAC,CAAC;IACH,IAAI,YAAY;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACvG,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,EAAE,EAAE,oBAAoB,CAAC,CAAC;IACvE,OAAO,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3G,CAAC"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/retrieval/runtime.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/search.js

@@ -4,11 +4,13 @@
  * both read.
  *
  * **The rule this module exists to enforce: only `fused-rerank` abstains, and only below
- * {@link ABSTAIN_SCORE_THRESHOLD}, calibrated against the measured reranker distribution** — that
+ * {@link ABSTAIN_SCORE_THRESHOLD}** — that
  * constant's own doc comment carries the value and points at the record of how it was chosen. The
  * reranker's score is the one this module treats as calibrated; the `lexical`, `vector` and `fused`
- * scores are rank-derived and uncalibrated, so those modes never abstain. Every store access goes
- * through the {@link DocStore} methods; this module holds no SQL.
+ * scores are rank-derived and uncalibrated, so those modes never abstain. The score abstention tests
+ * is reported on the result whether or not it abstained, so the calibration can observe the
+ * distribution it cuts. Every store access goes through the {@link DocStore} methods; this module
+ * holds no SQL.
  */
 import { HarnessError } from '../core/errors.js';
 /** The reciprocal-rank-fusion constant: a hit at rank `r` contributes `1 / (RRF_K + r)`. */
@@ -24,9 +26,9 @@ export const MAX_RESULTS = 20;
 /** The snippet length, before the `...` a cut appends. */
 const SNIPPET_CHARS = 240;
 /**
- * The best reranker score below which `fused-rerank` abstains, calibrated at `0.32` against the real
- * reranker's measured score distribution; `docs/retrieval-eval-results.md` → `## Threshold
- * calibration` holds how that value was chosen and on what, and is the only record of it.
+ * The best reranker score below which `fused-rerank` abstains. `docs/retrieval-eval-results.md` →
+ * `## Threshold calibration` holds how the value was chosen, the observed distributions it was
+ * re-tested on and what it costs, and is the only record of it.
  *
  * This module's own suite bounds the value from outside: the abstention cases of
  * `cli/test/docs-retrieval.test.mjs` run under the `stub-overlap` reranker, which scores a matching
@@ -71,6 +73,7 @@ function hitOf(chunk, score) {
  * Answers `query` in `mode`. `k` is clamped to `[1, MAX_RESULTS]`; an empty or whitespace-only query
  * is refused. Only `fused-rerank` abstains — on no candidates, or a best reranker score below
  * {@link ABSTAIN_SCORE_THRESHOLD}; the other modes' scores are uncalibrated and never abstain.
+ * `bestRerankScore` carries the score that comparison read, abstention or not, and no renderer reads it.
  */
 export async function searchDocs(options) {
     const { store, embedder, reranker, query, mode } = options;
@@ -86,19 +89,27 @@ export async function searchDocs(options) {
     if (mode !== 'fused-rerank') {
         const top = fused.slice(0, k);
         const chunks = await store.getChunks(top.map(([id]) => id));
-        return { abstained: false, hits: chunks.map((chunk) => hitOf(chunk, scores.get(chunk.id) ?? 0)) };
+        return {
+            abstained: false,
+            hits: chunks.map((chunk) => hitOf(chunk, scores.get(chunk.id) ?? 0)),
+            bestRerankScore: null,
+        };
     }
     const candidates = await store.getChunks(fused.slice(0, RERANK_CANDIDATES).map(([id]) => id));
     if (candidates.length === 0)
-        return { abstained: true, hits: [] };
+        return { abstained: true, hits: [], bestRerankScore: null };
     const rerankScores = await reranker.score(query, candidates.map((chunk) => (chunk.heading === '' ? chunk.body : `${chunk.heading}\n${chunk.body}`)));
     const reranked = candidates
         .map((chunk, index) => ({ chunk, score: rerankScores[index] ?? 0 }))
         .sort((a, b) => b.score - a.score);
     const best = reranked[0]?.score ?? 0;
     if (best < ABSTAIN_SCORE_THRESHOLD)
-        return { abstained: true, hits: [] };
-    return { abstained: false, hits: reranked.slice(0, k).map(({ chunk, score }) => hitOf(chunk, score)) };
+        return { abstained: true, hits: [], bestRerankScore: best };
+    return {
+        abstained: false,
+        hits: reranked.slice(0, k).map(({ chunk, score }) => hitOf(chunk, score)),
+        bestRerankScore: best,
+    };
 }
 /**
  * {@link ABSTAIN_MESSAGE} alone on an abstention; otherwise two lines per hit, `n. ref (score s)` and

package/dist/retrieval/search.js.map

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

package/dist/retrieval/server.js

@@ -4,7 +4,7 @@
  *
  * **The rule this module exists to enforce: the server's name, its tool's name and the permission
  * string built from them are a wire.** `plugin/agents/*.md` quotes {@link SEARCH_TOOL_PERMISSION} in
- * ten `tools:` allowlists, and the two CLI templates that register the server for an adopter carry
+ * eleven `tools:` allowlists, and the two CLI templates that register the server for an adopter carry
  * {@link DOCS_SERVER_NAME}, so renaming any of the three is an edit to every one of those files.
  *
  * **The tool's output is document text**, which an agent must treat as untrusted data rather than as

package/dist/retrieval/setup.js

@@ -23,8 +23,9 @@
 import { execFileSync } from 'node:child_process';
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { ownManifestString } from '../core/paths.js';
 import { modelFilesPresent, RETRIEVAL_STUB_ENV, stubModelsSelected } from './models.js';
-import { ownManifestString, retrievalCliEntry, retrievalModelCacheDir, retrievalPeers, retrievalRuntimeDir, retrievalRuntimeState, RUNTIME_CLI_RELATIVE, } from './runtime.js';
+import { retrievalCliEntry, retrievalModelCacheDir, retrievalPeers, retrievalRuntimeDir, retrievalRuntimeState, RUNTIME_CLI_RELATIVE, } from './runtime.js';
 /** Both child processes may take minutes on a cold cache. */
 const STEP_TIMEOUT_MS = 900000;
 const REMEDY = 're-run `npx autonomous-sdlc-harness init`; `npx autonomous-sdlc-harness doctor` reports what is missing';

package/dist/retrieval/setup.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autonomous-sdlc-harness",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "The outer loop of the autonomous SDLC harness: init, doctor, config and daemon management for the harness Claude Code plugin, plus opt-in local docs retrieval.",
   "license": "Apache-2.0",
   "author": "firu-daniel",
@@ -13,7 +13,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "pretest": "npm run build",
-    "test": "node --test",
+    "test": "node --test --test-timeout=1800000",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {

package/templates/README.md

@@ -9,7 +9,8 @@ The generator templates `init` copies into an adopted repository. Nothing here i
 | `githooks/` | the configured `githooksDir` |
 | `scripts/` | the configured `scriptsDir` |
 | `state-dir/` | the configured `stateDir` |
+| `github/` | `.github/` in the adopter's repo — `workflows/harness-run.yml` and `workflows/harness-resume.yml`, written only when `execution.target` is `github-actions` |
 
-**Naming rule for the whole tree: a template whose adopter-side name begins with a dot is stored here without the dot.** `repo/gitignore` is written as `.gitignore`, `repo/mcp.json` as `.mcp.json`, and the `claude/` subtree lands at `.claude/`; `init` adds the dot when it writes. The rule is load-bearing twice over — a real `.gitignore` inside this repository would be honoured by git and could silently exclude files that are meant to ship, and npm rewrites a packaged `.gitignore` to `.npmignore` on publish, so a dot-named template does not survive the wire.
+**Naming rule for the whole tree: a template whose adopter-side name begins with a dot is stored here without the dot.** `repo/gitignore` is written as `.gitignore`, `repo/mcp.json` as `.mcp.json`, and the `claude/` subtree lands at `.claude/` and the `github/` subtree at `.github/`; `init` adds the dot when it writes. The rule is load-bearing twice over — a real `.gitignore` inside this repository would be honoured by git and could silently exclude files that are meant to ship, and npm rewrites a packaged `.gitignore` to `.npmignore` on publish, so a dot-named template does not survive the wire.
 
-A template whose adopter-side home is none of the five above is new information for the item that adds it: give it a sixth subdirectory rather than forcing it into one of these.
+A template whose adopter-side home is none of the six above is new information for the item that adds it: give it a seventh subdirectory rather than forcing it into one of these.

package/templates/claude/context/conventions.md

@@ -10,7 +10,7 @@
 - How a change flows through those layers, and which direction a dependency is allowed to point.
 - The order files are created in when a feature is added, so a half-built feature is still a coherent tree.
 - Where a new responsibility goes when it fits no file that already exists.
-- Logging, error handling, and the testing bar a change clears before it counts as done.
+- Logging, error handling, and the testing bar a change clears before it counts as done — including **the one command that runs a single test file on its own**, or the statement that this project has none. The harness runs the full test command once per Run gates phase, never per change, so a unit that wrote a test runs only that file, through this command. Where the test wrapper's line accepts a path, `bash <scriptsDir>/test.sh <file>` is the command to name, because it is already allow-listed.
 - **The commit-message policy**, which is the whole of what the committer agent reads from this document: the subject-prefix vocabulary a caller draws its prefix from, whether the first word after the prefix is capitalized, the subject-length cap, the fixed-form subjects the flow emits, and the attribution-trailer policy: whether a trailer naming the agent as an author is required, forbidden or optional. The harness takes no position on that trailer, because the rule is actively reversed between projects: some forbid one outright, others require it on every agent-assisted commit, and unanswered here it has no default to fall back on. **The fixed-form subjects are derived here, never copied from a list** — run ``grep -rnE '(chore|feat|fix|refactor|docs|test): [A-Za-z][^"'"'"'`]*(<branch>|\$branch|\$\{branch\}|<entry-id>|K passing)' "${CLAUDE_PLUGIN_ROOT}" <scripts_dir>``, substituting `<scripts_dir>` with this repository's `scriptsDir` value from `harness.config.json` before running it, and write the policy so that **every** subject that command emits is exempt from the capitalisation rule and from the subject-length cap — **minus two classes the probe reaches but no commit point owns**: a subject the surrounding text tells the flow **not** to emit (its own line says it is forbidden), and a subject quoted as a worked example by a guard, a verification document or a prose restatement of another home's string. A subject with no emitting home is not a fixed form; check the line the probe emitted before exempting it. Each exempted subject is passed byte-for-byte by the commit point that owns it, so a policy that re-cases or truncates one breaks that commit point. `review_plan_file` and `ui_test_pass` are the committer's own commit modes and the dispatching flow files quote both, so changing either one is a two-file edit; the flow's other commit points own theirs the same way. The probe reaches **branch-scoped** subjects only — its alternation requires a `<branch>` / `$branch` / `${branch}` / `<entry-id>` / `K passing` token — so a fixed subject carrying none of them falls outside it, and widening the probe is part of the cost of adding one. **Per commit class, which prefix a commit of that class takes** — the vocabulary above names the set, this names the selection, and a policy giving only the set leaves a caller nothing to read: answer it for every class the flows commit in, at minimum a commit **fixing existing work**, the class the review-fix loops commit in, and a commit **adding new work**, the class a story task's commit falls in; and answer as well whether **any class carries no prefix at all, and which class that is**, which is what the committer's `commit_prefix` argument spells as the literal `none`. Designate by class and never by file kind — the classes are the flows', the tokens are yours.
 - **How this project stays in step with its reference implementation, if it has one** — which behaviour must match it exactly, which parts may deviate and why, and how a review finding cites the source it compared against. A project with a single implementation says so here and leaves `phases.parity` off; the section is optional, not missing.
 

package/templates/claude/context/layer.md

@@ -9,7 +9,7 @@
 - What this layer is responsible for and — just as usefully — what it is not, so a task that has drifted into it is recognisable.
 - What it may depend on, and which direction a dependency between layers is allowed to point.
 - Naming and file-layout rules that apply inside it.
-- What "done" means here: the tests to write, the checks to run, the bar a review holds the change to.
+- What "done" means here: the tests to write, the checks to run, the bar a review holds the change to — including **the one command that runs a single test file of this layer on its own**, or the statement that this layer has none. The harness runs the full test command once per Run gates phase, never per change, so a unit that wrote a test runs only that file, through this command. Where the test wrapper's line accepts a path, `bash <scriptsDir>/test.sh <file>` is the command to name, because it is already allow-listed.
 
 **One generic example — the shape a rule takes here**
 

package/templates/claude/push-notify.env.example

@@ -12,8 +12,13 @@
 # carrying settings over from an earlier runner, rename the keys — the reader recognises
 # these spellings and no others.
 
-# Where a run posts its notifications: any endpoint that accepts an HTTP POST.
-# Leave it empty to send none.
+# Where a run posts its notifications: the full http:// or https:// URL of any endpoint
+# that accepts an HTTP POST. Leave it empty to send none.
+# For ntfy with no server of your own: install the ntfy app, create a topic there and
+# write https://ntfy.sh/<your-topic> here. The topic name works like a password —
+# anyone who knows it can read and send these notifications.
+# This file is sourced by a shell, so a URL containing shell characters such as `&`
+# must be single-quoted: HARNESS_PUSH_URL='https://…?a=1&b=2'.
 HARNESS_PUSH_URL=
 
 # Optional. A local command run in addition to the POST — a desktop notifier, a chat

package/templates/claude/settings.autonomous.json

@@ -7,7 +7,7 @@
     "ONE COMMAND PER ENTRY, NEVER A COMPOUND: a single `mkdir && cp && rm` block is refused where each of those commands succeeds on its own, because the joined string matches no entry. Keep every entry a single command.",
     "THE CHECKOUT AND ITS SIBLING WORKTREES BOTH: every file glob and every wrapper path is listed for {{repoRoot}} and for the sibling pattern {{worktreeGlob}} under {{workRoot}}. A run in a second working copy that matches neither does not fail loudly - it silently skips whatever phase needed the path. A single-checkout repository simply has no sibling for the second entry to match, which costs nothing.",
     "EVERY WRAPPER IN {{scriptsDir}} IS LISTED IN ALL THREE FORMS A CALLER MAY USE: the repo-relative invocation `commands.*` holds and an agent runs verbatim from the repository root, its repo-root-absolute twin for a caller that resolves the path first, and its sibling-worktree twin. Listing only one form leaves the other two matching neither `allow` nor `deny`, which is the stall this profile exists to prevent. THE DEPLOY WRAPPER IS ONE OF THEM, SO ITS THREE FORMS ARE IN `allow` HERE AND AGAIN IN `ask` BELOW: `ask` is evaluated before `allow` and returns first, so the ask is what a deploy hits and the allow rows never decide it. Deleting the `ask` deploy rows as duplicates therefore leaves a deploy an unattended run makes on its own - remove deploy from both blocks or from neither.",
-    "THE OUTER-LOOP SCRIPTS AN AGENT RUNS ARE LISTED THE SAME THREE WAYS, AND THE REST GET NOTHING: `autonomous-sdlc-harness init` writes a second family of scripts into {{scriptsDir}} whose bodies ship fixed and read `harness.config.json` at run time rather than carrying a command line of yours. Only the ones a dispatched agent is itself the thing that runs are listed here, and they are in `allow` rather than `ask` because they sit on the unattended commit path, where an `ask` is evaluated first and parks the run with nothing to answer it. The run watcher, the worktree tooling and the cleanup sweep are started by the watcher process or by you, and they carry no entry on purpose: one would hand a dispatched agent a path to a branch deletion or a daemon restart. The docs-retrieval server launcher carries no entry either, for a different reason: the agent runner starts it from `.mcp.json` when docs.retrieval is on, never a dispatched agent's Bash call, and the one tool it serves, `search_docs` on the `harness-docs` server, is granted by the retrieval fragment's entry for it instead. Adding an entry for one of them is a decision to let an agent run it - make it deliberately, in the same three forms as everything else here.",
+    "THE OUTER-LOOP SCRIPTS AN AGENT RUNS ARE LISTED THE SAME THREE WAYS, AND THE REST GET NOTHING: `autonomous-sdlc-harness init` writes a second family of scripts into {{scriptsDir}} whose bodies ship fixed and read `harness.config.json` at run time rather than carrying a command line of yours. Only the ones a dispatched agent or the orchestrating session is itself the thing that runs are listed here - the orchestrating session runs two of them, the flow walker `flow-walker.sh` and the test-suite runner `run-test-suite.sh` - and they are in `allow` rather than `ask` because they sit on the unattended commit, planning or gate-run path, where an `ask` is evaluated first and parks the run with nothing to answer it. The run watcher, the worktree tooling and the cleanup sweep are started by the watcher process or by you, and `remote-run.sh` by the watcher, the remote job or you; they carry no entry on purpose: one would hand a dispatched agent a path to a branch deletion, a daemon restart or a remote run dispatch. The docs-retrieval server launcher carries no entry either, for a different reason: the agent runner starts it from `.mcp.json` when docs.retrieval is on, never a dispatched agent's Bash call, and the one tool it serves, `search_docs` on the `harness-docs` server, is granted by the retrieval fragment's entry for it instead. Adding an entry for one of them is a decision to let an agent run it - make it deliberately, in the same three forms as everything else here.",
     "THE PACKAGE MANAGER, THE BUILD AND THE DEPENDENCY INSTALL ARE DELIBERATELY NOT ALLOW-LISTED: `commands.build` and `commands.depInstall` are raw command lines with no wrapper, because they are run by a person or by the outer loop rather than by an agent, and granting an agent a package manager grants it every script that package manager can run. An adopter who wants one of them agent-run adds a wrapper script for it and one literal entry here, in the same three forms as the wrappers above. That stance leaves an ad-hoc probe a route, and it needs no entry here either - the next paragraph is that route, and the trade it makes rather than an exception it satisfies.",
     "THE PROBE ROUTE GRANTS AN INTERPRETER AT ONE REMOVE, AND IT IS BROADER THAN THE GRANT ABOVE REFUSES, NOT NARROWER: an ad-hoc probe or a mutation check is written into the run-artifact tree's `scratch/` directory and run through `bash {{scriptsDir}}/scratch-run.sh`, an outer-loop script whose three forms are already listed above. It runs a FILE from that one directory rather than a string on the command line, which fences WHICH FILE runs and nothing about what that file does: the file is one the agent composed a tool call earlier, it runs with the session's own privileges, and it reaches everything the `deny` floor below, the `ask` list below and the plugin guard's own deny list withhold from a COMMAND STRING. The trade is deliberate and is recorded here rather than left to be discovered: the alternative is a run with no permitted way to execute anything, which silently downgrades a verification claim from executed to reasoned. What still holds for a subprocess is the `pre-push` git hook, because git runs it however git was invoked. Removing the route means deleting `scratch-run.sh`'s `agentInvocable` row in the generator and adding its basename to the plugin guard's deny list - both, since either alone leaves it reachable.",
     "CREATING A FILE AND CHANGING ONE ARE TWO DIFFERENT GRANTS: `Edit` covers a change to a file that already exists, `Write` covers creating one - and almost every artifact a run produces is a new file, from a plan to a review to a ledger entry to whatever source file an implementer adds. Dropping the `Write` pair therefore leaves the most common operation in the whole flow matching neither `allow` nor `deny`, which in print mode is a stall and not a refusal. `defaultMode` does not close that gap: its auto-accept is scoped to the session's own working directory, and the entry that matters most here is the sibling-worktree one.",

package/templates/github/workflows/harness-resume.yml

@@ -0,0 +1,124 @@
+# harness-resume.yml — resumes usage-paused autonomous-sdlc-harness runs once
+# their usage window has reset, with no local machine involved.
+#
+# WHO WRITES IT. `autonomous-sdlc-harness init`, only when harness.config.json's
+# `execution.target` is `github-actions`. Written create-if-absent: from then on
+# it is yours to tune, and a re-run of `init` keeps your copy.
+#
+# WHY A POLLER. A `schedule` trigger is a recurring cron read from the default
+# branch, not a one-shot timer, so resuming at a recorded reset time means
+# polling. Each tick runs `remote-run.sh poll`: it downloads each branch's
+# newest `harness run` bundle and dispatches `resume: pause` for every
+# usage-paused run whose recorded reset has passed.
+#
+# IT DISABLES ITSELF. When a tick leaves no run waiting, `poll` runs
+# `gh workflow disable harness-resume.yml`; a job that ends on a usage pause
+# re-enables it (`remote-run.sh continue`). Ticks are paid only during a pause.
+# That also makes moot GitHub's disabling of scheduled workflows in a public
+# repository after 60 days without activity.
+#
+# UNVERIFIED: whether GITHUB_TOKEN with `actions: write` may enable and disable
+# a workflow. If it may not, the pausing job's `paused` notification says
+# auto-resume is unavailable, and the run waits for
+# /autonomous-sdlc-harness:branch-resume.
+#
+# THE INTERVAL IS YOURS TO EDIT. On a private repository every tick is billed
+# at least one minute while the poller is enabled: `*/30` is up to 48 minutes a
+# day, `*/15` up to 96, `0 * * * *` up to 24, each adding at most its interval
+# to how late a run resumes after its reset. On a public repository the ticks
+# cost nothing.
+#
+# WHAT IT READS.
+#   Secrets: HARNESS_PUSH_URL (optional notifications: the poller's own failed
+#     notice when it cannot resume a run).
+#   Variables: HARNESS_RUNNER, HARNESS_REMOTE_STOP (any value: the tick
+#     dispatches nothing), HARNESS_MAX_CHAIN (the automatic-dispatch limit),
+#     HARNESS_POLL_MAX_DISPATCH_FAILURES (failed re-dispatches of one paused
+#     run before the poller gives up on it; 3 when unset) and
+#     HARNESS_POLL_GIVE_UP_AFTER_MINUTES (minutes after the usage reset past
+#     which it gives up; 360 when unset).
+#   harness.config.json, at run time: `scriptsDir` and `stateDir`. No
+#     configured value is frozen into this file.
+#   The previous tick's `harness-poll-state` artifact, which `poll` downloads.
+#     The job's `actions: write` covers listing and downloading its own
+#     workflow's artifacts.
+#
+# WHAT IT WRITES. The `harness-poll-state` artifact: the failed-dispatch count
+#   `poll` carries to the next tick, kept 7 days.
+#
+# THE RULE EVERY EDIT KEEPS. Every GitHub expression has a space after its
+# opening braces, and every value reaches a shell line through `env:`. `init`
+# renders this file with the CLI's double-brace token renderer, which reads a
+# letter straight after the braces as a token; this file carries no token.
+#
+# DECLARED MIRRORS — a rename on either side is an edit to both:
+#   cli/src/remote/githubActions.ts   WORKFLOW_RESUME_FILE, HARNESS_RUNNER,
+#                                     HARNESS_REMOTE_STOP, HARNESS_PUSH_URL,
+#                                     POLL_STATE_ARTIFACT_NAME
+#   cli/src/config/model.ts           DEFAULTS.scriptsDir, DEFAULTS.stateDir
+
+name: harness-resume
+
+on:
+  schedule:
+    - cron: '*/30 * * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: write
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  poll:
+    runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    # A hand-dispatched tick overlapping a scheduled one would dispatch twice.
+    concurrency:
+      group: harness-resume
+      cancel-in-progress: false
+    env:
+      GH_TOKEN: ${{ github.token }}
+      HARNESS_REMOTE_STOP: ${{ vars.HARNESS_REMOTE_STOP }}
+      HARNESS_MAX_CHAIN: ${{ vars.HARNESS_MAX_CHAIN }}
+      HARNESS_POLL_MAX_DISPATCH_FAILURES: ${{ vars.HARNESS_POLL_MAX_DISPATCH_FAILURES }}
+      HARNESS_POLL_GIVE_UP_AFTER_MINUTES: ${{ vars.HARNESS_POLL_GIVE_UP_AFTER_MINUTES }}
+      HARNESS_REMOTE_SLUG: ${{ github.repository }}
+      HARNESS_PUSH_URL: ${{ secrets.HARNESS_PUSH_URL }}
+    steps:
+      - name: Check out the default branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Read the configuration
+        run: |
+          missing=""
+          for tool in jq gh; do
+            command -v "$tool" >/dev/null 2>&1 || missing="$missing $tool"
+          done
+          if [ -n "$missing" ]; then
+            echo "::error::this runner lacks:$missing. Install them on the self-hosted runner, or use a GitHub-hosted one."
+            exit 1
+          fi
+          scripts_dir=$(jq -r '.scriptsDir // "scripts"' harness.config.json)
+          state_dir=$(jq -r '.stateDir // "sdlc-harness"' harness.config.json)
+          {
+            echo "SCRIPTS_DIR=${scripts_dir%/}"
+            echo "POLL_STATE_DIR=${state_dir%/}/autonomous_logs/poll_state/current"
+          } >> "$GITHUB_ENV"
+
+      - name: Resume the runs whose usage window has reset
+        run: bash "$SCRIPTS_DIR/remote-run.sh" poll
+
+      - name: Upload the poller state
+        if: always() && env.POLL_STATE_DIR != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: harness-poll-state
+          path: ${{ env.POLL_STATE_DIR }}
+          overwrite: true
+          if-no-files-found: ignore
+          retention-days: 7