autonomous-sdlc-harness 0.4.2 → 0.6.0

package/dist/retrieval/setup.js

@@ -14,6 +14,10 @@
  *   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.
+ * - **The Python backend gets no install and no download here, and the TypeScript setup still runs.**
+ *   Its package, weights and Postgres are provisioned by hand; the TypeScript runtime and models are
+ *   kept so switching `docs.retrievalBackend` back costs nothing. With `python` selected, one note
+ *   says both.
  *
  * 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`;
@@ -25,6 +29,7 @@ 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 { PYTHON_RETRIEVAL_COMMAND } from './pythonBackend.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;
@@ -116,6 +121,9 @@ export function setUpRetrieval(options) {
     const warnings = [];
     setUpRuntime(options.dryRun, notes, warnings);
     setUpModels(options.dryRun, notes, warnings);
+    if (options.backend === 'python') {
+        notes.push(`docs.retrievalBackend is python: init installed and downloaded nothing for it — the \`${PYTHON_RETRIEVAL_COMMAND}\` package, its weights and its Postgres are set up by hand (docs/retrieval.md → Turning on the Python backend); the TypeScript runtime and models above are kept so switching back costs nothing`);
+    }
     return { notes, warnings };
 }
 //# sourceMappingURL=setup.js.map

package/dist/retrieval/setup.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autonomous-sdlc-harness",
-  "version": "0.4.2",
+  "version": "0.6.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",

package/templates/README.md

@@ -9,7 +9,7 @@ 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` |
+| `github/` | `.github/` in the adopter's repo — `workflows/harness-run.yml` and `workflows/harness-resume.yml`, written only when `execution.target` is `github-actions`, and `workflows/harness-trigger.yml` and `workflows/harness-control.yml`, written only when `forge` is also `github` |
 
 **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.
 

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

@@ -0,0 +1,184 @@
+# harness-control.yml — acts on an autonomous-sdlc-harness command comment
+# (`@sdlc-harness answer|pause|resume|stop|clear`) on an issue or pull request,
+# and turns a pull-request review requesting changes into the next user-review
+# round.
+#
+# WHO WRITES IT. `autonomous-sdlc-harness init`, only when harness.config.json's
+# `forge` is `github` and its `execution.target` is `github-actions`. Written
+# create-if-absent: from then on it is yours to tune, and a re-run of `init`
+# keeps your copy. `init --upgrade-workflows` does NOT re-render it: it carries
+# no version pin and calls the scripts on the default branch, so it shares
+# their re-run contract — `init --force` replaces it after a `.bak`. It is a
+# file of its own, apart from harness-trigger.yml, so you can disable comment
+# control alone: disabling a workflow disables every event in it.
+#
+# WHAT IT DOES. One job runs `remote-run.sh control`, which does everything
+# else: it authorises the actor, finds the run's branch, carries out the
+# command or places the review round, and replies. Every decision lives in that
+# script; this file carries only the events, the permissions, a prefilter and
+# the concurrency group.
+# The `run-name` below is not harness-run.yml's `harness <action> <branch>`
+# title, so no run lookup `remote-run.sh` makes by that title can match it.
+#
+# THE EVENTS.
+#   issue_comment, type `created` only: a command is a new comment. GitHub
+#     raises it for a comment on an issue and on a pull request alike.
+#   pull_request_review, type `submitted` only: the round is built from the
+#     review event, which carries the review body and identifies its inline
+#     comments (docs/github-integration-research.md, C1).
+#   Never pull_request_review_comment: one review raises one such event per
+#   inline comment, so listening to it would start one job per comment for a
+#   round the review event already covers (C1).
+#
+# THE PREFILTER. The job's `if:` runs it only for a comment that contains
+# `@sdlc-harness` and not `<!-- sdlc-harness` (the hidden line every harness
+# reply carries, so a reply quoting a command is never one), or for a review
+# whose state is `changes_requested` on a pull request from this repository.
+# Every other comment or review yields a skipped job, which runs no runner and
+# bills nothing (docs/remote-execution.md, `### Verified in Gate 12 round 2`).
+# It is a saving, not the authority: `control` re-checks every rule, so an
+# edited copy of this filter cannot bypass one. That `contains()` compares
+# case-insensitively is GitHub's documented behaviour, not verified here; a
+# mixed-case handle the filter missed would only go unanswered, never obeyed.
+#
+# THE PERMISSIONS, declared because the default token may be read-only
+# (docs/github-integration-research.md, T2):
+#   contents: write        push a review round
+#   actions: write         dispatch, pause, stop and cancel runs, and read
+#                          runs and their artifacts
+#   issues: write          reply on the issue or pull request, and label it
+#   pull-requests: write   read the pull request, its reviews and comments,
+#                          and label it
+# The job reads no repository secret: it needs only its own token, so the
+# credential secrets never reach the job that reads untrusted comment text.
+# Every reply is posted as github-actions[bot] and starts no workflow (S3).
+#
+# FORK PULL REQUESTS. Never `pull_request_target`, which would run with this
+# repository's write token on a fork's event (C2).
+# A `pull_request_review` job runs this file as the pull request's merge
+# commit carries it (docs/github-integration-research.md, C2), so the `if:`
+# that skips a fork's review is the fork's own copy: a fork that edits it is
+# not skipped, and can name any `runs-on:` label, a self-hosted runner's
+# included. Such a job gets a read-only token and no secret (C2), and fork
+# approval policies apply to it.
+# A comment on a fork's pull request runs with a write token, and `control`
+# refuses it.
+# The checkout is always the default branch, never the pull request's merge
+# commit a `pull_request_review` job checks out by default, so the script that
+# decides is always the default branch's; what a pull request's head can change
+# is this file's own definition for its own review events.
+#
+# THE CONCURRENCY GROUP SERIALIZES REVIEW JOBS PER BRANCH, NEVER COMMENT JOBS.
+#   * A comment job's group is its own run id, so it never waits and is never
+#     replaced: a group keeps at most one pending job and cancels an earlier
+#     pending one, which would drop a command.
+#   * Review jobs on one head branch share `harness-review-<branch>` and run one
+#     at a time, so two reviews submitted together give one round, not two
+#     pushes racing for the same round number.
+#   * A pending review job replaced by a newer one loses nothing: every job in
+#     the group collects cumulatively, every review requesting changes, every
+#     other review carrying a summary and every inline comment no earlier round
+#     recorded, and the round's comment names
+#     every reviewer it took.
+#   * The name `harness-review-<branch>` is reserved for every job that places a
+#     review round on that branch; any other workflow's job that does so joins
+#     the group under exactly that name, and both files' headers declare it.
+#     harness-run.yml's `collect` job is the one such job today (DECLARED
+#     MIRRORS below).
+#
+
+# TWO RULES EVERY EDIT KEEPS.
+#   * Event text and variables reach a shell line only through `env:` and the
+#     event file, never through a GitHub expression inside `run:` — a comment
+#     body is written by whoever posted it (script injection).
+#   * Every GitHub expression has a space after its opening braces. `init`
+#     renders its workflows with the CLI's double-brace token renderer, which
+#     reads a letter straight after the braces as a token; this file carries
+#     no token.
+#
+# DECLARED MIRRORS — a rename on either side is an edit to both:
+#   cli/src/remote/githubActions.ts   WORKFLOW_CONTROL_FILE, COMMAND_HANDLE
+#                                     (`@sdlc-harness`), COMMENT_MARKER
+#                                     (`<!-- sdlc-harness`), REVIEW_ROUND_STATE
+#                                     (`changes_requested`), HARNESS_RUNNER,
+#                                     HARNESS_REMOTE_STOP,
+#                                     HARNESS_TRIGGER_ALLOWED_BOTS
+#   cli/src/config/model.ts           DEFAULTS.scriptsDir
+#   harness-run.yml                   the concurrency group
+#                                     `harness-review-<branch>`, held by its
+#                                     `collect` job
+#
+# ACTION PINS.
+#   actions/checkout@v5
+# The lowest major whose own action.yml declares `runs.using: node24`, per a
+# maintainer's lookups of its action.yml and release notes on
+# 2026-09-29T08:21Z (UTC). That major's release notes require Actions Runner
+# 2.327.1 or newer; a GitHub-hosted runner already has it, and a self-hosted
+# one must run it (docs/remote-execution.md, section 8). A major tag, not a
+# commit sha: it is GitHub's own `actions/` organisation, the owner of the
+# runner and GITHUB_TOKEN this job already trusts, and a major tag takes the
+# action's own patch and security releases where a sha would freeze your copy.
+# Pin a sha in your copy if you want one.
+
+name: harness-control
+run-name: harness control ${{ github.event.issue.number || github.event.pull_request.number }}
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: write
+  actions: write
+  issues: write
+  pull-requests: write
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  control:
+    if: (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@sdlc-harness') && !contains(github.event.comment.body, '<!-- sdlc-harness')) || (github.event_name == 'pull_request_review' && github.event.review.state == 'changes_requested' && github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    concurrency:
+      group: ${{ github.event_name == 'pull_request_review' && format('harness-review-{0}', github.event.pull_request.head.ref) || format('harness-control-{0}', github.run_id) }}
+      cancel-in-progress: false
+    env:
+      GH_TOKEN: ${{ github.token }}
+      HARNESS_REMOTE_STOP: ${{ vars.HARNESS_REMOTE_STOP }}
+      HARNESS_REMOTE_SLUG: ${{ github.repository }}
+      HARNESS_TRIGGER_ALLOWED_BOTS: ${{ vars.HARNESS_TRIGGER_ALLOWED_BOTS }}
+    steps:
+      - name: Check out the default branch
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          token: ${{ github.token }}
+          fetch-depth: 0
+
+      - name: Check for jq and gh
+        run: |
+          missing=""
+          for tool in jq gh; do
+            command -v "$tool" >/dev/null 2>&1 || missing="$missing $tool"
+          done
+          if [ -n "$missing" ]; then
+            echo "::error::this runner lacks:$missing. Install them on the self-hosted runner, or use a GitHub-hosted one."
+            exit 1
+          fi
+
+      - name: Read the configuration
+        run: |
+          scripts_dir=$(jq -r '.scriptsDir // "scripts"' harness.config.json)
+          echo "SCRIPTS_DIR=${scripts_dir%/}" >> "$GITHUB_ENV"
+
+      - name: Set the git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Act on the comment or review
+        run: bash "$SCRIPTS_DIR/remote-run.sh" control

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

@@ -4,6 +4,8 @@
 # WHO WRITES IT. `autonomous-sdlc-harness init`, only when harness.config.json's
 # `execution.target` is `github-actions`. Written create-if-absent: from then on
 # it is yours to tune, and a re-run of `init` keeps your copy.
+# `init --upgrade-workflows` re-renders it together with the run workflow, after
+# a `.bak`, carrying its `- cron:` lines.
 #
 # WHY A POLLER. A `schedule` trigger is a recurring cron read from the default
 # branch, not a one-shot timer, so resuming at a recorded reset time means
@@ -46,6 +48,11 @@
 #     The job's `actions: write` covers listing and downloading its own
 #     workflow's artifacts.
 #
+# THE PERMISSIONS. `issues: write` and `pull-requests: write` serve `poll`'s
+# reports, which comment on the waiting run's issue or pull request; a
+# workflow-level `permissions:` block sets every permission it does not list to
+# `none`.
+#
 # WHAT IT WRITES. The `harness-poll-state` artifact: the failed-dispatch count
 #   `poll` carries to the next tick, kept 7 days.
 #
@@ -83,6 +90,8 @@ on:
 permissions:
   contents: read
   actions: write
+  issues: write
+  pull-requests: write
 
 defaults:
   run:

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

@@ -4,6 +4,8 @@
 # WHO WRITES IT. `autonomous-sdlc-harness init`, only when harness.config.json's
 # `execution.target` is `github-actions`. Written create-if-absent: from then on
 # it is yours to tune, and a re-run of `init` keeps your copy.
+# `init --upgrade-workflows` re-renders it at that CLI's version, after a `.bak`,
+# and only when the HARNESS_CLI_VERSION below differs.
 #
 # THE INPUT CONTRACT. Composed on the shell side by `remote-run.sh` alone:
 #   action           run | pause | warm | stop. Only `run` and `warm` start a
@@ -30,13 +32,42 @@
 #   cli/src/remote/githubActions.ts   the file names, HARNESS_RUNNER,
 #                                     HARNESS_REMOTE_STOP, CLAUDE_CODE_OAUTH_TOKEN,
 #                                     ANTHROPIC_API_KEY, HARNESS_PUSH_URL,
-#                                     HARNESS_GIT_TOKEN, the artifact harness-state
+#                                     HARNESS_GIT_TOKEN, the artifact harness-state,
+#                                     HARNESS_CLI_VERSION
+#   cli/src/generators/githubWorkflows.ts   --upgrade-workflows
 #   cli/src/generators/projectSettings.ts   the marketplace and plugin key
 #                                     autonomous-sdlc-harness@autonomous-sdlc-harness
 #   cli/src/config/model.ts           DEFAULTS.scriptsDir and retrievalApplies
 #   cli/src/machine/paths.ts          machineCacheDir, under which the retrieval
 #                                     runtime sits in `retrieval/`
 #   cli/src/retrieval/runtime.ts      RETRIEVAL_CACHE_DIRNAME, that `retrieval/`
+#   remote-run.sh (the scriptsDir copy) RUN_JOB_NAME (`run`): the `run` job has no
+#                                     `name:`, so GitHub names it by its key,
+#                                     and the settledness test reads that
+#                                     job's status by that name
+#   harness-control.yml               the concurrency group
+#                                     `harness-review-<branch>`, shared by its
+#                                     review jobs and the `collect` job here
+#
+# THE COLLECT JOB. When a run ends, `remote-run.sh collect` starts the next
+# user-review round from every review requesting changes that `control`
+# answered "collected" while the run was in flight, so a reviewer waits at most
+# for that run and never resubmits. It is a job of its own, not a step of
+# `run`, for two reasons: a step cannot hold a concurrency group, and this one
+# must share `harness-review-<branch>` with harness-control.yml's review jobs so
+# the two never place a round at once; and the settledness test reads "the
+# `run` job is completed", which no step inside that job could see. Under
+# `!cancelled()` a failed `run` job still reaches it, and the run's state bundle
+# decides whether the run ended or only paused or parked; a cancelled or
+# stopped run skips it. The group name mirrors harness-control.yml's, and
+# RUN_JOB_NAME in remote-run.sh mirrors the `run` job's key (DECLARED MIRRORS
+# above). It reads no secret: its own token pushes the round, dispatches it and
+# comments. It checks out the default branch, as harness-control.yml's review
+# jobs do, never the run's branch: `collect` fetches that branch itself and
+# `review` cuts its own working copy of it, which create-worktree.sh refuses
+# for a branch already checked out. Its step is `continue-on-error` for the
+# report step's reason below: scripts older than this file carry no `collect`
+# verb.
 #
 # ACTION PINS.
 #   actions/checkout@v5
@@ -58,7 +89,9 @@
 #   Secrets: CLAUDE_CODE_OAUTH_TOKEN and/or ANTHROPIC_API_KEY (one is required;
 #     billing follows the API key when both are set), HARNESS_GIT_TOKEN (optional:
 #     a personal or App token, so the job's pushes trigger your own CI, which
-#     GITHUB_TOKEN pushes never do), HARNESS_PUSH_URL (optional notifications).
+#     GITHUB_TOKEN pushes never do; it also opens the run's draft pull request,
+#     so your CI runs on it without an approval click), HARNESS_PUSH_URL
+#     (optional notifications).
 #   Variables: HARNESS_RUNNER, HARNESS_REMOTE_STOP (any value stops every job
 #     before it launches anything), HARNESS_STEP_TIMEOUT_MINUTES,
 #     HARNESS_SELF_PAUSE_AFTER_MINUTES, HARNESS_MAX_CHAIN, and the watcher
@@ -67,6 +100,20 @@
 #   harness.config.json, at run time: `scriptsDir` and whether docs retrieval
 #     applies. No configured value is frozen into this file.
 #
+# THE PERMISSIONS. A workflow-level `permissions:` block sets every permission
+# it does not list to `none`, so each one the job uses is listed:
+#   contents       to push the branch
+#   actions        to dispatch, poll and enable the poller
+#   issues         to comment and set labels on the issue and the pull request,
+#                  which both use the issues API
+#   pull-requests  to open the draft pull request and label it
+#
+# WHY THE REPORT STEP MAY FAIL. `Open the pull request and report` runs
+# `remote-run.sh deliver` after the push, so the pull request's head carries the
+# run's last commit. It is `continue-on-error`: a repository that re-rendered
+# this file without `init --force` still runs scripts with no `deliver` verb,
+# and a finished run must not be marked failed for its report.
+#
 # THE SELF-PAUSE POINT, MEASURED. On a hosted runner the job drops its own PAUSE
 # REMOTE_SELF_PAUSE_AFTER_SECS after it started, the run yields at its next
 # dispatch boundary, and `remote-run.sh continue` chains a new job.
@@ -95,13 +142,18 @@
 # accepted and its `Run the harness` step run: the expression-valued
 # timeout-minutes is accepted.
 #
-# THE PLUGIN PIN. `claude plugin marketplace add --help` and
-# `claude plugin install --help` (Claude Code 2.1.282) offer no ref or version:
-#   "Usage: claude plugin marketplace add [options] <source>" (options: --claudeai,
-#   --scope, --sparse); "Usage: claude plugin install|i [options] <plugin>".
-# So the job installs the plugin, then refuses to run, naming both versions,
-# when `claude plugin list --json` reports a version other than this file's
-# rendered CLI version.
+# THE PLUGIN PIN. The job clones the marketplace repository at the release tag
+# autonomous-sdlc-harness--v<HARNESS_CLI_VERSION> (docs/development.md, section 7)
+# and adds the clone as a directory source, so what it installs is the tag's
+# plugin whatever the default branch carries. Both the add and the install run
+# from $RUNNER_TEMP, outside the checkout, so the committed .claude/settings.json's
+# project-scope entry of the same name is not in view while installing. The
+# clone is the plugin's runtime root and the runner's cache is its install
+# root; `init --plugin-root-entries` grants both and `doctor --remote-job` grades both. The check after install
+# stays as the guard: the job refuses to run, naming both versions and the
+# upgrade route, when `claude plugin list --json` reports another version. What
+# the agent-runner CLI was measured to accept is recorded in
+# docs/remote-execution.md, section 6.
 #
 # WHY retention-days IS SET. The `harness-state` bundle is the only remote copy
 # of a run's clarifications, uncommitted planning drafts and carried counts; a
@@ -174,6 +226,8 @@ on:
 permissions:
   contents: write
   actions: write
+  issues: write
+  pull-requests: write
 
 defaults:
   run:
@@ -337,11 +391,18 @@ jobs:
             echo "::error::.claude/settings.json names no marketplace source for autonomous-sdlc-harness. Run init locally with --marketplace <owner>/<repo> and commit the file."
             exit 1
           fi
-          claude plugin marketplace add "$source_repo"
-          claude plugin install autonomous-sdlc-harness@autonomous-sdlc-harness
+          upgrade_route="to run another version, re-render this repository's workflows with 'npx autonomous-sdlc-harness@<version> init --upgrade-workflows', then commit the paths its printed 'git add' names and push them to the default branch (docs/remote-execution.md, section 7, Upgrading)"
+          tag="autonomous-sdlc-harness--v$HARNESS_CLI_VERSION"
+          marketplace_dir="$RUNNER_TEMP/harness-marketplace"
+          # --quiet does not cover the detached-HEAD advice a tag checkout prints; only advice.detachedHead gates it.
+          if ! git -c advice.detachedHead=false clone --quiet --depth 1 --branch "$tag" "https://github.com/$source_repo.git" "$marketplace_dir"; then
+            echo "::error::$source_repo has no release tag $tag, so the plugin this workflow was rendered for cannot be installed. If $HARNESS_CLI_VERSION was released, its release is missing the tag; otherwise, $upgrade_route."
+            exit 1
+          fi
+          (cd "$RUNNER_TEMP" && claude plugin marketplace add ./harness-marketplace && claude plugin install autonomous-sdlc-harness@autonomous-sdlc-harness)
           installed=$(claude plugin list --json | jq -r '[.[] | select(.id == "autonomous-sdlc-harness@autonomous-sdlc-harness" and .scope == "user")][0].version // empty')
           if [ "$installed" != "$HARNESS_CLI_VERSION" ]; then
-            echo "::error::the installed plugin is version '${installed:-none}', but this workflow was rendered for $HARNESS_CLI_VERSION. Publish the matching plugin, or re-run init with the installed version and commit the workflow."
+            echo "::error::the installed plugin is version '${installed:-none}', but this workflow was rendered for $HARNESS_CLI_VERSION and cloned $tag; $upgrade_route."
             exit 1
           fi
 
@@ -404,6 +465,13 @@ jobs:
           overwrite: true
           retention-days: 400
 
+      - name: Open the pull request and report
+        if: ${{ !cancelled() && env.SCRIPTS_DIR != '' }}
+        continue-on-error: true
+        env:
+          HARNESS_PR_TOKEN: ${{ secrets.HARNESS_GIT_TOKEN }}
+        run: bash "$SCRIPTS_DIR/remote-run.sh" deliver "$HARNESS_INPUT_BRANCH" "$RUNNER_TEMP/harness-state"
+
       - name: Continue, wait or stop
         if: ${{ !cancelled() && env.SCRIPTS_DIR != '' }}
         run: bash "$SCRIPTS_DIR/remote-run.sh" continue "$HARNESS_INPUT_BRANCH" "$RUNNER_TEMP/harness-state"
@@ -414,6 +482,53 @@ jobs:
           export HARNESS_REPO_SLUG="$HARNESS_REMOTE_SLUG"
           bash "$SCRIPTS_DIR/autonomous-notify.sh" failed "$HARNESS_INPUT_BRANCH" "" \
             "job cancelled: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" || true
+          bash "$SCRIPTS_DIR/remote-run.sh" report failed "$HARNESS_INPUT_BRANCH" --note "the job was cancelled: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" || true
+
+  collect:
+    needs: run
+    if: ${{ inputs.action == 'run' && !cancelled() }}
+    runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    concurrency:
+      group: harness-review-${{ inputs.branch }}
+      cancel-in-progress: false
+    env:
+      GH_TOKEN: ${{ github.token }}
+      HARNESS_REMOTE_SLUG: ${{ github.repository }}
+      HARNESS_INPUT_BRANCH: ${{ inputs.branch }}
+      HARNESS_REMOTE_STOP: ${{ vars.HARNESS_REMOTE_STOP }}
+      HARNESS_TRIGGER_ALLOWED_BOTS: ${{ vars.HARNESS_TRIGGER_ALLOWED_BOTS }}
+    steps:
+      - name: Check out the default branch for collecting
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          token: ${{ github.token }}
+          fetch-depth: 0
+
+      - name: Check for jq and gh before collecting
+        run: |
+          missing=""
+          for tool in jq gh; do
+            command -v "$tool" >/dev/null 2>&1 || missing="$missing $tool"
+          done
+          if [ -n "$missing" ]; then
+            echo "::error::this runner lacks:$missing. Install them on the self-hosted runner, or use a GitHub-hosted one."
+            exit 1
+          fi
+
+      - name: Read the configuration for collecting
+        run: |
+          scripts_dir=$(jq -r '.scriptsDir // "scripts"' harness.config.json)
+          echo "SCRIPTS_DIR=${scripts_dir%/}" >> "$GITHUB_ENV"
+
+      - name: Set the git identity for collecting
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Start the next round from collected reviews
+        continue-on-error: true
+        run: bash "$SCRIPTS_DIR/remote-run.sh" collect "$HARNESS_INPUT_BRANCH"
 
   warm:
     if: inputs.action == 'warm'

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

@@ -0,0 +1,144 @@
+# harness-trigger.yml — starts an autonomous-sdlc-harness task run when an
+# issue is labelled, or when a `repository_dispatch` asks for one.
+#
+# WHO WRITES IT. `autonomous-sdlc-harness init`, only when harness.config.json's
+# `forge` is `github` and its `execution.target` is `github-actions`. Written
+# create-if-absent: from then on it is yours to tune, and a re-run of `init`
+# keeps your copy. `init --upgrade-workflows` does NOT re-render it: it carries
+# no version pin and calls the scripts on the default branch, so it shares
+# their re-run contract — `init --force` replaces it after a `.bak`.
+#
+# WHAT IT DOES. One job runs `remote-run.sh trigger`, which does everything
+# else: it authorises the start, derives the branch, places and commits the task
+# prompt, pushes, dispatches harness-run.yml, comments on the issue and removes
+# the label. Every decision lives in that script; this file carries only the
+# events, the permissions and the label filter. The `run-name` below is not
+# harness-run.yml's `harness <action> <branch>` title, so no run lookup
+# `remote-run.sh` makes by that title can match a trigger run.
+#
+# THE EVENTS.
+#   issues, type `labeled` only, never `opened`: labelling an issue at creation
+#     raises `labeled` too, so listening to both would start twice
+#     (docs/github-integration-research.md, T1). The job runs only for the
+#     label the HARNESS_TRIGGER_LABEL variable names (`sdlc-harness` when
+#     unset), and passes the job that same label, never an empty one;
+#     every other label yields a skipped job, which runs no runner and bills
+#     nothing (docs/remote-execution.md, `### Verified in Gate 12 round 2`).
+#   repository_dispatch, type `harness-task`: the entry for any other adapter
+#     (a Jira rule, a script). Its body is
+#       {"event_type": "harness-task",
+#        "client_payload": {"title": …, "body": …, "source": …}}
+#     within GitHub's client_payload limits (10 top-level properties, under
+#     64 KB). Sending one needs a token with Contents write, so its holder is
+#     the authority.
+#
+# WHO CAN START A RUN. `remote-run.sh`'s `trigger` paragraph owns the check —
+# the labeller, bots and HARNESS_TRIGGER_ALLOWED_BOTS, the permission call —
+# and the order its refusals are made in. Nothing here pre-filters on it.
+#
+# THE PERMISSIONS, declared because the default token may be read-only
+# (docs/github-integration-research.md, T2):
+#   contents: write   push the new branch carrying the task prompt
+#   actions: write    dispatch harness-run.yml and look up the run it created
+#   issues: write     comment on the issue and remove the trigger label
+# The job reads no repository secret: it needs only its own token, so the
+# credential secrets never reach the job that reads untrusted issue text.
+#
+# THE CHECKOUT. The default branch, with the job's own token and never
+# HARNESS_GIT_TOKEN: a branch pushed with GITHUB_TOKEN starts no workflow
+# (docs/remote-execution.md, `### Verified in Gate 12 round 3`), so the prompt
+# commit does not run your CI. A full fetch, because pushing a new branch from
+# a shallow clone has not been measured anywhere.
+#
+# NO CONCURRENCY GROUP. A group keeps at most one pending run and cancels an
+# earlier pending one, which would drop a trigger. Two starts that race for one
+# branch name are caught by the refused push of an existing branch, and the
+# refusal is commented on the issue.
+#
+# TWO RULES EVERY EDIT KEEPS.
+#   * Event text and variables reach a shell line only through `env:` and the
+#     event file, never through a GitHub expression inside `run:` — an issue
+#     title is written by whoever opened the issue (script injection).
+#   * Every GitHub expression has a space after its opening braces. `init`
+#     renders its workflows with the CLI's double-brace token renderer, which
+#     reads a letter straight after the braces as a token; this file carries
+#     no token.
+#
+# DECLARED MIRRORS — a rename on either side is an edit to both:
+#   cli/src/remote/githubActions.ts   WORKFLOW_TRIGGER_FILE, HARNESS_RUNNER,
+#                                     HARNESS_REMOTE_STOP, HARNESS_TRIGGER_LABEL,
+#                                     DEFAULT_TRIGGER_LABEL (`sdlc-harness`),
+#                                     HARNESS_TRIGGER_ALLOWED_BOTS,
+#                                     TRIGGER_DISPATCH_EVENT_TYPE (`harness-task`)
+#   cli/src/config/model.ts           DEFAULTS.scriptsDir
+#
+# ACTION PINS.
+#   actions/checkout@v5
+# The lowest major whose own action.yml declares `runs.using: node24`, per a
+# maintainer's lookups of its action.yml and release notes on
+# 2026-09-29T08:21Z (UTC). That major's release notes require Actions Runner
+# 2.327.1 or newer; a GitHub-hosted runner already has it, and a self-hosted
+# one must run it (docs/remote-execution.md, section 8). A major tag, not a
+# commit sha: it is GitHub's own `actions/` organisation, the owner of the
+# runner and GITHUB_TOKEN this job already trusts, and a major tag takes the
+# action's own patch and security releases where a sha would freeze your copy.
+# Pin a sha in your copy if you want one.
+
+name: harness-trigger
+run-name: harness trigger ${{ github.event.issue.number || github.event.action }}
+
+on:
+  issues:
+    types: [labeled]
+  repository_dispatch:
+    types: [harness-task]
+
+permissions:
+  contents: write
+  actions: write
+  issues: write
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  trigger:
+    if: github.event_name == 'repository_dispatch' || github.event.label.name == (vars.HARNESS_TRIGGER_LABEL || 'sdlc-harness')
+    runs-on: ${{ vars.HARNESS_RUNNER || 'ubuntu-latest' }}
+    env:
+      GH_TOKEN: ${{ github.token }}
+      HARNESS_REMOTE_STOP: ${{ vars.HARNESS_REMOTE_STOP }}
+      HARNESS_REMOTE_SLUG: ${{ github.repository }}
+      HARNESS_TRIGGER_LABEL: ${{ vars.HARNESS_TRIGGER_LABEL || 'sdlc-harness' }}
+      HARNESS_TRIGGER_ALLOWED_BOTS: ${{ vars.HARNESS_TRIGGER_ALLOWED_BOTS }}
+    steps:
+      - name: Check out the default branch
+        uses: actions/checkout@v5
+        with:
+          token: ${{ github.token }}
+          fetch-depth: 0
+
+      - name: Check for jq and gh
+        run: |
+          missing=""
+          for tool in jq gh; do
+            command -v "$tool" >/dev/null 2>&1 || missing="$missing $tool"
+          done
+          if [ -n "$missing" ]; then
+            echo "::error::this runner lacks:$missing. Install them on the self-hosted runner, or use a GitHub-hosted one."
+            exit 1
+          fi
+
+      - name: Read the configuration
+        run: |
+          scripts_dir=$(jq -r '.scriptsDir // "scripts"' harness.config.json)
+          echo "SCRIPTS_DIR=${scripts_dir%/}" >> "$GITHUB_ENV"
+
+      - name: Set the git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Start the run
+        run: bash "$SCRIPTS_DIR/remote-run.sh" trigger

package/templates/repo/gitignore

@@ -68,5 +68,10 @@
 # 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}}
+# The copies `init --upgrade-workflows` and `init --force` take of the two remote-execution workflows
+# and of the permission profile. The upgrade's report names each workflow copy in a diff command, and
+# the profile copy carries this machine's absolute paths just as the profile does. Every other .bak a
+# forced run writes is left visible on purpose.
+{{harnessBackups}}
 {{qaBrowserArtifacts}}
 {{docsRetrievalIndex}}