autonomous-sdlc-harness 0.1.0

package/templates/claude/settings.autonomous.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_README": [
+    "UNATTENDED SETTINGS PROFILE - written by `autonomous-sdlc-harness init`, and yours from there on: edit it freely, a re-run keeps your copy. It is selected per run with `--settings .claude/settings.autonomous.json` and is never installed as the interactive default, so dropping that flag reverts every grant below with nothing to undo.",
+    "COMPLETENESS IS LOAD-BEARING: in print mode a tool that is neither allowed nor denied stalls rather than prompting, so `allow` has to cover the whole flow end to end. A gap surfaces as a hang, not as an error - add the missing entry here rather than relaxing the permission mode.",
+    "SCRIPT PATHS ARE UNQUOTED LITERALS: the guard matches the raw command string, so a quoted path fails a `*.sh` match, falls through to a prompt and stalls an unattended run. Never put quotes around one of the wrapper paths below.",
+    "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 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.",
+    "EVERY FILE RULE MARKS AN ABSOLUTE PATH WITH A `//` PREFIX - `Read`, `Edit` AND `Write` ALIKE - AND THE PATH BRINGS ITS OWN LEADING SLASH: the entries `Read(/{{repoRoot}}/**)`, `Edit(/{{repoRoot}}/**)` and `Write(/{{repoRoot}}/**)` above are that prefix immediately followed by the absolute path {{repoRoot}}, which is why each carries two slashes and not three. One tool syntax governs all three: a rule content starting with `//` is anchored at the filesystem root, while a single leading `/` is resolved relative to the root of the settings file the rule came from, so a one-slash rule names a path nobody has and matches no file. Adding a slash of its own to a path that already starts with one gives the same silent nothing from the other side.",
+    "NO `hooks` KEY, DELIBERATELY: the harness plugin ships its own guard hooks; they fire from the plugin, resolve their own root and append to whatever hooks you already have. Writing them here as well would run each guard twice and would replace your own hook configuration. This omission is a decision, not an oversight.",
+    "`deny` IS A FLOOR, NOT A PREFERENCE: it is evaluated before `allow` and cannot be overridden by one, which is what makes a broad `allow` beside it safe - the destructive commands below stay refused however widely the rest is granted. Add to it freely; do not weaken it, and do not try to re-enable one of its entries by adding an allow rule, because the allow will not win. What a deny entry holds back is what its pattern literally matches: each is a PREFIX match anchored at the START of the command string, so `Bash(git branch -D:*)` refuses `git branch -D <x>` and does not fire on the same words inside a compound such as `git status && git branch -D <x>`. It does not fire on `git -C <dir> branch -D <x>` either - the directory sits ahead of the words the pattern anchors on. Both gaps are closed on the plugin side rather than here - the guard hooks that auto-allow a compound, or a single directory-scoped statement, refuse to vouch for a piece that deletes, renames or overwrites a branch ref, whichever safe prefix it otherwise matches, and they parse the `-C` form rather than matching it as a prefix - so keep the two in step when you add an entry that names one of those prefixes. It is also why no `Bash(git -C:*)` entry is added above: it would grant the `-C` spelling of every verb this floor refuses, with no deny entry able to fire on it.",
+    "NO BROWSER-NAMESPACE ENTRY IN `deny`: a deny is evaluated before any allow and cannot be overridden, so denying the browser-automation namespaces would revoke the interactive-test agent's own grant along with everyone else's. That closure is done per agent, by the `tools:` allowlist on each agent definition - the one agent that drives a browser lists those tools and no other agent does."
+  ],
+  "permissions": {
+    "allow": [
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git show:*)",
+      "Bash(git ls-files:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git rev-list:*)",
+      "Bash(git branch:*)",
+      "Bash(git remote get-url:*)",
+      "Bash(git worktree:*)",
+      "Bash(git fetch:*)",
+      "Bash(git add:*)",
+      "Bash(git stash:*)",
+      "Bash(git commit:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(sed:*)",
+      "Bash(awk:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(wc:*)",
+      "Bash(jq:*)",
+      "Bash(mkdir -p:*)",
+      "Bash(pwd)",
+      "Bash(echo:*)",
+      "Edit(/{{repoRoot}}/**)",
+      "Edit(/{{worktreeGlob}}/**)",
+      "Write(/{{repoRoot}}/**)",
+      "Write(/{{worktreeGlob}}/**)",
+      "Read(/{{repoRoot}}/**)",
+      "Read(/{{worktreeGlob}}/**)",
+      "Bash({{scriptInvocation}}:*)",
+      "Bash(bash {{scriptsDirAbs}}/{{scriptFile}}:*)",
+      "Bash(bash {{worktreeGlob}}/{{scriptPath}}:*)",
+      "Bash({{outerLoopInvocation}}:*)",
+      "Bash(bash {{scriptsDirAbs}}/{{outerLoopFile}}:*)",
+      "Bash(bash {{worktreeGlob}}/{{outerLoopPath}}:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(git branch -D:*)",
+      "Bash(git branch -d:*)",
+      "Bash(git branch -M:*)",
+      "Bash(git branch -m:*)"
+    ],
+    "ask": [
+      "Bash(git checkout:*)",
+      "Bash(git pull:*)",
+      "Bash(git push:*)",
+      "Bash(git reset:*)",
+      "Bash(git merge:*)",
+      "Bash(git rebase:*)",
+      "Bash(git restore:*)",
+      "Bash(git revert:*)",
+      "Bash(git cherry-pick:*)",
+      "Bash(git tag:*)",
+      "Bash(git rm:*)",
+      "Bash(git mv:*)",
+      "Bash(git clean:*)",
+      "Bash(git remote add:*)",
+      "Bash(git remote remove:*)",
+      "Bash(git remote set-url:*)",
+      "Bash({{deployInvocation}}:*)",
+      "Bash(bash {{scriptsDirAbs}}/{{deployFile}}:*)",
+      "Bash(bash {{worktreeGlob}}/{{deployPath}}:*)"
+    ],
+    "defaultMode": "acceptEdits",
+    "additionalDirectories": ["{{stateDirAbs}}"]
+  },
+  "model": "{{agentModel}}"
+}

package/templates/claude/settings.autonomous.qa.json

@@ -0,0 +1,36 @@
+{
+  "_README": [
+    "THE BROWSER HALF, ADDED ONLY WHEN TWO CONDITIONS BOTH HOLD - THE INTERACTIVE TEST PHASE IS ENABLED, AND ITS DRIVER IS THE BROWSER ONE: the `enabledMcpjsonServers` key, the `mcp__` entries at the end of `allow` and the port and liveness probes beside them were merged in because `phases.qa` was true AND `qa.driver` was `web-playwright` when this file was generated. Fail either condition and none of them is written at all, so an adopter who never drives a browser pays neither the browser tool schemas in every session's context nor a launched browser process. With a MOBILE driver that is not merely a saving: the mobile variants of the interactive test agent are declared-not-implemented in this release and carry built-ins-only tool allowlists, so a server started here would be one no agent could ever call - which is why the repository's own `.mcp.json` is withheld in the same run rather than left declaring servers this profile never starts. Turning the phase on in `harness.config.json`, or changing `qa.driver` to `web-playwright`, and re-running `autonomous-sdlc-harness init` does NOT rewrite this file — it is yours once written; copy the entries in from a fresh generation, or re-run it with --force, which takes a .bak first.",
+    "BOTH KEYS ARE NEEDED AND THEY DO DIFFERENT THINGS: `enabledMcpjsonServers` STARTS the browser servers the repository's own MCP wiring declares, while the `mcp__` entries in `allow` gate which of their tools may run. A fresh working copy has no local settings file to enable a server in, and this profile is the only settings source an unattended run loads - without the enablement the servers never start, the pre-allowed tools do not EXIST, and the phase stalls rather than failing, because an un-loaded tool in print mode stalls instead of prompting. Enabling a server is not itself a capability grant: removing a tool entry below removes the capability while leaving the server running.",
+    "THE ALLOWED TOOL SET IS THE ONE THE PHASE DRIVES - navigation, snapshot, console, network, click, type, select, wait, screenshot, tracing and one client-storage escape hatch - and nothing wider. That last one is `mcp__playwright__browser_evaluate`, and it is in the base set because a test that has to start from a known client-storage state has no other route to one: the interactive-test agent grants it in its own `tools:` allowlist and documents the single way it goes wrong (an unbounded `await` inside it hangs, because the tool carries no timeout of its own), and withholding it does not make a test safer - it makes the phase STALL at that test's first step, per the completeness line above. One tool that agent may call is deliberately NOT here: `mcp__playwright__browser_route`, which fakes the network the application under test talks to. Granting an agent that is an adopter's decision rather than a default - add the entry if your interactive tests stub backend responses, and until you do, a test that reaches for it stalls rather than failing. Any other tool a test needs gets one more entry here rather than a namespace wildcard, because these entries are what an adopter reads to know what the phase can do to a running application.",
+    "THE PORT PROBE IS ALLOW-LISTED AS A COMMAND PREFIX RATHER THAN AS ONE PORT: the phase serves its own instance on the configured port seed and moves past it when that port is taken, so an entry naming a single port would leave the very next probe matching neither `allow` nor `deny`. The dev-server wrapper itself is not re-declared here - it is one of the wrapper scripts in `allow` above, listed there in all three forms a caller may use, and a second declaration of it here is how the two spellings drift apart. THE LIVENESS PROBE BESIDE IT IS THE SAME CLASS, AND IT IS `ps -p` RATHER THAN `ps` ON PURPOSE: it exists for the one step that owns the dev server - which confirms the process it started has not exited before it trusts a poll that answered, because a URL answering on a port says nothing about WHOSE server answered - so the entry grants a query about one pid and not a listing of every process on the machine; that step grades it by EXIT STATUS and never by parsing its output, which is what keeps a platform-dependent output shape out of the contract; it sits in this fragment rather than in the base profile, so a repository that never drives the phase is not widened by it; and this file is written create-if-absent, so a fragment generated before this line existed does not gain it on a plain re-run - add the one line by hand, or take it from a --force run, which writes a .bak first; the bare `ps -p <pid>` form has been measured to run even on a profile carrying no `ps` entry at all, so this line is the guarantee rather than the only route, and the phase's own E.0 step 3 is where what to do with a liveness check that cannot run is stated.",
+    "THE PHASE'S OWN HELPER SCRIPTS ARE NOT ALLOW-LISTED HERE - ADD THEM BY HAND, ONCE: the port, dev-server and QA-user helpers this phase runs ship inside the harness plugin and are invoked as `bash ${CLAUDE_PLUGIN_ROOT}/scripts/<name>.sh`. Keeping the token in an entry rescues nothing, because the guard matches the raw command string and a substitution anywhere in that string defeats the match however the entry is worded (measured against `claude` 2.1.227, with the limits of that measurement recorded in the harness repository's own `docs/development.md` section 3). So each line you add must name a RESOLVED root - `Bash(bash <resolved plugin root>/scripts/<name>.sh:*)`, in the same unquoted form the wrapper entries above use, naming the script FILE rather than the directory holding it, because a directory-prefix entry was measured not to match either. That form is what a resolved command meets, whatever kind of file names the helper - an adoption run on 2026-08-26 reached three of them through it and stalled at none - but WHICH root it resolves to does depend on that: a helper named in an instruction file is resolved by the agent itself, one named in an agent definition body has the token substituted by the runtime, and on a directory-sourced marketplace those two were measured to be different directories. Add the line once per helper per root where they differ. `autonomous-sdlc-harness init` does not generate these lines, and an unknowable root is not the reason - it is recorded per plugin in the agent runner's own `installed_plugins.json`. What stops the generator is that `init` may run before the plugin is enabled, and that the path carries the plugin VERSION, so a line written once goes silently stale on the next upgrade. The resolving is therefore done at check time instead: run `npx autonomous-sdlc-harness doctor` and paste what its `plugin-permissions` check prints - it re-resolves both roots on every run and names each missing line exactly, grouped by root. The helper names are declared once, in the plugin's own `scripts/README.md`, and are deliberately not repeated here. Until those lines exist the phase STALLS rather than failing, per the completeness line above. This file is written create-if-absent, so the lines you add survive every later `autonomous-sdlc-harness init`: a plain re-run keeps the whole file, and `--force`, the one run that regenerates it from the template after a .bak, re-reads it first and CARRIES FORWARD every `permissions.allow` entry naming a plugin root this machine still resolves - the lines above among them. The one it does not carry is an entry naming a root it no longer resolves, which is what a plugin upgrade leaves behind: that run names each entry it dropped, and `doctor` names them on every run after it. That exception applies only where the plugin DOES resolve on the machine running it - where none of its roots resolve at all, nothing there can tell a stranded entry from one you pasted a minute ago, so the run carries every absolute entry outside the checkout forward UNVERIFIED and says so in those words."
+  ],
+  "enabledMcpjsonServers": ["playwright", "chrome-devtools"],
+  "permissions": {
+    "allow": [
+      "mcp__playwright__browser_navigate",
+      "mcp__playwright__browser_snapshot",
+      "mcp__playwright__browser_console_messages",
+      "mcp__playwright__browser_network_requests",
+      "mcp__playwright__browser_network_request",
+      "mcp__playwright__browser_click",
+      "mcp__playwright__browser_type",
+      "mcp__playwright__browser_select_option",
+      "mcp__playwright__browser_wait_for",
+      "mcp__playwright__browser_take_screenshot",
+      "mcp__playwright__browser_evaluate",
+      "mcp__chrome-devtools__navigate_page",
+      "mcp__chrome-devtools__take_snapshot",
+      "mcp__chrome-devtools__click",
+      "mcp__chrome-devtools__fill",
+      "mcp__chrome-devtools__fill_form",
+      "mcp__chrome-devtools__wait_for",
+      "mcp__chrome-devtools__performance_start_trace",
+      "mcp__chrome-devtools__performance_stop_trace",
+      "mcp__chrome-devtools__performance_analyze_insight",
+      "Bash(lsof -ti:*)",
+      "Bash(ps -p:*)"
+    ]
+  }
+}

package/templates/githooks/README.md

@@ -0,0 +1,3 @@
+# githooks/
+
+The caller-agnostic pre-push guard `init` writes into the configured `githooksDir` before pointing `core.hooksPath` at that directory. The guard refuses a push to a protected branch whoever invokes it — an agent, a wrapper script, or a human at a terminal — which is what makes it a last line of defence rather than a convention. That is caller-agnosticism *within git*, and the whole of the claim: git runs the hook on every push **git** performs, so a tool that implements push against the git backend itself, as `jj git push` does, performs no git push and runs no git hook. `doctor`'s `jj-repository` check reports that where it applies, and names what covers such a push: the session-level `PreToolUse` protected-branch guard, which sees it and refuses one whose target is **named**, and the forge-side branch ruleset, which is the only true floor and the only cover for a `jj git push` that names no bookmark — that form carries no target for the guard's explicit-target test and cannot trip its HEAD test either, since jj leaves `HEAD` detached. The set it protects is the adopter's: `protectedBranches` (else that key's schema default) unioned with `defaultBranch`, the same set `hr_protected_patterns` in the shared script library resolves for the git wrappers. The two differ in *when*: the wrappers re-read `harness.config.json` on every call, while the hook is `create-if-absent` and carries the set substituted into its `case` label when `init` wrote it, so an edit to `protectedBranches` reaches the hook only at `init --force` (or after deleting the hook and re-running `init`) and until then the two enforce different sets. A third run re-renders it as a *consequence* rather than as a way to change the set: `init --reset-config` rebuilds `harness.config.json` itself, and re-renders the hook from the rebuilt file when the `case` label the hook carried no longer matches the set that file resolves — after a `.bak`, and never when the label cannot be read. It is not a route to reach for deliberately: the rebuild takes the whole config from detection and the flags, so every hand-set value goes with it. A push is judged by the `case` label in the written file, because that is the file git runs. Roadmap item 13 owns the writer.

package/templates/githooks/pre-push

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Caller-agnostic pre-push BACKSTOP, written by `autonomous-sdlc-harness init` into the
+# configured `githooksDir` - which init then points `core.hooksPath` at, so the hook
+# travels with the checkout. Yours from there on: edit it freely, a re-run keeps your copy.
+#
+# WHAT IT DOES: refuses a push whose TARGET ref is a protected branch, whoever invoked git -
+# a person at a terminal, a wrapper script, or an unattended run - because git itself runs
+# this hook on every push GIT PERFORMS, including one started by a subprocess of some other
+# program. A guard that inspects the command an agent submitted sees only that one string,
+# so a push spawned indirectly never re-enters it. This hook closes that gap, which is what
+# makes it a last line of defence rather than a convention. Caller-agnostic WITHIN GIT is
+# the whole of that claim, and the fourth bypass below is the caller it does not reach.
+#
+# IT IS HONESTLY BYPASSABLE ON-BOX - `git push --no-verify`, re-pointing or unsetting
+# core.hooksPath, deleting this file, and pushing with a tool that implements push against
+# the git backend itself instead of running git (`jj git push` in a colocated jj repository
+# performs no git push and therefore runs no git hook - measured on one repository, one
+# hook, seconds apart) all skip it - so it is a backstop, not a floor. The only true floor
+# is a rule enforced by the host the repository is pushed to. This hook is what protects the
+# branch until there is one, and once there is one it is what reports the refusal locally
+# rather than after a round trip.
+#
+# THE PROTECTED SET COMES FROM CONFIGURATION, not from a list baked into this script: the
+# `case` pattern below was substituted, when init wrote this file, from `protectedBranches`
+# in harness.config.json (or that key's schema default when it is absent) UNIONED WITH
+# `defaultBranch` - so the branch work merges back into is in the set whatever the list
+# says, and an empty list means exactly that one branch. `case` patterns are globs, so one
+# entry like `release/*` protects a whole namespace. TO CHANGE THE SET: edit the `case`
+# pattern below and put the same set in `protectedBranches` - or edit that key and re-run
+# `init --force`, which writes the hook again from the config in effect after copying this
+# file to a .bak beside it, so the old set stays readable there. `--force` overwrites
+# generated files but never harness.config.json, which init reads on every run, so a set
+# that lives only in that file is the set this hook is re-rendered from. Without `--force`,
+# delete this file and re-run `init`: a re-run keeps a hook that is already here, so
+# deleting it is the part that makes the re-run re-render it. A third run re-renders this
+# file as a CONSEQUENCE rather than as a way to change the set - `init --reset-config`
+# rebuilds harness.config.json itself, and re-renders this hook from the rebuilt file when
+# the `case` label here no longer matches the set that file resolves, after copying this
+# file to a .bak beside it and never when the label cannot be read at all. Do not reach for
+# it to change the set: it rebuilds the whole config from detection and the flags, so every
+# hand-set value goes with it. Either way the union holds:
+# leaving `defaultBranch` out of `protectedBranches` does not take it out of a re-rendered
+# `case` pattern, so only a hand edit here can drop it and the next re-render puts it back.
+# Never change only one of the two, because the set that is actually enforced on a push is
+# the one in this file.
+#
+# GIT'S CONTRACT: the hook is invoked as `pre-push <remote-name> <remote-url>` and is fed
+# one line per ref on stdin - `<local-ref> <local-sha> <remote-ref> <remote-sha>`. The check
+# is on <remote-ref>, the push TARGET, with `refs/heads/` stripped: `HEAD:main`,
+# `feature:refs/heads/main` and `origin main` all arrive as the same target ref on stdin, so
+# matching that one field covers every spelling and the command line is never re-parsed.
+#
+# `set -uo pipefail`, and deliberately NOT `-e`: a glitch in this script has to fail SAFE
+# toward allowing a legitimate push to an unprotected branch rather than blocking one.
+
+set -uo pipefail
+
+# The happy path is pure string matching on the stdin lines - no git subprocess at all.
+# Empty stdin, or no protected target among the refs, falls through to the exit 0 below.
+while read -r local_ref local_sha remote_ref remote_sha; do
+  # Strip the refs/heads/ prefix to get the bare target branch name.
+  target="${remote_ref#refs/heads/}"
+
+  case "$target" in
+    {{protectedBranchesCase}})
+      echo "pre-push: refusing to push to protected branch '$target' - land the change through a pull request" >&2
+      exit 1
+      ;;
+  esac
+done
+
+exit 0

package/templates/repo/README.md

@@ -0,0 +1,3 @@
+# repo/
+
+The files `init` writes at the adopter's repository root, stored dot-less per the naming rule in the parent README: the git attributes and ignore templates, and the MCP server wiring for browser automation. `gitignore.qa` is a **fragment** of `gitignore` rather than a fourth file — the ignore rules for what the browser half of a run leaves in the working copy, rendered into the parent template only under the same `browserWiringApplies` gate as the MCP wiring, on the pattern `claude/settings.autonomous.qa.json` sets. It carries its own comments because they are gated with it: a repository that drives no browser must not carry prose explaining rules it does not have. Roadmap item 13 owns the writer. The MCP wiring template is written **only when the QA phase is enabled and its `qa.driver` is `web-playwright`**, so an adopter who never runs browser QA pays neither the browser tool schemas in every session's context nor a launched browser process — which is why it is a conditional write rather than part of the unconditional root set. A **mobile** driver gets a note and no file, for a second reason: the two mobile variants of the interactive test agent ship declared-not-implemented with built-ins-only tool allowlists, so a declared server would be wiring nothing can ever start. The permission profile's interactive-test fragment is gated on the same condition and in the same run — the profile names the servers it starts and this file declares them, so gating one side alone leaves the two disagreeing.

package/templates/repo/gitattributes

@@ -0,0 +1,16 @@
+# Written by `autonomous-sdlc-harness init`, and yours from there on: edit it freely, a
+# re-run keeps your copy.
+#
+# Line-ending normalisation only. Everything else a repository puts in this file - diff
+# drivers, merge strategies, linguist hints, filters - is a project decision the harness
+# has no opinion about, so it starts empty and you add to it.
+
+# Store every text file with LF whatever the contributing machine writes it with.
+* text=auto
+
+# ...and check the executable assets out with LF on every platform. A script is run by
+# the interpreter named on its `#!` line, and a CR at the end of that line is read as
+# part of the interpreter's name: a CRLF checkout fails with "bad interpreter" or
+# "no such file or directory", neither of which mentions a line ending.
+*.sh text eol=lf
+{{githooksDir}}/* text eol=lf

package/templates/repo/gitignore

@@ -0,0 +1,61 @@
+# Machine-local files this repository names by path but never commits. Each path is a
+# value in harness.config.json, so it is the same for everyone who clones, while the file
+# it names never leaves the machine. Where one of these has a committed `.example`
+# sibling, that sibling is what a fresh clone copies from. The client env file is the one whose
+# DIRECTORY is the configured value (`appDir`) while its name is fixed: setup-worktree.sh symlinks
+# it into every working copy it bootstraps, so without this rule every fresh worktree opens with an
+# untracked entry. What is ignored is the file and never the directory, so a committed
+# `.env.example` beside it stays committable.
+{{pushEnvPath}}
+{{qaCredentialsPath}}
+{{clientEnvPath}}
+# The per-machine settings file the agent runner writes beside the committed profiles.
+.claude/settings.local.json
+# The presence-only marker one user's "don't ask again" answer writes to silence the change-request
+# offer. It lives at the main worktree's root and is checked there from every worktree of this
+# checkout, so one answer covers them all - its existence is the whole signal, so it has no
+# contents to commit.
+.claude/harness-no-offer
+# The run daemon's transcripts, event logs and run registry are machine-local. The
+# directory itself is committed, because its README is the contract for what belongs in
+# it, so the contents are ignored and that one file is excepted - an ignore rule on the
+# directory would take the README with it, and git cannot re-include a file whose parent
+# directory is excluded.
+{{logsGlob}}
+{{logsReadmeException}}
+# The unattended loop's stop, pause and dispatch-count control files, written flat at the root of
+# the run-artifact tree while a run is in flight. The tree around them is committed, so one
+# `git add` of it would take whichever exist at that moment - and a committed STOP halts every run
+# for everyone who clones, at a step whose own instruction forbids deleting the file.
+{{runControlArtifacts}}
+# The questions a parked run asks and the answers it is given are machine-local, while the
+# directory's README is the committed contract for the exchange - so the contents are ignored and
+# that one file is excepted, exactly as for the log directory above. A question sits one level
+# further down, under a <branch> subdirectory, which this glob covers with everything else beneath
+# the directory. On a repository whose ignore file was generated before this pair existed: the
+# managed block is only ever added to and never pruned, so the older whole-directory rule for this
+# channel - the line ending `/clarifications/` - is still in the file and has to be DELETED BY HAND,
+# and so do the two comment lines that stood above it, which state that this channel has no committed
+# README and are wrong now that it has one. While that rule stands the exception cannot take effect,
+# wherever the two sit relative to each other, because git cannot re-include a file whose parent
+# directory is excluded - `doctor`'s `ignore-rules` check reports that state and names every line to
+# delete.
+{{clarificationsGlob}}
+{{clarificationsReadmeException}}
+# The drop point the unattended loop takes its work from. The prompts left in it are machine-local
+# and its README is the committed contract for what belongs there, so the contents are ignored and
+# that one file is excepted, exactly as for the log directory above.
+{{inboxGlob}}
+{{inboxReadmeException}}
+# The throwaway files an agent runs a probe or a mutation check from. They are written to be executed
+# once and deleted, never to be committed or read back, while the directory's README is the committed
+# contract for that - so the contents are ignored and that one file is excepted, exactly as for the
+# log directory above.
+{{scratchGlob}}
+{{scratchReadmeException}}
+# The backup `config set` copies the configuration to before every write, and the one .bak an
+# adopter gets without asking for it: applying a layer split is the documented path, so without this
+# rule a wired repository carries an untracked file from its first `config set` onward. The leading
+# slash anchors it at the repository root, the only place the configuration is written.
+/{{configBackupFile}}
+{{qaBrowserArtifacts}}

package/templates/repo/gitignore.qa

@@ -0,0 +1,25 @@
+# What the browser half of a run leaves in the working copy. These rules and these comments are
+# rendered only where a browser is actually driven - the interactive-test phase on AND its driver
+# the browser one - because only that driver starts an MCP server, so a repository that drives none
+# carries neither the rules nor prose explaining rules it does not have.
+# The browser server's own output directory, created at the repository root: screenshots, traces and
+# saved sessions. Ignored as a whole directory, unlike the run-artifact directories above - nothing
+# commits a contract file into it, so there is no README a directory rule would take with it, and a
+# re-run writes its own.
+.playwright-mcp/
+# The second pinned browser server writes no fixed project-local directory: it takes a temporary,
+# auto-cleaned user-data-dir by default. This rule is a DEFENSIVE catch if one is ever pointed here
+# (e.g. via an --output-dir flag at run time) rather than a directory the harness knows is written.
+# It costs nothing while the directory never appears, and a re-run neither creates nor needs it.
+.chrome-devtools-mcp/
+# Where the interactive-test agent is told to send a screenshot. It sits inside the run-artifact
+# tree, so an unattended run's launch check tolerates it as a <state_dir> artifact even if this rule
+# is ever dropped. Machine-local evidence of one run: no contract file is committed under it, and a
+# re-run takes its own screenshots.
+{{qaArtifactsDir}}
+# A screenshot the browser server wrote at the repository ROOT under a bare name, because it
+# sanitized the filename it was given rather than honouring the subdirectory in it. DEFENSIVE in the
+# same sense as the rule two above: it costs nothing while the file never appears, and a re-run
+# neither creates nor needs it. The leading slash anchors it at the root and `.png` narrows it to the
+# one artifact kind, so a committed `qa_`-named image in a subdirectory is untouched.
+/qa_*.png

package/templates/repo/mcp.json

@@ -0,0 +1,17 @@
+{
+  "_comment": "Browser wiring for the interactive test phase, written by `autonomous-sdlc-harness init` and merged rather than overwritten on a re-run: a server you add here survives, and one of these two is re-added only if it is missing. THE TWO SERVERS ARE SEPARATE BROWSER INSTANCES - each launches and drives its own browser, so a page one of them has navigated or signed in is not visible to the other, and a test that needs both drives each of them into the state it needs. BOTH RUN --isolated because each package otherwise defaults to one fixed persistent profile directory: a second instance started against a profile already in use refuses to launch, which is a failure that surfaces only when two runs overlap. THE VERSIONS ARE PINNED DELIBERATELY - a browser-automation server's tool names and flags change between releases, and an unpinned fetch would change what the phase can do without any edit here. Raise a pin as its own change, and re-check the tool names allow-listed in the generated permission profile when you do. NEITHER PACKAGE IS INSTALLED BY init - the `npx -y` above fetches each pinned spec from the registry the first time the interactive-test phase runs, so a machine that is offline, behind a proxy, or on a mirror that does not carry those exact versions fails at that first dispatch rather than at setup; `npx autonomous-sdlc-harness doctor --check-registry` answers it beforehand.",
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@0.0.75", "--isolated"],
+      "env": {}
+    },
+    "chrome-devtools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@1.1.1", "--isolated"],
+      "env": {}
+    }
+  }
+}

package/templates/scripts/README.md

@@ -0,0 +1,5 @@
+# scripts/
+
+The project-command wrapper scripts `init` writes into the configured `scriptsDir`: type-check, test and dev-server, configured through `commands.*` in `harness.config.json`, and deploy, configured through `deploy.command` on the separate `deploy` object — so no build tool and no hosting provider is hardcoded anywhere in the harness. They exist as scripts rather than as raw command lines because an unattended run's permission profile can allow-list a literal script path far more safely than an arbitrary command, which is why `commands.<key>` holds the **wrapper invocation** `bash <scriptsDir>/<name>.sh` — the literal the profile allow-lists — while the **raw** command line lives inside the script. Which raw line that is follows one precedence, and it is what keeps the pair from being circular: a raw command line already sitting in `commands.<key>` wins, because an adopter who edited it there meant it — and that state is **reported** rather than silently blessed, since the raw line is not the value the permission profile allow-lists: `init` names it as it writes the wrapper from it, `config set` names it as the value is stored, and `doctor`'s `command-wrappers` check grades it on every later run; otherwise, when that key holds this wrapper's own invocation — the normal state after a first `init` — the body is the line stack detection produced; and when neither resolves, the body names what to fix — the key to set, or for `deploy`, which detection never supplies, this script itself — and exits non-zero rather than appearing to have run a check it never ran. Two states get no wrapper at all, and therefore no allow entry: a key still holding the placeholder `init` writes for a command it could not detect, and `commands.typecheck` holding the `<none>` sentinel — the first is unfinished and is the one that asks the adopter to do something about it, the second is the answer that this repository has no such command and asks for nothing. **Each script prints its own verdict line**, so a caller never appends an exit-code probe to it: that compound form is exactly what stalls an unattended run on a permission prompt — except `start-dev-server.sh`, which has no verdict to give because it starts a long-running process. Every wrapper anchors itself to its own checkout before it runs and forwards whatever arguments it was given to the **last** command of its raw line — whether that command accepts a bare path or name filter is a property of the command, not of the wrapper, so a line ending in a sub-command's own flags takes none; `docs/cli.md` §5 is the full contract.
+
+**The other family in this directory is not generated.** The run watcher, its restart wrapper, the notifier and its stream formatter, the commit / push / branch-refresh / worktree / cleanup wrappers, the scratch runner and the shared library at `lib/harness-run-lib.sh` are copied byte for byte into the same `scriptsDir`, because each reads `harness.config.json` *at run time* rather than carrying a value frozen in when `init` ran — a guard whose protected-branch set was baked into a file at generation time enforces the wrong set the moment that list changes, and does it silently. They therefore carry no `{{token}}` at all. `cli/src/generators/outerLoopScripts.ts` declares that set and marks which of its rows an agent may invoke; `cli/scripts/README.md` records why they live under `scriptsDir` rather than in the installed package. **One of them runs a file it is given:** `scratch-run.sh` runs an agent's language probe or mutation check in the interpreter that file's extension names, and refuses any argument that does not resolve inside `<state_dir>/scratch/`.

package/templates/scripts/autonomous-format-stream.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# autonomous-format-stream.sh — turn a headless agent run's `stream-json` events
+# into ONE short line per meaningful event, so the run's log reads like an
+# interactive session and stays tailable while the run is still going.
+#
+# WHO PIPES INTO IT. The watcher, and only the watcher: it starts the agent CLI
+# with `--output-format stream-json --verbose`, tees the raw events to
+# `<state_dir>/autonomous_logs/<branch>.stream.jsonl` (which the usage gate
+# parses for `rate_limit_event`) and pipes the same stream through this filter
+# into the human-readable run log. Nothing here writes a file, opens a network
+# connection, reads configuration or takes an argument — stdin to stdout, once.
+#
+# WHAT IT DELIBERATELY DROPS, AND WHY. A raw transcript of a multi-hour run is
+# tens of megabytes and unreadable, and the three biggest contributors carry the
+# least operator value:
+#
+#   * thinking blocks — unbounded, and the decision they lead to is in the text
+#     or the tool call that follows;
+#   * `tool_result` bodies — a file read is the whole file;
+#   * `system` / init envelopes — one-time setup noise.
+#
+# WHAT IT KEEPS is what answers "what is this run doing right now":
+#
+#   * assistant text, which is where an orchestrator's `[A · Task N · …]`
+#     heartbeat line appears — trimmed, newlines folded to `⏎` so one event
+#     stays one line, and clipped to 300 characters;
+#   * `tool_use` dispatches: the tool name plus one short descriptor, taken from
+#     the first of `subagent_type` / `description` / `command` / `file_path`
+#     that the call carries, clipped to 160 characters;
+#   * the final `result` envelope: the subtype, the turn count, the cost and the
+#     four-way token split (input / output / cache-write / cache-read).
+#
+# A LINE THAT IS NOT JSON IS A NO-OP, BY DESIGN. `fromjson? // empty` swallows
+# it. The stream this reads is interleaved with whatever the CLI writes to the
+# same descriptor — a warning, a partial line at a truncated write — and a
+# filter that died on one of those would take the run's log with it just when
+# something is going wrong. `--unbuffered` is what keeps a `tail -f` live rather
+# than arriving in 4 KB bursts.
+#
+# `jq` IS A HARD PREREQUISITE, the same one the guard hooks and the shared
+# library carry; `doctor` checks its version. Without it this exits non-zero on
+# the first byte and the run's log is empty while the raw `.jsonl` beside it is
+# intact — which is the recoverable half of the pair, and the reason the watcher
+# tees rather than only filtering.
+#
+# Usage: <agent CLI> … --output-format stream-json --verbose | autonomous-format-stream.sh
+#
+# Exit map: this process IS `jq` (`exec`), so the status is `jq`'s — 0 on a
+# clean end of stream, non-zero when `jq` itself could not start or the program
+# failed to compile. No caller in the flow switches on it: the watcher reads the
+# agent CLI's status, not this filter's.
+#
+# REPRO — reproduce any line by hand, with no run and no repository:
+#
+#   printf '%s\n' \
+#     '{"type":"assistant","message":{"content":[{"type":"text","text":"hello"}]}}' \
+#     '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Task","input":{"subagent_type":"general-implementer","description":"port a script"}}]}}' \
+#     '{"type":"assistant","message":{"content":[{"type":"thinking","thinking":"dropped"}]}}' \
+#     'not json at all' \
+#     '{"type":"user","message":{"content":[{"type":"tool_result","content":"dropped"}]}}' \
+#     '{"type":"result","subtype":"success","num_turns":3,"total_cost_usd":0.5,"usage":{"input_tokens":10,"output_tokens":20,"cache_creation_input_tokens":30,"cache_read_input_tokens":40}}' \
+#     | bash <repo>/<scripts_dir>/autonomous-format-stream.sh
+#
+#   -> exactly three lines (the text, the dispatch, the result summary), in that
+#      order, with the thinking block, the malformed line and the tool result
+#      absent, and exit 0.
+
+set -u
+
+exec jq -Rr --unbuffered '
+  (fromjson? // empty)
+  | if .type == "assistant" then
+      ( .message.content[]? |
+        if .type == "text" then
+          ( .text | gsub("^\\s+|\\s+$"; "") ) as $t
+          | if ($t | length) > 0 then "💬 " + ($t | gsub("\n"; " ⏎ ") | .[0:300]) else empty end
+        elif .type == "tool_use" then
+          "→ " + .name + "  "
+          + ( ( (.input.subagent_type // "") + " "
+                + (.input.description // .input.command // .input.file_path // "") )
+              | tostring | gsub("\n"; " ") | gsub("^\\s+|\\s+$"; "") | .[0:160] )
+        else empty end )
+    elif .type == "result" then
+      (.usage.input_tokens // 0) as $in
+      | (.usage.output_tokens // 0) as $out
+      | (.usage.cache_creation_input_tokens // 0) as $cw
+      | (.usage.cache_read_input_tokens // 0) as $cr
+      | "✅ " + (.subtype // "done")
+      + "  turns=" + ((.num_turns // 0) | tostring)
+      + "  cost=$" + ((.total_cost_usd // 0) | tostring)
+      + "  tokens=" + (($in + $out + $cw + $cr) | tostring)
+      + " (in:" + ($in | tostring) + " out:" + ($out | tostring)
+      + " cache-w:" + ($cw | tostring) + " cache-r:" + ($cr | tostring) + ")"
+    else empty end
+'