autonomous-sdlc-harness 0.1.0 → 0.4.0

package/dist/retrieval/setup.js

@@ -0,0 +1,121 @@
+/**
+ * The setup-time half of docs retrieval: installing the runtime and downloading the models, which
+ * `init` runs after its plan when the config in effect has retrieval on.
+ *
+ * **The rule this module exists to enforce: every download retrieval needs happens here, at setup
+ * time, and never on a run.** An unattended run has no network to count on, so the runtime install
+ * and the model download both happen while an operator is present.
+ *
+ * - **The install skips on `retrievalRuntimeState().installed` and nothing else.** The `.mcp.json`
+ *   launcher (`docs-search-server.sh`) runs the runtime's entry alone, so an installation that
+ *   resolves its own peers still needs the runtime. The install-state tests live in
+ *   `retrieval/runtime.ts` alone, the same predicate `doctor` grades on.
+ * - **A stub run never installs and never downloads.** With `RETRIEVAL_STUB_ENV` set, a missing
+ *   runtime is a warning rather than an `npm` call, so a test that forgets to plant one stays offline.
+ * - **A failed step is a warning.** The wiring the plan wrote stays valid; `doctor` fails until a
+ *   re-run completes the step.
+ *
+ * Both steps put machine state outside the repository, not through the write engine
+ * (`cli/src/core/writer.ts` header). `setUpRuntime` writes the runtime itself, through `npm`;
+ * `setUpModels` only spawns `docs fetch-models`, and the model cache's write belongs to
+ * `retrieval/models.ts` → `fetchModels`, through Transformers.js, in that child process.
+ */
+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 { 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';
+/** A warning for a failed child: the command, its exit status and the last line it wrote to stderr. */
+function failureWarning(step, command, error) {
+    const failure = error;
+    const status = typeof failure?.status === 'number'
+        ? `exit status ${failure.status}`
+        : failure?.signal
+            ? `killed by ${failure.signal}`
+            : `not run (${failure?.code ?? String(error)})`;
+    const stderr = failure?.stderr === undefined ? '' : String(failure.stderr);
+    const lastLine = stderr
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '')
+        .pop();
+    return `docs retrieval ${step} failed: \`${command.join(' ')}\` ended with ${status}${lastLine === undefined ? '' : `: ${lastLine}`}. The retrieval wiring is written and stays valid; ${REMEDY}`;
+}
+function runStep(step, command, warnings) {
+    const [file, ...args] = command;
+    try {
+        execFileSync(file, args, { stdio: ['ignore', 'ignore', 'pipe'], timeout: STEP_TIMEOUT_MS });
+    }
+    catch (error) {
+        warnings.push(failureWarning(step, command, error));
+    }
+}
+function setUpRuntime(dryRun, notes, warnings) {
+    const runtimeDir = retrievalRuntimeDir();
+    const state = retrievalRuntimeState();
+    if (state.installed) {
+        notes.push(`docs retrieval runtime already installed: version ${state.version ?? 'unknown'} in ${runtimeDir}`);
+        return;
+    }
+    const command = [
+        'npm',
+        'install',
+        '--prefix',
+        runtimeDir,
+        '--no-audit',
+        '--no-fund',
+        `${ownManifestString('name')}@${ownManifestString('version')}`,
+        ...retrievalPeers().map((peer) => `${peer.name}@${peer.range}`),
+    ];
+    if (dryRun) {
+        notes.push(`docs retrieval runtime would be installed (dry run): \`${command.join(' ')}\``);
+        return;
+    }
+    if (stubModelsSelected()) {
+        warnings.push(`docs retrieval runtime is not installed in ${runtimeDir}, and a stub run (${RETRIEVAL_STUB_ENV} set) never installs it; unset ${RETRIEVAL_STUB_ENV} and ${REMEDY}`);
+        return;
+    }
+    mkdirSync(runtimeDir, { recursive: true });
+    runStep('runtime install', command, warnings);
+}
+function setUpModels(dryRun, notes, warnings) {
+    const cacheDir = retrievalModelCacheDir();
+    if (stubModelsSelected()) {
+        notes.push(`docs retrieval models: stub models (${RETRIEVAL_STUB_ENV} set) need no download`);
+        return;
+    }
+    if (modelFilesPresent(cacheDir).present) {
+        notes.push(`docs retrieval models already cached in ${cacheDir}`);
+        return;
+    }
+    // In a dry run the install above has not happened, so the runtime's entry is named where no other resolves.
+    const entry = retrievalCliEntry()?.entry;
+    const command = [
+        process.execPath,
+        entry ?? join(retrievalRuntimeDir(), RUNTIME_CLI_RELATIVE),
+        'docs',
+        'fetch-models',
+    ];
+    if (dryRun) {
+        notes.push(`docs retrieval models would be downloaded into ${cacheDir} (dry run): \`${command.join(' ')}\``);
+        return;
+    }
+    if (entry === undefined) {
+        warnings.push(`docs retrieval models were not downloaded: no CLI entry can load the retrieval packages, because the runtime in ${retrievalRuntimeDir()} is not installed; ${REMEDY}`);
+        return;
+    }
+    runStep('model download', command, warnings);
+}
+/** Install the runtime, then download the models; each step skips when already satisfied. */
+export function setUpRetrieval(options) {
+    const notes = [];
+    const warnings = [];
+    setUpRuntime(options.dryRun, notes, warnings);
+    setUpModels(options.dryRun, notes, warnings);
+    return { notes, warnings };
+}
+//# sourceMappingURL=setup.js.map

package/dist/retrieval/setup.js.map

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

package/dist/retrieval/store.js

@@ -0,0 +1,170 @@
+/**
+ * The docs-retrieval index store: the {@link DocStore} interface every consumer takes, and its one
+ * implementation on an embedded Postgres (PGlite) with an HNSW vector index and a BM25 lexical index.
+ *
+ * **The rule this module exists to enforce: every value reaches SQL as a bound parameter, and the SQL
+ * stays plain Postgres plus the `vector` and `pg_textsearch` extensions.** A search query comes from an
+ * agent and is untrusted, so no input is ever spliced into a statement; the two spliced tokens are the
+ * `vector(<dimensions>)` column type, taken from a checked integer, and the constant index name inside
+ * `to_bm25query($1, 'chunks_bm25')`. Keeping the dialect plain is what would let a real Postgres
+ * implement {@link DocStore} by connection string; this module builds no such implementation.
+ *
+ * **The shapes the lexical plan's cost depends on are exported, and a caller composes them rather than
+ * retyping them:** {@link CHUNKS_TABLE}, {@link BM25_INDEX}, {@link BM25_INDEX_DEFINITION},
+ * {@link BM25_ORDER_CLAUSE}, {@link CHUNK_TEXT_COLUMN} and {@link chunkEmbeddingColumn}. They exist for
+ * `cli/test/docs-retrieval-store.test.mjs`, which measures the row count at which the planner chooses
+ * the BM25 index scan and must build that index *after* the rows — which this module's open path cannot
+ * do. The statements below are issued from those same constants, so there is no second copy inside the
+ * owner either, and a change to the indexed column, the `text_config`, the index name, the row width or
+ * the ordering operator moves the measurement with it instead of leaving it describing a store that no
+ * longer exists.
+ *
+ * The PGlite packages are optional peers reached only through `loadRetrievalModule`
+ * (`cli/src/retrieval/runtime.ts`); this file takes their types with `import type`.
+ */
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { internal } from '../core/errors.js';
+import { normalizeRepoDir } from '../core/repoPaths.js';
+import { loadRetrievalModule } from './runtime.js';
+/** The index directory's name under `stateDir`; the ignore rule reads it from here. */
+export const INDEX_DIR_NAME = 'docs_index';
+/** The chunk table's name, so a composed statement names the same table the store's own DDL creates. */
+export const CHUNKS_TABLE = 'chunks';
+/** The BM25 lexical index's name, spliced rather than bound — see the header's spliced-token clause. */
+export const BM25_INDEX = 'chunks_bm25';
+/**
+ * Everything after the index name in the BM25 index's `CREATE INDEX`: the indexed column and the
+ * `text_config` the planner's row estimate and the scan's matching-rows behaviour both depend on. The
+ * `IF NOT EXISTS` is the open path's alone, so a caller building the index after its rows composes the
+ * same definition without it.
+ */
+export const BM25_INDEX_DEFINITION = `ON ${CHUNKS_TABLE} USING bm25 (text) WITH (text_config='english')`;
+/** The lexical arm's ordering clause; `$1` is the bound query text. */
+export const BM25_ORDER_CLAUSE = `text <@> to_bm25query($1, '${BM25_INDEX}')`;
+/** The BM25-indexed column's declaration. */
+export const CHUNK_TEXT_COLUMN = 'text text NOT NULL';
+/** The embedding column's declaration; its width is what sets the rows per page a scan is costed on. */
+export function chunkEmbeddingColumn(dimensions) {
+    return `embedding vector(${dimensions}) NOT NULL`;
+}
+/** `<repoRoot>/<stateDir>/docs_index` — the per-checkout index PGlite persists into. */
+export function indexDataDir(repoRoot, stateDir) {
+    return join(repoRoot, normalizeRepoDir(stateDir), INDEX_DIR_NAME);
+}
+const PGLITE_SPECIFIER = '@electric-sql/pglite';
+const PGVECTOR_SPECIFIER = '@electric-sql/pglite-pgvector';
+const PG_TEXTSEARCH_SPECIFIER = '@electric-sql/pglite-pg_textsearch';
+/** The meta key recording the width the `chunks.embedding` column was created with. */
+const DIMENSIONS_META_KEY = 'dimensions';
+/** The meta key refresh compares against the embedder's id; cleared when the column is recreated. */
+export const EMBEDDER_META_KEY = 'embedder';
+/** A vector as pgvector's text input form, bound as `$n::vector`. */
+function vectorLiteral(embedding) {
+    return `[${embedding.map((value) => String(value)).join(',')}]`;
+}
+/**
+ * Opens the index. `dataDir: undefined` is an in-memory store; a path is created and persisted into.
+ *
+ * An existing index built at another width has its `chunks` table dropped and its embedder record
+ * removed, so the next refresh rebuilds rather than failing on the column type.
+ */
+export async function openPgliteStore(options) {
+    const { dataDir, dimensions } = options;
+    if (!Number.isInteger(dimensions) || dimensions <= 0) {
+        throw internal(`openPgliteStore was given ${String(dimensions)} dimensions, which is not a positive integer`);
+    }
+    const { PGlite } = await loadRetrievalModule(PGLITE_SPECIFIER);
+    const { vector } = await loadRetrievalModule(PGVECTOR_SPECIFIER);
+    const { pg_textsearch } = await loadRetrievalModule(PG_TEXTSEARCH_SPECIFIER);
+    // The one in-repository write outside the write engine: `cli/src/core/writer.ts`'s header, the
+    // per-checkout docs index clause; raised for a supervised amendment in the story index's
+    // `## Corpus staleness`.
+    if (dataDir !== undefined)
+        mkdirSync(dataDir, { recursive: true });
+    const db = await PGlite.create({ dataDir, extensions: { vector, pg_textsearch } });
+    await db.exec('CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS pg_textsearch;');
+    await db.exec('CREATE TABLE IF NOT EXISTS meta (key text PRIMARY KEY, value text NOT NULL)');
+    const readMeta = async (key) => {
+        const result = await db.query('SELECT value FROM meta WHERE key = $1', [key]);
+        return result.rows[0]?.value;
+    };
+    const writeMeta = async (key, value) => {
+        await db.query('INSERT INTO meta (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value', [
+            key,
+            value,
+        ]);
+    };
+    const width = String(dimensions);
+    if ((await readMeta(DIMENSIONS_META_KEY)) !== width) {
+        await db.exec(`DROP TABLE IF EXISTS ${CHUNKS_TABLE}`);
+        await db.query('DELETE FROM meta WHERE key = $1', [EMBEDDER_META_KEY]);
+    }
+    await db.exec(`CREATE TABLE IF NOT EXISTS ${CHUNKS_TABLE} (id serial PRIMARY KEY, key text UNIQUE NOT NULL, path text NOT NULL, ` +
+        `anchor text NOT NULL, heading text NOT NULL, body text NOT NULL, ${CHUNK_TEXT_COLUMN}, hash text NOT NULL, ` +
+        `${chunkEmbeddingColumn(dimensions)})`);
+    await db.exec(`CREATE INDEX IF NOT EXISTS chunks_hnsw ON ${CHUNKS_TABLE} USING hnsw (embedding vector_cosine_ops)`);
+    await db.exec(`CREATE INDEX IF NOT EXISTS ${BM25_INDEX} ${BM25_INDEX_DEFINITION}`);
+    await writeMeta(DIMENSIONS_META_KEY, width);
+    const ranked = (rows) => rows.map((row, index) => ({ id: row.id, rank: index + 1 }));
+    return {
+        readMeta,
+        writeMeta,
+        async listChunkHashes() {
+            const result = await db.query(`SELECT key, hash FROM ${CHUNKS_TABLE}`);
+            return new Map(result.rows.map((row) => [row.key, row.hash]));
+        },
+        async upsertChunks(chunks, embeddings) {
+            if (chunks.length !== embeddings.length) {
+                throw internal(`upsertChunks was given ${chunks.length} chunks and ${embeddings.length} embeddings`);
+            }
+            await db.transaction(async (tx) => {
+                for (const [index, chunk] of chunks.entries()) {
+                    const embedding = embeddings[index] ?? [];
+                    if (embedding.length !== dimensions) {
+                        throw internal(`an embedding for ${chunk.key} has ${embedding.length} dimensions where the index has ${dimensions}`);
+                    }
+                    await tx.query(`INSERT INTO ${CHUNKS_TABLE} (key, path, anchor, heading, body, text, hash, embedding) ` +
+                        'VALUES ($1, $2, $3, $4, $5, $6, $7, $8::vector) ' +
+                        'ON CONFLICT (key) DO UPDATE SET path = EXCLUDED.path, anchor = EXCLUDED.anchor, heading = EXCLUDED.heading, ' +
+                        'body = EXCLUDED.body, text = EXCLUDED.text, hash = EXCLUDED.hash, embedding = EXCLUDED.embedding', [chunk.key, chunk.path, chunk.anchor, chunk.heading, chunk.body, chunk.text, chunk.hash, vectorLiteral(embedding)]);
+                }
+            });
+        },
+        async deleteChunks(keys) {
+            if (keys.length === 0)
+                return;
+            await db.query(`DELETE FROM ${CHUNKS_TABLE} WHERE key = ANY($1::text[])`, [[...keys]]);
+        },
+        async clear() {
+            await db.exec(`DELETE FROM ${CHUNKS_TABLE}`);
+        },
+        async lexicalSearch(query, limit) {
+            if (query.trim() === '')
+                return [];
+            // pg_textsearch scores lower-is-better; a non-matching row scores 0, so matches sort first.
+            // Filtering to matching rows alone is the index scan's behaviour, not the operator's — see the
+            // interface comment above.
+            const result = await db.query(`SELECT id FROM ${CHUNKS_TABLE} ORDER BY ${BM25_ORDER_CLAUSE} LIMIT $2`, [query, limit]);
+            return ranked(result.rows);
+        },
+        async vectorSearch(embedding, limit) {
+            const result = await db.query(`SELECT id FROM ${CHUNKS_TABLE} ORDER BY embedding <=> $1::vector LIMIT $2`, [vectorLiteral(embedding), limit]);
+            return ranked(result.rows);
+        },
+        async getChunks(ids) {
+            if (ids.length === 0)
+                return [];
+            const result = await db.query(`SELECT id, key, path, anchor, heading, body FROM ${CHUNKS_TABLE} WHERE id = ANY($1::int[])`, [[...ids]]);
+            const byId = new Map(result.rows.map((row) => [row.id, row]));
+            return ids.flatMap((id) => {
+                const row = byId.get(id);
+                return row === undefined ? [] : [row];
+            });
+        },
+        async close() {
+            await db.close();
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/retrieval/store.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "autonomous-sdlc-harness",
-  "version": "0.1.0",
-  "description": "The outer loop of the autonomous SDLC harness: init, doctor, config and daemon management for the harness Claude Code plugin.",
+  "version": "0.4.0",
+  "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",
   "homepage": "https://github.com/firu-daniel/autonomous-sdlc-harness",
@@ -16,8 +16,27 @@
     "test": "node --test",
     "prepublishOnly": "npm run build"
   },
+  "peerDependencies": {
+    "@electric-sql/pglite": "0.5.8",
+    "@electric-sql/pglite-pg_textsearch": "^0.0.10",
+    "@electric-sql/pglite-pgvector": "^0.0.9",
+    "@huggingface/transformers": "^4.3.0",
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": { "optional": true },
+    "@electric-sql/pglite-pg_textsearch": { "optional": true },
+    "@electric-sql/pglite-pgvector": { "optional": true },
+    "@huggingface/transformers": { "optional": true },
+    "@modelcontextprotocol/sdk": { "optional": true }
+  },
   "devDependencies": {
     "typescript": "^5.6.0",
-    "@types/node": "^20.14.0"
+    "@types/node": "^20.14.0",
+    "@electric-sql/pglite": "0.5.8",
+    "@electric-sql/pglite-pg_textsearch": "^0.0.10",
+    "@electric-sql/pglite-pgvector": "^0.0.9",
+    "@huggingface/transformers": "^4.3.0",
+    "@modelcontextprotocol/sdk": "^1.30.0"
   }
 }

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/CLAUDE.md

@@ -2,7 +2,7 @@
 
 {{setupBanner}}
 
-_`/harness-analyze` writes this paragraph from the repository itself — or replace this line by hand: what this project is, who uses it, and anything an agent must know before it touches a file._
+_`/{{pluginName}}:harness-analyze` writes this paragraph from the repository itself — or replace this line by hand: what this project is, who uses it, and anything an agent must know before it touches a file._
 
 ---
 
@@ -12,7 +12,7 @@ _`/harness-analyze` writes this paragraph from the repository itself — or repl
 |---|---|---|
 | _(kind of file)_ | _(the name pattern it follows)_ | _(one real file in this repository that follows it)_ |
 
-_`/harness-analyze` fills this table from the repository's real file names — or add the rows by hand, one per kind of file this project has a naming rule for. Until it is filled, an implementer follows whatever the files around it already do, which is slower and less consistent than one row here._
+_`/{{pluginName}}:harness-analyze` fills this table from the repository's real file names — or add the rows by hand, one per kind of file this project has a naming rule for. Until it is filled, an implementer follows whatever the files around it already do, which is slower and less consistent than one row here._
 
 ---
 
@@ -26,7 +26,7 @@ This file is auto-loaded into every agent, which is why it deliberately holds al
 
 > **Checkout root — derive it, never assume it.** Take the root of the checkout **you are running in** from a **bare** `git rev-parse --show-toplevel` (a read-only command an unattended run can allow-list as a literal), then build every literal path from that result — this run's artifacts under `<root>/{{stateDir}}/`, the lessons ledger at `<root>/{{stateDir}}/lessons.md`. This binds **every** repo-relative path you are given and every file you write, not only the ledger. Do not hardcode an absolute path, do not wrap the substitution inside another shell command, and do not stash it in a shell variable — separate tool calls do not share shell state, and a command carrying a substitution is not reliably auto-allowed in an unattended run. In a second working copy the original checkout is a *different branch*: reading it returns that branch's file, and writing to it puts this run's artifact on the wrong branch. One exception, and it is not one you resolve: an **argument** path handed to a wrapper script is **relative to that wrapper's own base and never prefixed with a checkout root** — which base that is, is the wrapper's to state (its `--repo`, or the directory it `cd`s to); take it from the wrapper's own documented usage rather than assuming the repo top. The wrapper's own invocation path is rooted like everything else. The links in the table above are document pointers; resolve the live path this way at read and write time.
 
-The rows above were generated from the `layers` list in `harness.config.json`, so this table and the layers the orchestrator dispatches on started out in agreement. Keep them that way: add a layer there, then add its row here by hand — that is the route that costs nothing. `autonomous-sdlc-harness init --force` will also re-render the rows from the `layers` list as it then stands (`--force` overwrites generated files but never `harness.config.json`, which `autonomous-sdlc-harness init` reads on every run, so the layer just added is the one the rows come from), but it regenerates **this whole file** from the template — every section `/harness-analyze` filled goes with it, recoverable only from the single `CLAUDE.md.bak` the run writes. That `.bak` is single-generation, and the next `--force` does not necessarily spend it: a forced run that finds this file byte-identical to the one it would write keeps the file and leaves the `.bak` alone, so the sections a previous pass rescued into it stay there. What overwrites a `.bak` holding filled sections is a forced run over a file that has been filled again since. The orchestrator reads none of these files; the committer reads exactly one section of one of them — the commit-message policy in the shared cross-layer conventions document — and nothing else. One read-on-demand document is deliberately not in that table because no layer owns it: `.claude/harness-task-offer.md`, which `## Where a change request runs` below points at directly and nothing else reads.
+The rows above were generated from the `layers` list in `harness.config.json`, so this table and the layers the orchestrator dispatches on started out in agreement. Keep them that way: add a layer there, then add its row here by hand — that is the route that costs nothing. `autonomous-sdlc-harness init --force` will also re-render the rows from the `layers` list as it then stands (`--force` overwrites generated files but never `harness.config.json`, which `autonomous-sdlc-harness init` reads on every run, so the layer just added is the one the rows come from), but it regenerates **this whole file** from the template — every section `/{{pluginName}}:harness-analyze` filled goes with it, recoverable only from the single `CLAUDE.md.bak` the run writes. That `.bak` is single-generation, and the next `--force` does not necessarily spend it: a forced run that finds this file byte-identical to the one it would write keeps the file and leaves the `.bak` alone, so the sections a previous pass rescued into it stay there. What overwrites a `.bak` holding filled sections is a forced run over a file that has been filled again since. The orchestrator reads none of these files; the committer reads exactly one section of one of them — the commit-message policy in the shared cross-layer conventions document — and nothing else. One read-on-demand document is deliberately not in that table because no layer owns it: `.claude/harness-task-offer.md`, which `## Where a change request runs` below points at directly and nothing else reads.
 
 ---
 
@@ -43,7 +43,7 @@ The allowlist is the whole mechanism, deliberately: a global deny is evaluated b
 Four tests, all of which must hold, **in this order** — the first three cost nothing, so reach the fourth only when they have all passed. If any fails: say nothing, offer nothing, and carry out the instruction you were given.
 
 1. **Tool.** `AskUserQuestion` is in your own toolset. If it is not, you are an unattended run and nothing below applies to you.
-2. **Provenance.** The message was **typed by the user in this conversation**. Not an instruction you are executing from a harness command or a flow-instruction document it dispatched — every `/branch-*` and `/harness-*`, supervised, semi-autonomous and unattended alike, including reading a task prompt or a review file as your own work. Not one handed to you as a **dispatched sub-agent**, whichever agent type you are and whatever your toolset holds. Not a continuation of work the user has already routed, in this conversation or in the one that dispatched you.
+2. **Provenance.** The message was **typed by the user in this conversation**. Not an instruction you are executing from a harness command or a flow-instruction document it dispatched — every `/{{pluginName}}:branch-*` and `/{{pluginName}}:harness-*`, supervised, semi-autonomous and unattended alike, including reading a task prompt or a review file as your own work. Not one handed to you as a **dispatched sub-agent**, whichever agent type you are and whatever your toolset holds. Not a continuation of work the user has already routed, in this conversation or in the one that dispatched you.
 3. **Trigger.** The message **asks for a change to this project's code** — a feature, a fix, a refactor, a chore. **Size is never a factor.** The line is *asks for a change* versus *asks about the code*: *"explain this function"* fires **nothing**; *"this button isn't centred"* fires; *"check this file `/some/path/notes.txt` to implement adding comments to a content item"* fires too, because where a spec lives does not change what is being asked. A message invoking or continuing a harness command does not fire. Any shape you cannot place: **stay silent**.
 4. **Opt-out.** `.claude/harness-no-offer` does not exist at the **main worktree's** root — the checkout you are running in may be a worktree of it, and the marker is written once for all of them. Test it with the shell rather than by reading anything: `test -e "$(git worktree list | head -1 | awk '{print $1}')/.claude/harness-no-offer"`, whose first line is always the main worktree and which is the same path in an ordinary single-checkout repository; the checkout-root rule's literal-command constraint is an unattended-run allow-listing concern and clause 1 has already excluded those. Presence-only: never read, parse or act on anything inside it — a read of a path outside this session's own root can raise a permission prompt mid-fence, while the test's non-zero exit is a clean answer. The file is normally absent, and absent means only *not opted out*; a check you cannot make — the command declined, the repository not a git one, no output — is silence too, never a remark to the user about a file they never created.
 

package/templates/claude/README.md

@@ -1,5 +1,7 @@
 # claude/
 
-Copied into the adopter's `.claude/` directory by `autonomous-sdlc-harness init`: the project-context and conventions stubs that `/harness-analyze` fills in from the adopted repository's real code, under the marker contract `docs/analyze.md` records, the settings and permission profile the unattended modes run under (roadmap item 14), the `*.env.example` files an adopter copies and completes with its own credentials and push configuration, `harness-task-offer.md`, the change-request offer rules the always-loaded file's fence reads on demand, and — when the interactive test phase is on — the test-scenario-rules skeleton that phase's agents read. The settings profile is the reason a CLI exists at all — a plugin cannot write a repository's `settings.json`, and getting that profile right, with every wrapper script allow-listed in the exact literal form the guard matches, is the highest-friction part of adoption.
+Copied into the adopter's `.claude/` directory by `autonomous-sdlc-harness init`: the project-context and conventions stubs that `/autonomous-sdlc-harness:harness-analyze` fills in from the adopted repository's real code, under the marker contract `docs/analyze.md` records, the settings and permission profile the unattended modes run under (roadmap item 14), the `*.env.example` files an adopter copies and completes with its own credentials and push configuration, `harness-task-offer.md`, the change-request offer rules the always-loaded file's fence reads on demand, and — when the interactive test phase is on — the test-scenario-rules skeleton that phase's agents read. The settings profile is the reason a CLI exists at all — a plugin cannot write a repository's `settings.json`, and getting that profile right, with every wrapper script allow-listed in the exact literal form the guard matches, is the highest-friction part of adoption.
+
+`settings.autonomous.qa.json` and `settings.autonomous.retrieval.json` are **fragments** merged into that profile rather than second profiles: the first when the interactive test phase drives a browser, the second when `phases.docs` and `docs.retrieval` are both on. The retrieval fragment starts the `harness-docs` server `repo/mcp.retrieval.json` declares and allows its one tool, and needs both keys: a server that is not started has no tools, and an un-loaded tool stalls an unattended run.
 
 **This directory is never named `.claude` inside this repository, and must not be renamed to it.** These are templates for **someone else's** configuration, not this repository's own: the dot is added at the adopter's end, by `autonomous-sdlc-harness init`, and nowhere else, so the stored path is the undotted one. The reason once given here was that a dotted path would register these templates as live agents and commands in any session opened at this root; that was measured false on Claude Code 2.1.234 on 2026-08-19, against a root-level control in the same repository — a `.claude/` in a subdirectory registers nothing into a session rooted above it — so do not restore it. The one literal `.claude/` in this tree, under `examples/notes-app/`, is an adopted repository's own generated output rather than a template, which is why it is not a counter-example to this rule.

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. 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/claude/settings.autonomous.retrieval.json

@@ -0,0 +1,9 @@
+{
+  "_README": [
+    "THE DOCS-RETRIEVAL HALF, ADDED ONLY WHEN TWO CONDITIONS BOTH HOLD - THE DOCS PHASE IS ENABLED, AND DOCS RETRIEVAL IS ON: the `harness-docs` entry in `enabledMcpjsonServers` and the one `mcp__harness-docs__` entry at the end of `allow` were merged in because `phases.docs` AND `docs.retrieval` were both true when this file was generated. Fail either condition and neither is written. BOTH ARE NEEDED AND THEY DO DIFFERENT THINGS: the enablement STARTS the server the repository's own `.mcp.json` declares, and the allow entry lets its one tool run - without the enablement the tool does not exist, and an un-loaded tool in print mode stalls the run rather than failing it. Turning retrieval on in `harness.config.json` and re-running `autonomous-sdlc-harness init` does NOT rewrite this file - it is yours once written, and a plain re-run adds the server to `.mcp.json` while leaving this profile starting none of it; run `init --force`, which takes a .bak first, or copy the two entries in from a fresh generation."
+  ],
+  "enabledMcpjsonServers": ["harness-docs"],
+  "permissions": {
+    "allow": ["mcp__harness-docs__search_docs"]
+  }
+}