autonomous-sdlc-harness 0.4.1 → 0.5.0

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,7 +32,9 @@
 #   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
@@ -38,6 +42,22 @@
 #                                     runtime sits in `retrieval/`
 #   cli/src/retrieval/runtime.ts      RETRIEVAL_CACHE_DIRNAME, that `retrieval/`
 #
+# ACTION PINS.
+#   actions/checkout@v5
+#   actions/setup-node@v5
+#   actions/cache/restore@v5
+#   actions/cache@v5
+#   actions/upload-artifact@v6
+# Each is the lowest major whose own action.yml declares `runs.using: node24`,
+# per a maintainer's lookups of each action's action.yml and release notes on
+# 2026-09-29T08:21Z (UTC). Each of those majors' release notes requires 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: every action here 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 shas in your copy if you want them.
+#
 # WHAT IT READS.
 #   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:
@@ -72,33 +92,40 @@
 # the step timeout. The job-level timeout-minutes is the self-hosted limit; a
 # hosted job is stopped at its own limit whatever that says.
 #
-# WHY THE TIMEOUT IS COMPUTED INTO GITHUB_ENV. Whether a step's timeout-minutes
-# accepts an expression over `runner.environment` could not be checked against
-# GitHub's workflow-syntax documentation when this file was written (no network
-# access), so the first step computes every budget value from
-# `runner.environment` into GITHUB_ENV, and the harness step reads a single
-# `env` value. Gate 12 records the real behaviour.
+# WHY THE TIMEOUT IS COMPUTED INTO GITHUB_ENV. The first step computes every
+# budget value from `runner.environment` into GITHUB_ENV, so the harness step's
+# timeout-minutes reads a single `env` value rather than an expression over the
+# runner kind. Gate 12 round 2, on 2026-09-29, found every harness-run.yml run
+# 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 and carried counts; a run parked or paused longer
-# than its retention cannot be answered and loses those counts. 400 is the
+# of a run's clarifications, uncommitted planning drafts and carried counts; a
+# run parked or paused longer than its retention cannot be answered and loses
+# those drafts and counts. 400 is the
 # largest retention any repository can configure, and `actions/upload-artifact`
 # caps a larger `retention-days` at the repository's own maximum, so the value
 # means "as long as this repository allows" — the same bound as leaving it
 # unset. It is explicit so that lowering it is a visible edit. The real bound is
 # the repository's Artifact and log retention setting, which
-# `autonomous-sdlc-harness doctor --check-github` reads. The cap (rather than a
-# rejection) is carried from the action's `@actions/artifact` retention code
-# and could not be re-checked against its v4 README when this file was written
-# (no network access); Gate 12 records the real behaviour.
+# `autonomous-sdlc-harness doctor --check-github` reads. Gate 12 round 2, on
+# 2026-09-29, observed the cap rather than a rejection on `actions/upload-artifact@v4`:
+# the artifact's `expires_at` fell 90 days after its creation, with the
+# repository's artifact-and-log-retention at {"days":90,"maximum_allowed_days":400}.
+# That was v4; the v6 pinned above has not yet been observed by a gate round.
 
 name: harness-run
 run-name: harness ${{ inputs.action }} ${{ inputs.branch }}
@@ -248,7 +275,7 @@ jobs:
 
       - name: Check out the run's branch
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: ${{ inputs.branch }}
           fetch-depth: 0
@@ -280,9 +307,11 @@ jobs:
 
       - name: Set up Node
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: '22'
+          # v5 caches by package.json's packageManager; the job installs nothing through npm's cache, and a lockfile-less repository must not fail this step.
+          package-manager-cache: false
 
       - name: Install the claude CLI when absent
         if: env.HARNESS_STOPPED != '1'
@@ -317,17 +346,24 @@ 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
 
       - name: Restore the docs-retrieval cache
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@v5
         with:
           path: ${{ env.HARNESS_RETRIEVAL_CACHE }}
           key: harness-retrieval-${{ runner.os }}-${{ env.HARNESS_CLI_VERSION }}
@@ -377,7 +413,7 @@ jobs:
 
       - name: Upload the state bundle
         if: always() && env.SCRIPTS_DIR != ''
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: harness-state
           path: ${{ runner.temp }}/harness-state
@@ -411,7 +447,7 @@ jobs:
 
       - name: Check out the dispatched ref
         if: env.HARNESS_STOPPED != '1'
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Read the configuration
         id: config
@@ -430,13 +466,15 @@ jobs:
 
       - name: Set up Node
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: '22'
+          # As in the run job: no npm cache is used, and a lockfile-less repository must not fail this step.
+          package-manager-cache: false
 
       - name: Restore and save the docs-retrieval cache
         if: env.HARNESS_STOPPED != '1' && steps.config.outputs.retrieval == 'true'
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ${{ env.HARNESS_RETRIEVAL_CACHE }}
           key: harness-retrieval-${{ runner.os }}-${{ env.HARNESS_CLI_VERSION }}

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

@@ -0,0 +1,143 @@
+# 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 (`harness` when unset);
+#     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 (`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 || '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 }}
+      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}}