autonomous-sdlc-harness 0.1.0

package/dist/machine/registry.js

@@ -0,0 +1,330 @@
+/**
+ * The machine-local registry of initialized repositories: its format of record, and the only code
+ * that reads or writes it.
+ *
+ * **The rule this module exists to enforce: `repos.json` has one definition, and it is this file.**
+ * Two consumers ask about this artifact — `daemon list`, which enumerates it, and `doctor`, which
+ * reports on it — and a second derivation of the path, the JSON shape or the staleness grading would
+ * be a second answer to "what is armed on this machine". The name is joined here and nowhere else
+ * (`grep -rn REGISTRY_FILENAME cli/src`); that is the property worth keeping. The one mirror outside
+ * that scope is `MACHINE_REGISTRY_FILENAME` in `cli/templates/scripts/autonomous-watcher.sh`, which
+ * the footprint report reads — `grep -rn 'repos.json' cli/` reaches both.
+ *
+ * `docs/watcher.md` §7 is the human-facing half of this definition and says the same things in the
+ * same order. The two are one contract: change either and change the other in the same commit.
+ *
+ * ## The three questions this artifact has to answer, and its answers
+ *
+ * 1. **Where it lives.** {@link registryPath} — `repos.json` in {@link machineStateDir}, i.e. beside
+ *    the usage lane's two artifacts, in a directory created `0700` and outside every repository. It
+ *    is a **separate file** and is never merged into `usage-state.json`: that one is the lane, its
+ *    format is `docs/watcher.md` §5's, and §5 is explicit that this registry "is a different
+ *    artifact". Sharing a file would put a per-run publisher and a per-install index behind one
+ *    merge rule that suits neither.
+ * 2. **What happens when it is stale** — a recorded root that is gone, is no longer a repository, or
+ *    whose unit file has been removed. It is **reported and never removed by a read**
+ *    ({@link inspect} grades; nothing it does touches the filesystem). A read command must not
+ *    mutate machine state, and a checkout on an unmounted volume or temporarily moved aside must not
+ *    be silently dropped from the index while its daemon is still installed. Pruning is the explicit
+ *    `daemon list --prune`, which is the one caller of {@link removeRepositories}.
+ * 3. **Who writes it.** `daemon install`, and nothing else. `init` does not — a wired repository with
+ *    no daemon polls nothing, so registering it would list repositories that never run. `doctor` does
+ *    not — it repairs nothing and writes nothing, which is what makes it safe in CI. `daemon stop`
+ *    does not remove an entry — the unit file survives a stop, and this index mirrors *installed*
+ *    units rather than running ones.
+ *
+ * ## Two properties nobody should re-derive wrongly
+ *
+ * - **It is not consulted before starting a run.** That is the usage lane's job and `docs/watcher.md`
+ *   §5 says so. Nothing here may become a precondition of anything: an absent, truncated or garbage
+ *   registry costs a listing, never a run, which is why {@link readRegistry} fails open in every one
+ *   of those cases rather than reporting a fault.
+ * - **`daemon install` run from a git worktree registers that worktree, and that is correct.** The
+ *   unit's identity is the checkout it was installed from (`daemon/units.ts`, choice 1) and its text
+ *   carries that checkout as both `ExecStart` and `WorkingDirectory` (choice 4), so the entry has to
+ *   describe the same checkout the unit does. Keying on {@link repoSlug} — the same function that
+ *   names the unit — is what makes the two unable to disagree.
+ *
+ * ## Why the writes here are not enqueued on a `WritePlan`
+ *
+ * `core/writer.ts` implements the `init` re-run contract for artifacts **inside a repository** that
+ * an adopter then owns and edits: its policies are create-if-absent, merge and back-up-then-replace,
+ * and its plan is built by generators and applied once. This file is none of that. It is a
+ * machine-scoped index the CLI owns end to end, it is rewritten in place on every registration
+ * (read-modify-write, not merge), and no adopter edits it. The daemon unit is written through a plan
+ * with `allowOutsideRepo` because it is a create-if-absent artifact an operator may go on to edit;
+ * this one is not.
+ *
+ * The consequence a caller must honor: **{@link upsertRepository} and {@link removeRepositories}
+ * write when they are called.** They are not on the plan, so `--dry-run` does not skip them for you —
+ * a command that supports `--dry-run` must not call either under it.
+ */
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { internal } from '../core/errors.js';
+import { probeRepoRoot } from '../core/git.js';
+import { formatJson, isJsonObject, readJsonFile } from '../core/json.js';
+import { repoSlug } from '../daemon/units.js';
+import { MACHINE_DIR_MODE, machineStateDir } from './paths.js';
+/** The file's name under {@link machineStateDir}. Joined here and nowhere else in the CLI. */
+const REGISTRY_FILENAME = 'repos.json';
+/**
+ * The format version written into every record, and the only one {@link readRegistry} recognises.
+ *
+ * A reader that meets a value it does not know treats the whole file as unreadable — the same rule
+ * `usage-state.json` carries in `docs/watcher.md` §5 — which is also this format's forward-compatible
+ * escape hatch: a release that adds a field or a backend value bumps this integer, and an older CLI
+ * then declines to interpret the file rather than half-understanding it.
+ */
+const REGISTRY_SCHEMA = 1;
+/** Mode of the file: it names an account's checkouts, so it is the owner's to read and nobody else's. */
+const REGISTRY_FILE_MODE = 0o600;
+/** The registry file's absolute path. A pure string: asking where it is never creates anything. */
+export function registryPath() {
+    return join(machineStateDir(), REGISTRY_FILENAME);
+}
+/** Codepoint order, not the locale's — the same ASCII-only discipline {@link repoSlug} is built on. */
+function compareSlugs(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** A non-empty string, or `undefined` for every other JSON value. */
+function stringField(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/**
+ * One record's parsed form, or `undefined` when it is not one.
+ *
+ * **A malformed record is dropped, not fatal.** The file is an index of independent rows, and one
+ * row a hand-edit mangled should not hide the rest — the fail-open rule of the module header applied
+ * at record granularity. The dropped row does not come back: the next {@link upsertRepository}
+ * rewrites the file from what was readable. That is acceptable for the same reason the whole-file
+ * case is (see {@link readRegistry}), and it is why the strictness here is safe rather than brittle:
+ * a future release that adds a field or a backend value arrives with a new
+ * {@link REGISTRY_SCHEMA}, which this reader declines wholesale instead of parsing row by row.
+ */
+function parseEntry(value) {
+    if (!isJsonObject(value))
+        return undefined;
+    const root = stringField(value['root']);
+    const projectName = stringField(value['projectName']);
+    const label = stringField(value['label']);
+    const unitPath = stringField(value['unitPath']);
+    const backend = value['backend'];
+    if (root === undefined || projectName === undefined || label === undefined || unitPath === undefined) {
+        return undefined;
+    }
+    if (backend !== 'launchd' && backend !== 'systemd')
+        return undefined;
+    // A timestamp that is not a whole non-negative number is reduced to 0 rather than discarding the
+    // row: it is a breadcrumb, and losing the entry would cost more than losing its age.
+    const stamp = value['registered_at'];
+    const registered_at = typeof stamp === 'number' && Number.isInteger(stamp) && stamp >= 0 ? stamp : 0;
+    return { root, projectName, label, backend, unitPath, registered_at };
+}
+/**
+ * The registry as it is on disk, or an empty one.
+ *
+ * **It fails open in every failure mode there is**: absent, unreadable (a permission bit, a bad
+ * mount), unparseable, not a JSON object, `repos` not an object, or a `schema` this release does not
+ * recognise all read as "no repositories are registered" rather than throwing. A machine-scoped file
+ * must not be able to stop a repository-scoped command, and this one is not consulted before
+ * starting a run, so there is nothing a fault here could correctly block.
+ *
+ * That is the opposite of `readJsonFile`'s own contract, which throws on unparseable JSON so a later
+ * create-if-absent write cannot clobber a file the adopter merely mistyped. The trade is different
+ * here and worth stating: an unreadable registry **is** rewritten by the next
+ * {@link upsertRepository}, and that is acceptable because this file is *derived* state — every
+ * entry in it can be recreated by re-running `daemon install` in the repository it names, and losing
+ * one costs a line in a listing rather than a run or an adopter's edits.
+ *
+ * The returned registry is a fresh object each call; a caller may keep it and grade it later without
+ * aliasing anyone else's copy.
+ */
+export function readRegistry() {
+    let parsed;
+    try {
+        parsed = readJsonFile(registryPath());
+    }
+    catch {
+        return { schema: REGISTRY_SCHEMA, repos: {} };
+    }
+    const repos = {};
+    if (!isJsonObject(parsed) || parsed['schema'] !== REGISTRY_SCHEMA)
+        return { schema: REGISTRY_SCHEMA, repos };
+    const stored = parsed['repos'];
+    if (!isJsonObject(stored))
+        return { schema: REGISTRY_SCHEMA, repos };
+    for (const slug of Object.keys(stored)) {
+        const entry = parseEntry(stored[slug]);
+        if (entry !== undefined)
+            repos[slug] = entry;
+    }
+    return { schema: REGISTRY_SCHEMA, repos };
+}
+/** The serialized form: the current schema, and the entries in slug order with a fixed field order. */
+function toJson(registry) {
+    const repos = {};
+    for (const slug of Object.keys(registry.repos).sort(compareSlugs)) {
+        const entry = registry.repos[slug];
+        if (entry === undefined)
+            continue;
+        repos[slug] = {
+            root: entry.root,
+            projectName: entry.projectName,
+            label: entry.label,
+            backend: entry.backend,
+            unitPath: entry.unitPath,
+            registered_at: entry.registered_at,
+        };
+    }
+    return { schema: REGISTRY_SCHEMA, repos };
+}
+/**
+ * Write the whole registry, **atomically**: a temp file in the same directory, then a rename.
+ *
+ * Same directory, so the rename is within one filesystem and therefore atomic — a reader mid-write
+ * sees the previous record or the new one and never a half-written line. It is the same protocol
+ * `hr_lane_publish` uses for `usage-state.json` in the generated `lib/harness-run-lib.sh`, and for
+ * the same reason.
+ *
+ * The temp name carries this process's pid: two writers with one pid cannot exist at the same time
+ * on one machine, so it is unique among concurrent writers, and a crashed run leaves at most one
+ * stale temp per pid rather than an accumulating pile. The mode is applied by an explicit `chmod`
+ * after the write as well as by `writeFileSync`'s own option, because that option is masked by the
+ * process umask and is ignored outright for a file that is already there — which a leftover temp
+ * from a crash would be. The directory is created and `chmod`ed on the same two-step reasoning
+ * (`core/writer.ts`'s `ensure-dir` commit, and the shell half's `mkdir -p` then `chmod 700`).
+ *
+ * A failure leaves the previous file untouched and removes the temp. The removal is `rmSync` on one
+ * file **without** `recursive`, so it cannot empty a directory even if it were aimed at one.
+ */
+function writeRegistry(registry) {
+    const dir = machineStateDir();
+    mkdirSync(dir, { recursive: true });
+    chmodSync(dir, MACHINE_DIR_MODE);
+    const temp = join(dir, `.${REGISTRY_FILENAME}.${process.pid}.tmp`);
+    try {
+        writeFileSync(temp, formatJson(toJson(registry)), { encoding: 'utf8', mode: REGISTRY_FILE_MODE });
+        chmodSync(temp, REGISTRY_FILE_MODE);
+        renameSync(temp, registryPath());
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch {
+            // The original failure is the one worth reporting; a temp file left behind is not.
+        }
+        throw error;
+    }
+}
+/** Refuse a path that is not absolute, before it becomes a record two commands later disagree on. */
+function assertAbsolute(field, value) {
+    if (!isAbsolute(value)) {
+        throw internal(`the repository registry was given a relative ${field} (${JSON.stringify(value)}), which would read differently depending on where a later command was run from`);
+    }
+}
+/**
+ * Register a repository, or replace its entry in place.
+ *
+ * The key is {@link repoSlug} of `entry.root`, derived **here** rather than taken from the caller,
+ * so a re-install over an existing repository can only ever land on that repository's own row and
+ * two checkouts can never collide. Every other entry in the file is preserved.
+ *
+ * It writes when it is called: see the module header's last paragraph, and do not call it under
+ * `--dry-run`.
+ */
+export function upsertRepository(entry) {
+    assertAbsolute('root', entry.root);
+    assertAbsolute('unitPath', entry.unitPath);
+    const current = readRegistry();
+    const repos = { ...current.repos, [repoSlug(entry.root)]: entry };
+    writeRegistry({ schema: REGISTRY_SCHEMA, repos });
+}
+/**
+ * Remove the named entries and report how many were there — the explicit prune, and the only removal
+ * in this module.
+ *
+ * A slug that is not registered is not an error: the caller of `daemon list --prune` passes what it
+ * graded stale, and a concurrent `daemon install` may legitimately have changed the file in between.
+ * When nothing matched, **nothing is written at all** — so a prune over an unreadable file leaves
+ * that file exactly as it is rather than replacing it with an empty one.
+ *
+ * It writes when it is called: see the module header's last paragraph.
+ */
+export function removeRepositories(slugs) {
+    const repos = { ...readRegistry().repos };
+    let removed = 0;
+    for (const slug of slugs) {
+        if (!Object.hasOwn(repos, slug))
+            continue;
+        delete repos[slug];
+        removed += 1;
+    }
+    if (removed === 0)
+        return 0;
+    writeRegistry({ schema: REGISTRY_SCHEMA, repos });
+    return removed;
+}
+/** True when something is at `path` and it is a directory. Any error reads as "not there". */
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Grade one entry. Reads the filesystem and probes git; changes neither.
+ *
+ * **The order of the two first checks is load-bearing, not cosmetic.** `probeRepoRoot` runs `git` with
+ * the candidate directory as its working directory, and spawning a process in a directory that is not
+ * there fails with `ENOENT` — which that probe reads as "git is not on PATH". So the root's existence
+ * is settled first, and the repository question is only ever asked of a directory that exists.
+ *
+ * A recorded root that exists and *is inside* a repository whose top level is some other directory is
+ * `not-a-repository`: the entry claims a repository root, and this path is no longer one. Comparing a
+ * `--show-toplevel` answer against a recorded value is comparing like with like, because the recorded
+ * value came from the same probe when the daemon was installed.
+ *
+ * When git is not on PATH, or refused to answer at all (`detected dubious ownership`), the repository
+ * question has no answer, so it is skipped and the entry is graded on the two axes that remain. Only
+ * git's own "not a git repository" grades the entry stale. Reporting every registered repository as
+ * broken because the machine running `daemon list` has no git, or will not read a root it does not
+ * own, would be a fault of the reader dressed up as a fault of the registry.
+ */
+function gradeEntry(entry) {
+    if (!isDirectory(entry.root))
+        return 'root-missing';
+    const probe = probeRepoRoot(entry.root);
+    if (probe.kind === 'not-a-repository')
+        return 'not-a-repository';
+    if (probe.kind === 'repository' && probe.root !== entry.root)
+        return 'not-a-repository';
+    if (!existsSync(entry.unitPath))
+        return 'unit-missing';
+    return 'ok';
+}
+/**
+ * Grade every entry — **the one place staleness is decided**, so `daemon list` and `doctor` cannot
+ * report the same machine differently.
+ *
+ * Sorted by slug rather than left in the file's own order, so a listing an operator reads twice reads
+ * the same way twice even if the file was hand-edited into some other order.
+ *
+ * It writes nothing and removes nothing; that is the module header's answer 2, and it is why this
+ * function is safe to call from `doctor`, whose published contract is that a run of it writes
+ * nothing at all.
+ */
+export function inspect(registry) {
+    const graded = [];
+    for (const slug of Object.keys(registry.repos).sort(compareSlugs)) {
+        const entry = registry.repos[slug];
+        if (entry === undefined)
+            continue;
+        graded.push({ slug, entry, state: gradeEntry(entry) });
+    }
+    return graded;
+}
+//# sourceMappingURL=registry.js.map

package/dist/machine/registry.js.map

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

package/package.json

@@ -0,0 +1,23 @@
+{
+  "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.",
+  "license": "Apache-2.0",
+  "author": "firu-daniel",
+  "homepage": "https://github.com/firu-daniel/autonomous-sdlc-harness",
+  "repository": { "type": "git", "url": "https://github.com/firu-daniel/autonomous-sdlc-harness.git" },
+  "type": "module",
+  "bin": { "autonomous-sdlc-harness": "./dist/cli.js" },
+  "files": ["dist", "scripts", "templates", "README.md", "LICENSE", "NOTICE"],
+  "engines": { "node": ">=20.11.0" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "pretest": "npm run build",
+    "test": "node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^20.14.0"
+  }
+}

package/scripts/README.md

@@ -0,0 +1,13 @@
+# scripts/
+
+The **daemon unit templates** the `daemon` subcommand renders — `daemon/launchd.plist.template` and `daemon/systemd.service.template` — and nothing else. They live here rather than under `templates/` because they are the one generated artifact that never lands in the adopting repository: the CLI reads them out of its own installed copy and writes the rendered unit into the account's home directory, whereas every subdirectory of `templates/` is an adopter-side home `init` writes *into*. The package's `files` field carries this directory into the tarball and the compiler's `include` (`src/**/*.ts`) leaves it alone. `plugin/scripts/` is a different thing again — the helpers an instruction or agent body calls by path — and that README states the split from the plugin side.
+
+**Where the outer-loop scripts went, and why.** An earlier version of this README had them executing from the installed package and named the conflict that made the location undecidable: this directory claimed them, while the shipped instruction corpus names three of them by their `<scripts_dir>/` destination, two of them as `bash <scripts_dir>/<name>.sh` invocations. Both could not be right, and the generated permission profile has to name one location or the other — an allow entry naming the location the corpus does not call fails exactly as silently as no entry at all, because in an unattended run a command matching neither `allow` nor `deny` parks with no diagnostic. **The resolution taken is the `scriptsDir` option**, the one this README recommended: the run watcher, its restart wrapper, the notifier and its stream formatter, and the commit / push / branch-refresh / worktree / cleanup wrappers ship as generator templates under `cli/templates/scripts/` (with the shared library they source at `cli/templates/scripts/lib/`), and `init` copies them verbatim into the adopter's configured `scriptsDir`. `cli/src/generators/outerLoopScripts.ts` is the single declaration of that set.
+
+Three things decided it, against the alternative of keeping them in the installed package and adding one absolute literal profile entry per script, built at run time from the package root:
+
+- **The corpus resolves unchanged.** Every `<scripts_dir>/`-prefixed invocation in the instruction corpus is already in the shape this resolution produces, so the port added no corpus edit at all; the package-relative alternative required changing the prefix at each of those sites. Reproduce the site list from the tree root with `grep -rn 'commit-on-branch\.sh\|push-branch\.sh\|autonomous-watcher\.sh' plugin/`.
+- **Coverage is a row, not a mechanism.** An agent-invocable row in the shipped table emits the three literal forms the profile generator already builds and tests — the repo-relative invocation, its repo-root-absolute twin and its sibling-worktree twin — gated so a script that was never written is never allow-listed. The alternative had to name each script **file** in an absolute entry, because a directory-prefix entry does not match even with a literal path (`docs/development.md` §3).
+- **The daemon's program stays inside the repository it works on.** `ExecStart` resolves as `<repoRoot>/<scriptsDir>/autonomous-watcher.sh`, inside the very checkout `WorkingDirectory` names, rather than at an `npx` cache path that can be evicted under a long-running service (`docs/cli.md` §9).
+
+The cost is recorded rather than hidden: a copied script is upgraded by re-running `init`, not by updating the package, and the `create-if-absent` re-run contract deliberately keeps an adopter's edited copy instead of replacing it (`docs/cli.md` §3). That is the price of the corpus, the profile and the unit file all naming one location.

package/scripts/daemon/launchd.plist.template

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  User LaunchAgent for the autonomous run watcher of {{projectName}}.
+
+  Rendered by `autonomous-sdlc-harness daemon install`, which writes it to
+  ~/Library/LaunchAgents/{{label}}.plist and loads it with `launchctl bootstrap gui/<uid>`.
+  It is a per-user agent and never a system daemon: it runs as the account that installed it, and
+  so has that account's keychain and agent-runner credentials, which is exactly what an unattended
+  run needs and what a system daemon would not have. Its PATH is not that account's — launchd
+  starts an agent from launchd's own environment and never from a login shell — so the unit
+  renders one in below.
+
+  Every value below is substituted at install time. This file carries no account name, no home
+  directory and no checkout path of its own, so the same template serves every adopter.
+
+  No comment in this file may contain a double hyphen, substituted values included: XML 1.0 §2.5
+  forbids one, and `cli/test/daemon.test.mjs` fails if one appears in a rendered unit.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>{{label}}</string>
+
+  <!-- The interpreter is named rather than left to the script's own shebang: an agent is
+       started with no shell, and naming it keeps the unit working for a watcher whose
+       executable bit did not survive a checkout. -->
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>{{watcherPath}}</string>
+  </array>
+
+  <key>WorkingDirectory</key>
+  <string>{{repoRoot}}</string>
+
+  <!-- The PATH the agent runs on. Without this key that is launchd's own
+       /usr/bin:/bin:/usr/sbin:/sbin, and a toolchain installed anywhere else — Homebrew, nvm,
+       ~/.local/bin — is not found: the watcher's package manager and its agent CLI both resolve
+       through PATH. `daemon install` renders the PATH of the shell that ran it; if that shell had
+       none, no key is rendered at all, because a PATH of "" is worse than launchd's four
+       directories. Re-run `daemon install` with the force flag when the toolchain moves. -->
+{{environment}}
+  <key>RunAtLoad</key>
+  <true/>
+
+  <!-- Restarted whenever it exits: a watcher that died between dispatches looks exactly like
+       one with nothing to do, and the run queue drains silently. -->
+  <key>KeepAlive</key>
+  <true/>
+
+  <!-- The watcher's own output, beside the per-run logs in the run-artifact tree. launchd
+       creates these files but not the directory above them, which `init` has already made. -->
+  <key>StandardOutPath</key>
+  <string>{{stateDirAbs}}/autonomous_logs/watcher.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>{{stateDirAbs}}/autonomous_logs/watcher.err.log</string>
+</dict>
+</plist>

package/scripts/daemon/systemd.service.template

@@ -0,0 +1,58 @@
+# User service unit for the autonomous run watcher of {{projectName}}.
+#
+# A documented template rather than a system unit. `autonomous-sdlc-harness daemon install`
+# renders it to ~/.config/systemd/user/{{label}}, and it is driven with `systemctl --user`
+# throughout — `--user daemon-reload`, then `--user enable --now {{label}}`. As a user unit it
+# runs as the account that installed it, and so has that account's secret store and agent-runner
+# credentials; installed system-wide it would have none of them. Its PATH is not that account's —
+# a user unit inherits the service manager's environment and never a login shell's — so the unit
+# renders one in below.
+#
+# The unit's name carries a slug of the repository it was installed from, so a second repository
+# on this machine installs its own watcher rather than overwriting this one. It is a concrete
+# file and not a `harness-watcher@.service` template unit: systemd resolves an instance name to a
+# literal file of that name before falling back to a template, and a template would have to reach
+# the checkout path through %i — the value this file renders in below instead.
+#
+# On a headless host, `loginctl enable-linger <account>` is what keeps a user unit running
+# while nobody is logged in. That is left to the operator deliberately: it changes how the
+# account behaves outside this harness.
+#
+# Every value below is substituted at install time — no account name, no home directory and no
+# checkout path is written into this file. The renderer escapes each value for the directive it
+# lands in: `%` is doubled everywhere, and the ExecStart path is quoted here and backslash-
+# escaped there, so a checkout holding a space is one command and not two. The two log lines
+# need systemd 240 or newer for `append:`; on anything older, drop them and read the watcher's
+# output from the journal.
+#
+# Prose written here to be shared with, or copied into, the launchd template must carry no double
+# hyphen: a `#` comment forbids nothing, and an XML comment there may not contain one.
+
+[Unit]
+Description=Autonomous SDLC harness run watcher for {{projectName}}
+
+[Service]
+Type=simple
+ExecStart=/bin/bash "{{watcherPath}}"
+WorkingDirectory={{repoRoot}}
+
+# The PATH the service runs on. Without this directive it is whatever the user manager was started
+# with, and the toolchain the outer loop runs — the agent CLI, the configured package manager —
+# need not resolve there. `daemon install` renders the PATH of the shell that ran it; if that shell
+# had none, no directive is rendered at all, because an empty PATH is worse than the manager's own.
+# The value is quoted because a PATH entry may hold a space, so a `"` or a `\` in one is backslash-
+# escaped by the renderer, and its `%` is doubled like every other value here. Re-run
+# `daemon install --force` when the toolchain moves.
+{{environment}}
+# Restarted whenever it exits: a watcher that died between dispatches looks exactly like one
+# with nothing to do, and the run queue drains silently.
+Restart=always
+RestartSec=5
+
+# The watcher's own output, beside the per-run logs in the run-artifact tree, which `init` has
+# already created.
+StandardOutput=append:{{stateDirAbs}}/autonomous_logs/watcher.out.log
+StandardError=append:{{stateDirAbs}}/autonomous_logs/watcher.err.log
+
+[Install]
+WantedBy=default.target

package/templates/README.md

@@ -0,0 +1,15 @@
+# templates/
+
+The generator templates `init` copies into an adopted repository. Nothing here is compiled — the package's `tsconfig.json` includes only `src/**/*.ts` — and nothing here is loaded at runtime by the plugin; these files are source material `init` writes out at adoption time. Most are rendered with configured values substituted in, but the outer-loop family under `scripts/` carries no `{{token}}` at all and is copied byte for byte, because each of those scripts reads `harness.config.json` **at run time** rather than carrying a value frozen in when `init` ran — `scripts/README.md` states that rule and `cli/src/generators/outerLoopScripts.ts` implements it. Roadmap items 6, 7, 13 and 14 fill the tree and all four have shipped, and each subdirectory's README names its own content owner and its writer; the package's `files` field carries the tree into the published tarball. One subdirectory per adopter-side home:
+
+| Template subdirectory | Adopter-side home `init` writes to |
+|---|---|
+| `claude/` | `.claude/` in the adopter's repo |
+| `repo/` | the adopter's repo root |
+| `githooks/` | the configured `githooksDir` |
+| `scripts/` | the configured `scriptsDir` |
+| `state-dir/` | the configured `stateDir` |
+
+**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.
+
+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.

package/templates/claude/CLAUDE.md

@@ -0,0 +1,54 @@
+# {{projectName}}
+
+{{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._
+
+---
+
+## File naming conventions
+
+| Type | Pattern | Example |
+|---|---|---|
+| _(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._
+
+---
+
+## Context files (read on demand)
+
+This file is auto-loaded into every agent, which is why it deliberately holds almost nothing. Everything else is loaded on purpose: **read the relevant file before starting work in that area — do not load them all upfront.** An always-loaded file carrying every rule this project has would spend every agent's context budget on every turn, and the table below exists so that it does not.
+
+| When working on… | Read |
+|---|---|
+{{routingRows}}
+
+> **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.
+
+---
+
+## Agent authoring rules
+
+**Every agent you add under `.claude/agents/` MUST declare a `tools:` allowlist, and that allowlist MUST omit the browser-automation tool namespaces unless the agent is the one that drives a browser for the interactive test phase.** That agent's own allowlist grants them explicitly, and it is the only one that may.
+
+The allowlist is the whole mechanism, deliberately: a global deny is evaluated before any allow and cannot be overridden, and a subagent's `tools:` allowlist compiles into *narrowing* deny rules in the same pool rather than into overriding allow ones — so a namespace-wide deny would revoke the test agent's own grant as well. An agent added with no `tools:` field inherits the full default tool set and silently re-opens browser access, so a review rejects it.
+
+---
+
+## Where a change request runs
+
+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.
+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.
+
+All four hold: read `.claude/harness-task-offer.md`, at the root of the checkout you are running in, and follow it — it owns the question, the four options and what each answer does — and ask nothing before reading it. If that file cannot be read, make no offer and carry out the request in this session.
+
+---
+
+_Written by `autonomous-sdlc-harness init`, and yours from there on: edit it freely, a re-run keeps your copy._

package/templates/claude/README.md

@@ -0,0 +1,5 @@
+# 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.
+
+**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/api.md

@@ -0,0 +1,29 @@
+# Request-handling layer
+
+> **Read this when:** the change is about an endpoint this project serves — its route, its request and response shapes, its status codes, its authentication or its validation. **Skip when:** the change is a rule that would hold however it was invoked; that belongs to the layer owning the rules.
+
+**Purpose.** What every endpoint here does before it does anything else, and how thin a handler is required to stay.
+
+**What belongs here**
+
+- How a route is declared and registered, which file it lives in and how that file is named.
+- The validation step every handler runs before it touches anything else, and where the request shape it validates against is declared.
+- Authentication and authorisation: where each check is made, and what a caller who fails one gets back.
+- The response contract — the success shape, the error shape, and which status code carries which outcome — so two endpoints do not report the same failure two ways.
+- What counts as a breaking change to a published endpoint, and how a compatible one is introduced.
+
+**Rule that holds whatever the framework is:** a handler validates, delegates and formats — nothing else. A rule written inside a handler is unreachable from every other entry point this project has, so the scheduled job, the administrative tool and the next endpoint each grow their own copy of it, and the copies disagree before anyone notices there are several.
+
+**One generic example**
+
+```
+POST /orders
+  1. validate the request against the declared shape — refuse before anything else runs
+  2. authorise this caller for this action
+  3. delegate to one unit of work in the layer that owns the rules
+  4. map its result onto the response shape and the status code
+```
+
+_Run `{{analyzeInvocation}}` to fill this in from this repository's own code, or replace everything above with this project's own request-handling rules; either way this file is yours from here on and a re-run of `autonomous-sdlc-harness init` keeps your copy — and if you write it by hand, the marker on the last line goes with it._
+
+<!-- harness:unfilled -->