@shahboura/harness 3.0.4

package/.opencode/skills/add-repo/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: add-repo
+version: "3.0.0"
+author: "Mostafa Ashraf"
+description: >
+  Register one new repo into an already-bootstrapped workspace, without
+  disturbing repos already registered or re-running the full interview.
+  USER-ENTRY — invoke only when the user explicitly runs /add-repo; never
+---
+
+
+# add-repo
+
+Every command below is `bin/harness <verb> …` — run it
+yourself via Bash. Never ask the user to type a `harness` command; the user
+only answers the questions below.
+
+## 1 · Ask
+
+- Repo name (must be new — case-insensitively distinct from every
+  already-registered name) and its local path.
+
+## 2 · Discover, then confirm
+
+`bin/harness discover --repo <path>` — same discovery
+`/init-workspace` uses. It first ensures the repo is clean and on its
+default branch: a dirty repo, or one mid-rebase/merge, refuses with a clear
+error — surface that to the user verbatim, never auto-stash/discard. If the
+guessed default branch doesn't resolve (no `origin/HEAD`), ask the user to
+name it explicitly, then pass `--branch <name>` yourself; a repo with no
+`origin` and a stray local branch that happens to be named `main` can't be
+told apart from a genuine one, so confirm rather than assume.
+**Known risk:** running `discover` against a path that's actually already
+registered, with a `/dev-workflow` run in progress against it, can switch
+that run's feature-branch checkout back to default — if there's any chance
+the path is already registered, check first rather than running `discover`
+on it.
+
+Present the proposals (language, `test_cmd`, default branch) as
+defaults-to-confirm, not facts:
+
+- Confirm `test_cmd` by actually running it — don't accept the proposal
+  unconfirmed, and never collapse this repo's own command onto another
+  registered repo's.
+- A `monorepo_split` proposal means this "one repo" is actually several
+  logical repos sharing one `.git` at the physical root. **This isn't yet
+  representable as separate registered repos** — `init-verify`'s
+  `repo:<name>` check requires a `.git` directly under the registered path,
+  which no subtree has, so registering subtrees separately leaves every one
+  of them permanently failing verification with no available fix. Tell the
+  user this is a known gap; register the repo once, at its physical root.
+
+## 3 · Register
+
+```
+bin/harness add-repo --name <n> --path <path> --test-cmd '<confirmed cmd>'
+```
+
+This merges into the existing repo/language config — every already-
+registered repo survives untouched. It refuses (never renames/overwrites/
+aliases) on:
+
+- `--name` already registered, compared case-insensitively — surface this
+  verbatim and ask the user for a different name.
+- `--path` already registered under a different name — surface this
+  verbatim; the repo is very likely already set up, so confirm with the
+  user rather than retrying with a new name.
+
+`--test-cmd` is optional — omitting it registers the repo but leaves
+`init-verify`'s `test_cmd:<name>` check failing until a command is set via
+`init-section --section language` (merge the new repo's entry into the
+existing `language.repos` map — that section is still full-replace, so
+resupply the whole map, not just this repo's entry).
+
+## 4 · Verify + finish
+
+1. `bin/harness init-verify` — every check must pass
+   (or be `manual` with the user's explicit acknowledgment, for MCP-
+   transport work-item providers). **Do not proceed on failures** — show
+   the remediation, fix, re-run.
+2. `bin/harness init-finalize` — refreshes the
+   permission allowlist to cover the new repo (its `test_cmd` binary,
+   `Read` on its path). Confirm `.claude/settings.json` merged cleanly.
+3. **Repo-map**: offer to generate now — run `/repo-map-refresh`'s step 2
+   procedure for this repo (that skill owns the exact subagent_type-
+   guessing warning and the `harness-mode: repo-map` spawn/stamp sequence;
+   don't restate it here), pointed at
+   `.claude/context/repo-map/<repo-name>/`.
+4. Tell the user the new repo is ready for `/dev-workflow`.
+
+## Known risk
+
+`security-scan` scans every registered repo in one call, regardless of
+which repo a given `/dev-workflow` run's tasks touch — avoid running
+`/add-repo` while another run is active for an unrelated repo, in case the
+newly-added one isn't a valid checkout yet.

package/.opencode/skills/dev-workflow/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: "dev-workflow"
+description: "End-to-end SDLC workflow orchestration: fetch → plan → TDD → review → security → PR"
+version: "3.0.0"
+author: "Mostafa Ashraf"
+---
+
+# dev-workflow — the thin orchestrator walker
+
+You are the **orchestrator**: a coordinator, not an implementer. You never
+write code, never touch `ai/<run>/` authority files directly, and never run
+raw `git commit|merge|rebase` — every mutation goes through `harness`
+(guards block the raw paths and redirect you here).
+
+Every command below runs through `bin/harness` — a
+wrapper script that resolves the plugin venv (created by /init-workspace,
+either OS layout) and falls back to system `python3`/`python` pre-setup;
+it runs under Git Bash on Windows too. `--workspace <ws>` and
+`--run <run>` may go before or after the verb, in any mix — e.g. both
+`harness --workspace <ws> --run <run> <verb> …` and
+`harness <verb> --workspace <ws> --run <run> …` work. Always use the full
+`.` path; a bare `harness` is not on PATH, and shell
+variables do not persist between separate Bash calls. Non-zero exit =
+refused; read the JSON error.
+
+## Startup
+
+1. `bin/harness fetch --id <work-item-id>` — refuses if bootstrap is incomplete
+   (run `/init-workspace` first) or a live run already exists (offer the user
+   **Resume or Abort** — never clobber). Abort is a real verb:
+   `bin/harness abort --run <run> --reason "<why>"` —
+   terminal (mutations refuse from then on), sweeps worktrees, keeps the
+   audit trail, and releases the work-item slot so a fresh fetch works.
+   On success note `run`, `mode`.
+2. The pipeline manifest (`pipeline/manifest.yaml`) is
+   the single source of truth for step order. Do not improvise steps.
+
+## The walk
+
+Loop until the mode's sequence is exhausted, then close the run:
+`bin/harness complete --run <run>` (terminal, the
+successful sibling of abort — the final step's file says exactly when).
+
+1. `bin/harness show --run <run>` → current step, mode, tasks, gates.
+2. Read the step's file: `.opencode/skills/dev-workflow/steps/<step>.md`
+   — load ONE step file at a time (context economy). Gate steps all use
+   `steps/gate.md`.
+3. Execute it. Spawning a shape? The prompt MUST carry the structured headers
+   (`harness-mode`, `harness-task`, `harness-run`, `harness-repo`,
+   `harness-test-cmd`). Enforcement, precisely: the spawn guard BLOCKS a
+   harness-shape spawn missing `harness-mode`, and one missing
+   `harness-run` whenever the spawn is legalized by a run's current step
+   (the header must name THAT run). The remaining headers are capture
+   conventions — `harness-task` attributes the token ledger and reviewer
+   verdicts (a per-task review whose spawn omits it cannot satisfy the
+   task's completion guard), `harness-repo`/`harness-test-cmd` scope the
+   subagent's work. Before
+   every spawn, resolve its model: `bin/harness
+   resolve-model --shape <shape> --mode <mode>` (per-mode ?? per-shape
+   default ?? `inherit`, from `subagent_models`). Pass the result as the
+   spawn's `model` param — unless it's the literal string `inherit`, in
+   which case omit the `model` param entirely so the subagent runs on the
+   session model. Every harness-shape spawn runs FOREGROUND — pass
+   `run_in_background: false` explicitly (newer platforms default to
+   background, and capture reads the spawn's own tool_response; a
+   background spawn returns only a launch stub — verdict lost, stall
+   event fabricated; the guard blocks an explicit `true`). Parallelism =
+   batch multiple foreground spawns in ONE message, never backgrounding.
+4. Advance: `bin/harness cursor --to <next> --run <run>`. If refused, you are
+   off-manifest — re-read `show` and correct course; never force.
+
+## Cross-cutting rules
+
+- **Session cwd:** stay at the workspace ROOT — the prompt-capture hook
+  defaults its workspace from cwd, so a bare `cd` into a repo silently
+  drops gate evidence (field-proven). Use absolute paths / `git -C` /
+  `(cd X && …)` subshells for repo work.
+- **Gates:** always `gate --present`, show the artifact to the user verbatim,
+  wait for their reply, then `gate --decide`. The decision is derived from
+  captured human input — you cannot write it, only request the derivation.
+  The reply must be a plain typed chat message (never AskUserQuestion —
+  its answers bypass the capture hook and can never qualify). A refusal
+  means no qualifying reply: re-present or route to ad-hoc.
+- **Stalls:** a subagent that stops without a status block → `bin/harness stall
+  --task <T>` and follow the returned action (`reinvoke` → `recovery` →
+  `human`). NEVER commit or write on a stalled agent's behalf.
+- **Ad-hoc human requests mid-run:** spawn `reviewer` with
+  `harness-mode: request-triage` (always legal), surface the triage verdict
+  to the user; out-of-scope items are never silently merged.
+- **Publish:** the mirror snapshots the run's audit trail INTO a registered
+  **project repo's** feature branch (so the governance record travels with
+  the code in the PR) — never into the workspace, which isn't a git repo and
+  isn't a mirror target. So it only makes sense once a repo has a feature
+  branch, i.e. **after `preflight`**. Rules:
+  - **Before preflight** (`fetch`/`intake`/`plan`/⟨approve-plan⟩): there is
+    no branch yet — **skip the mirror entirely**, don't guess a `--repo`.
+  - **After preflight** (task completion, and each later gate crossing):
+    mirror into **every preflighted repo** (the `branches` artifact in
+    `show` lists them) — one call per repo:
+    `bin/harness publish-mirror --repo <preflighted-repo-path> --run <run>`.
+    In a single-repo run that's one call; in a multi-repo run, one per repo.
+  - It's best-effort/non-blocking: a repo that can't be committed to (no
+    git, detached, etc.) just isn't mirrored — never block the run on it.
+- **Status:** render progress with `bin/harness show`; the ledgers
+  (`events/tokens.ndjson`) are append-only — read, never write.

package/.opencode/skills/dev-workflow/shared/diagram-styling.md

@@ -0,0 +1,65 @@
+# Shared baseline: Mermaid diagram styling (cited by the planner)
+
+Structural rules keep every plan diagram valid, renderable Mermaid.
+**Mechanically enforced** by `bin/harness
+validate-mermaid` (M8 WS-4), run by the orchestrator against `plan.md`
+before the plan gate — a rule violation sends the planner back, it's not
+just a convention to follow on trust.
+
+- **HTML-entity escaping**: a node label containing `&`, `<`, `>`, or `|`
+  uses the entity form (`&amp;`, `&lt;`, `&gt;`, `&#124;`). Not `"` — that's
+  how a label is quoted in the first place; a mis-nested inner quote isn't
+  mechanically caught (would need a real parser, not a structural check).
+- **Quoted subgraph titles**: `subgraph X["..."]`, never the unquoted
+  `subgraph X [...]` form.
+- **classDef ↔ class-reference closure**: every `:::<class>` reference has a
+  matching `classDef <class>` line in the same diagram. The reverse isn't
+  required — an unreferenced `classDef` (e.g. `modified` on an all-new-types
+  diagram) is harmless boilerplate, not an error.
+- **60-node ceiling**: split into sub-diagrams past 60 nodes. The count is by
+  distinct **node ID**, not by words — a descriptive multi-word label like
+  `A[user changes the value]` counts as the one node `A`. Write labels as
+  natural prose; you do **not** need to hyphenate multi-word labels to stay
+  under the cap.
+- Comments use `%%`, never `<!-- -->` inside a fenced diagram.
+- **Not mechanically checked** (Mermaid auto-declares any referenced node
+  ID, so there's no real "undefined" state to detect without a full grammar
+  parser — same scope decision the original ai-sdlc-harness's validator
+  made, though it never said so): node-ID closure, edge-label quoting.
+
+## Class-diagram convention (v3.0-specific, not ported)
+
+A plan's diagrams show the **target codebase's** own types/flow/calls — a
+different subject from the harness's own phase/workflow diagrams (which
+color hook/skill/agent/orch nodes; that palette doesn't fit here). Plan
+diagrams instead mark scope directly on the class diagram:
+
+```
+classDef new fill:#ecffec,stroke:#3a7,stroke-width:1px,color:#063
+classDef modified fill:#fff7d8,stroke:#b80,stroke-width:1px,color:#530
+```
+
+Apply `:::new` / `:::modified` to each type so a reviewer sees scope at a
+glance — **but in a `classDiagram` the style attaches ONLY on a dedicated
+`class <Name>:::<style>` statement (or the class-body declaration), never
+the flowchart idiom.** classDiagram grammar rejects `:::` on a relationship
+endpoint or a bare reference (Mermaid raises `got 'STYLE_SEPARATOR'` and the
+diagram won't render); `validate-mermaid`'s R12 catches it at the plan gate.
+
+```
+%% RIGHT — scope styled on its own class statement:
+classDiagram
+  classDef modified fill:#fff7d8,stroke:#b80
+  AdminController --> WorkflowController : dispatches
+  class WorkflowController:::modified {
+    +run()
+  }
+  class AdminController:::new
+
+%% WRONG — :::modified on a relationship endpoint or bare ref (won't parse):
+%%   AdminController --> WorkflowController:::modified
+%%   WorkflowController:::modified
+```
+
+Any `:::modified` type that is also a PATCH/partial-update DTO must satisfy
+the wrapper-type rule (`shared/engineering.md` — `patch-dto-wrapper`).

package/.opencode/skills/dev-workflow/shared/engineering.md

@@ -0,0 +1,14 @@
+# Shared baseline: engineering principles (cited by developer + reviewer)
+
+- Match the surrounding code: its idioms, naming, error handling, comment
+  density. Consistency beats personal preference.
+- Do the simplest thing that works well: no speculative abstractions, no
+  feature flags or compat shims where changing the code suffices, no error
+  handling for scenarios that cannot happen. Validate at system boundaries.
+- Optional fields on partial-update DTOs use nullable/wrapper types
+  (review-policy `patch-dto-wrapper`) — a bare primitive cannot distinguish
+  "sent default" from "omitted".
+- Tests assert the full observable contract (review-policy
+  `assertion-depth`), not just status codes.
+- Every claim in a status block is evidence-grounded: cite the tool result
+  that proves it. Failures are reported verbatim, never aspirationally.

package/.opencode/skills/dev-workflow/shared/status-block.md

@@ -0,0 +1,29 @@
+# Shared contract: the status block (every shape, every response)
+
+End EVERY response with exactly this block — a capture hook checks for
+it; a missing block triggers the stalled-agent procedure (reinvoke →
+recovery → human).
+
+```
+harness-status: SUCCESS | PARTIAL | FAILED
+harness-task: <task-id or ->
+verdict: <APPROVED | CHANGES_REQUESTED>
+outcome: <one line — what actually happened, evidence-grounded>
+details: <optional: findings list / clarifying questions / blocker>
+```
+
+Rules:
+
+- `verdict` is the REVIEWER's line — APPROVED or CHANGES_REQUESTED, alone
+  on its own line, in the block position shown (BEFORE the prose fields).
+  Non-reviewer shapes omit the line entirely. NEVER fold it into another
+  field's prose: `details: No findings. verdict: APPROVED` is
+  uncapturable — the hook reads only a line-anchored verdict, fail-closed
+  (three field re-reviews were paid for exactly that run-together shape;
+  the verdict used to be defined as part of `details`, which taught it).
+- `outcome` claims only what a tool result in THIS session proves — report
+  failures faithfully ("tests fail with X"), never aspirationally.
+- `PARTIAL` means you checkpointed (wip commit) and the work is resumable —
+  say exactly where you stopped.
+- Reviewer findings go in `details` as a numbered list:
+  `[R1] <severity: CRITICAL|WARNING|SUGGESTION> <finding>`.

package/.opencode/skills/dev-workflow/steps/analyze-comments.md

@@ -0,0 +1,32 @@
+# Step: analyze-comments (reviewer shape; on-demand, repeatable group)
+
+Triggered when PR review comments arrive (`reenter_when:
+new_comments_present` — re-entry after apply-fixes is a declared edge).
+
+1. Fetch the comments via the git provider:
+   `bin/harness fetch-pr-comments --repo <repo> --run <run>`
+   (`local` provider returns none — paste them yourself for that case).
+2. Spawn `reviewer` with `harness-mode: analyze-comments` + the comments.
+   It follows `steps/comment-analysis.md`.
+3. Persist its analysis to `<run>/reports/comments-round-<n>.md`, numbering
+   each comment (`[1]`, `[2]`, …), and record the declared artifact:
+   `bin/harness artifact --name comment-analysis
+   --value reports/comments-round-<n>.md --run <run>`.
+4. Present ⟨select-comments⟩ — a `select` gate, not an approve/reject one.
+   The candidate list is supplied ONCE, at present time, and sealed into
+   state — decide replays that exact list, so the numbering the human saw
+   can never be redefined between present and decide (RC3):
+   ```
+   bin/harness gate --id select-comments --present \
+     --options <comment-id-1>,<comment-id-2>,... --run <run>
+   ```
+   Show the numbered list (same order), wait for the reply, then:
+   ```
+   bin/harness gate --id select-comments --decide --run <run>
+   ```
+   The human's reply (e.g. `1,3`) becomes a LIST decision — any parseable
+   selection is forward-legal, so this never routes to `on_reject`; it just
+   records which comments `apply-fixes` should address. To select nothing
+   (none of the comments need fixing), reply literally `NONE` — that's the
+   only input that parses to an empty selection; anything else either
+   matches real options or refuses as unparseable.

package/.opencode/skills/dev-workflow/steps/apply-fixes.md

@@ -0,0 +1,24 @@
+# Step: apply-fixes (developer shape, mode `fixup`)
+
+Requires the ⟨select-comments⟩ token — a `select` gate (see `analyze-comments.md`):
+its decision is a LIST of the comment IDs the human picked, read from
+`state.gates["select-comments"].decision` (`bin/harness show`).
+
+1. Spawn `developer` with `harness-mode: fixup` + the SELECTED comments only
+   (look up each id's text from `<run>/reports/comments-round-<n>.md`).
+   Same rules as `fixup-task.md` (fixup commits, autosquash, locked tests).
+2. `bin/harness merge-task --autosquash
+   --base <default-branch> --repo <repo> --run <run>` — this REWRITES the
+   branch's history (fixups folded in), so the remote copy is now stale
+   regardless of whether the branch itself moved. Push it:
+   `bin/harness push --repo <repo> --branch <feature-branch>
+   --force-with-lease --run <run>`. If the base moved upstream too,
+   `bin/harness sync-branch --onto <default-branch>
+   --repo <repo> --run <run>` FIRST (rebase), then the push.
+   Record the declared artifact: `bin/harness artifact
+   --name fix-commits --value "<comment-ids fixed> @ <new HEAD sha>" --run <run>`.
+3. `bin/harness publish-mirror --repo <repo> --run <run>`.
+   From here the cursor has two
+   legal moves (`show` + the manifest tell you which): reenter `analyze-comments`
+   (declared repeatable edge — more comments arrived) or proceed to `reconcile`
+   (declared `returns_to` edge — done addressing comments, PR merged).

package/.opencode/skills/dev-workflow/steps/comment-analysis.md

@@ -0,0 +1,11 @@
+# Instruction: PR comment analysis (reviewer shape, mode `analyze-comments`)
+
+For each PR comment, classify with evidence from the actual code:
+
+- `VALID` — the comment is right; state the fix it implies and its cost.
+- `INVALID` — the comment misunderstands; state the disproof (file:line).
+- `PARTIAL` — right concern, wrong specifics; state which half holds.
+
+Never soften a VALID into PARTIAL to avoid work; never argue an INVALID
+without a concrete disproof. Numbered list, one verdict per comment, full
+analysis in the status block `details`.

package/.opencode/skills/dev-workflow/steps/create-pr.md

@@ -0,0 +1,39 @@
+# Step: create-pr (orchestrator-owned, fully mechanical)
+
+The feature branch must exist on the remote before the provider CLI can open
+a PR/MR against it — push it first (owned entry point, RC1: never a raw
+`git push`):
+
+```
+bin/harness push --repo <repo> --branch <feature-branch> --run <run>
+```
+
+Then create the PR:
+
+```
+bin/harness create-pr --repo <repo> --run <run>
+```
+
+Creates the PR via the configured git provider (title from the declared
+`pr_title` template; base branch is the one `preflight` resolved and
+recorded for this repo — never a hardcoded guess), records the `pr`
+artifact (keyed by repo name — one PR per repo in multi-repo runs).
+
+**Provider outage escape hatch:** if the provider CLI cannot create the
+PR (infrastructure fault — e.g. a proxy 404ing path-encoded project
+lookups) but the branch is pushed, the human creates the PR by hand and
+you record it with `--url <its-url>` on the same command (the URL must
+end in the PR/MR number — the comment loop derives the id from it).
+Recording stays owned: same artifact, same locking, plus a
+`pr-recorded-manually` audit event. Never hand-edit state.yaml, never
+skip recording.
+
+Then publish the mirror **once per preflighted repo** (SKILL.md's Publish
+rule) so the final run snapshot lands in each PR's branch — `--push` is
+REQUIRED here: the PR was created from the already-pushed branch, so a
+mirror commit made after it stays local forever without its own push
+(field finding: every run ended with its audit snapshot stranded one
+commit ahead of the remote, invisible to the PR reviewer):
+`bin/harness publish-mirror --repo <preflighted-repo-path> --push --run <run>`.
+Advance to `reconcile`. The `pr-comments` group is now available on demand
+(round-triggered, repeatable).

package/.opencode/skills/dev-workflow/steps/develop-task.md

@@ -0,0 +1,54 @@
+# Instruction: develop one task (developer shape, mode `develop`)
+
+You own ONE task, in YOUR worktree (`harness-repo`), test-first.
+
+**The rule is per-task data, not the mode's name:** if your task declares
+`test_intents` (check it in `bin/harness show`'s task
+list), the completion transition mechanically requires a red-proof — there
+is no path to done that skips it. If it declares none, the red-proof
+machinery is inactive and `task --to in-review` skips both verify-red and
+verify-green entirely — step 3 below does not apply; write tests and
+implementation together, then go straight to step 4. In practice:
+plan-registered tasks carry intents unless the plan opted out
+(`test_intents: []`, docs/chore); quick mode's fetch-seeded task declares
+none — that's why quick runs are relaxed by design, not an oversight.
+
+1. **Read** the task's plan section (description, edge cases, test-intents,
+   `[API:]` annotations — verify those signatures before writing call sites,
+   pattern hints — start from them). Quick mode has no plan step, so there
+   are no declared test-intents to read — go straight to the work item's
+   own description.
+2. **Write the failing test(s)** implementing the declared test-intents.
+   No implementation yet — and this ordering is hook-ENFORCED, not advisory:
+   until your red-proof is sealed (step 3), writes to non-test paths in your
+   worktree are refused (test paths, test fixtures, and build manifests for
+   test dependencies stay writable). **Task declares NO test-intents**
+   (docs/chore — the plan-approved opt-out)? Skip steps 2–3 entirely: no
+   red-proof is needed or possible (verify-red refuses, the completion
+   guard exempts you) — implement, commit, report; review still applies.
+   (Quick mode: skip straight to writing test + implementation together —
+   there's no red-proof to prove first.)
+3. **Prove red (only when your task declares test-intents):**
+   `bin/harness verify-red --repo <repo> --task <T> --run <run>`
+   (`--test-cmd <cmd>` from your `harness-test-cmd` header; omit it and the
+   command auto-resolves from language-config for this task's registered
+   repo) — must succeed before any impl. If it reports "not red", your impl
+   already exists or the test is vacuous — fix the test.
+   From here your test files are LOCKED (blob-SHA): changing one fails the
+   completion check. Genuinely wrong test? Use the flagged path:
+   `verify-red --revise --reason "<why>"` — reviewer-visible, never silent.
+   The output's `missing_intents` (declared names not literally found in
+   your test files) is mechanical, not a suggestion — write ALL declared
+   tests before this call so it comes back empty; a non-empty result after
+   the fact means a declared test was skipped, and adding it now means the
+   same flagged `--revise` path as any other post-seal test change, not a
+   silent add.
+4. **Implement** until the test passes. Checkpoint with
+   `bin/harness commit --repo <repo> --task-id <T> --summary "<what>"`
+   (working commits; squashed later — never raw `git commit`).
+5. **Full-suite check:** run `<test-cmd>`; fix regressions you introduced.
+6. Report via the status block: `harness-status: SUCCESS` with
+   `verify-red`'s `missing_intents` value quoted verbatim in `details`
+   (empty if you closed every gap in step 3), or `PARTIAL` after a
+   `--commit-class wip` checkpoint near your turn ceiling, or `FAILED` with
+   the blocker.

package/.opencode/skills/dev-workflow/steps/develop.md

@@ -0,0 +1,60 @@
+# Step: develop (orchestrator loop — spawns developer + reviewer per task)
+
+Lane policy (M5 charter): tasks run **sequentially within a repo, in
+parallel across repos** (one developer per lane, spawned together). A lane's
+stall pauses that lane only (fail-soft); gates and pre-pr require ALL lanes
+complete (fail-closed sync points — mechanically enforced: the cursor cannot
+leave `develop` while any task is still pending/in-progress/in-review).
+
+Once, before the first task: `bin/harness write-back
+--milestone develop_start --run <run>` (no-ops cleanly if
+`write_back.on_develop_start` is off or the provider/type resolve no target;
+for an MCP-transport work-item provider it also no-ops, returning
+`mcp_guidance` — invoke the named tool yourself if you want live status
+sync, otherwise nothing further to do).
+
+Per task:
+
+1. **Worktree:** `bin/harness worktree-add --repo <repo> --task-id <T>
+   --base <feature-branch> --run <run>` — records `{path, branch}` in state;
+   idempotent on resume. If it fails twice it names the direct-branch
+   fallback — offer that choice to the user, never improvise.
+2. `bin/harness task --id <T> --to in-progress --run <run>`
+3. **Spawn `developer`** with headers (`harness-mode: develop`,
+   `harness-task: <T>`, `harness-run`, `harness-repo: <worktree-path>`,
+   `harness-test-cmd`: the task's registered repo's own `language.repos.<repo-name>.test_cmd`
+   — language-config is per repo, not one global command; look up the name
+   this task's repo was registered under in `repos.yaml`) + the task's plan
+   section. It follows `steps/develop-task.md` (TDD: verify-red, then
+   impl, then a harness commit).
+4. **Completion:** `bin/harness task --id <T> --to in-review --repo <worktree>
+   --run <run>` (`--test-cmd <cmd>` optional — omitted, it auto-resolves from
+   language-config for this task's registered repo) — runs verify-green +
+   the red-proof check; a refusal means the TDD contract wasn't met (send
+   the developer back; a locked-test change needs the flagged revision path).
+5. **Spawn `reviewer`** (`harness-mode: review`, same headers — the
+   `harness-task: <T>` header is load-bearing here: a capture hook
+   captures the reviewer's `verdict:` line into `reviews.ndjson` keyed by
+   it, and step 7's `task --to done` REFUSES without a captured APPROVED
+   for this task) on the task diff. `CHANGES_REQUESTED` →
+   `bin/harness task --id <T> --to in-progress --run <run>`
+   (round-bounded; a refusal = escalate to the human) and re-spawn the
+   developer with the findings. `APPROVED` → continue.
+   **Verdict not captured** (a `verdict-uncaptured` event, or step 7
+   refused with reviews.ndjson missing this task)? Re-spawn the reviewer
+   FRESH — foreground, same headers. NEVER SendMessage/resume the finished
+   one: continuation replies pass through no capture hook, so a restated
+   verdict there can never register, however clean (field finding).
+6. **Squash:** from the feature-branch checkout:
+   `bin/harness merge-task --repo <repo> --task-id <T> --task-branch
+   <worktree-branch> --summary "<task summary>" --run <run>`
+7. `bin/harness task --id <T> --to done --run <run>`
+   (refused unless the hook captured this task's reviewer APPROVED — spawn
+   the reviewer, don't restate its verdict) → `bin/harness worktree-remove --repo
+   <repo> --task-id <T> --run <run>` → `bin/harness publish-mirror --repo <repo> --run <run>`.
+
+All tasks done → record the declared artifact the ⟨approve-impl⟩ gate
+presents: `bin/harness artifact --name task-commits
+--value "<T1>: <sha1>; <T2>: <sha2>; …" --run <run>` (the SHAs are in
+`show`'s tasks) → `bin/harness cursor --to <next> --run <run>`
+(⟨approve-impl⟩ in full; quick-recheck in quick).

package/.opencode/skills/dev-workflow/steps/fetch.md

@@ -0,0 +1,34 @@
+# Step: fetch (orchestrator-owned, fully mechanical)
+
+Already executed by `bin/harness fetch` at startup — it fetched the work item via
+the configured provider, normalized it to `<run>/work-item.json`, resolved
+`change_type`, ran the ex-ante quick classifier, and bootstrapped `state.yaml`
+with a seeded task.
+
+## MCP-transport providers (ado-mcp / jira / zoho)
+
+A script can't call an MCP tool, so `bin/harness fetch
+--id` **refuses** for these, naming the tool + args to invoke (that refusal is
+the instruction). Run step-one in the orchestrator instead:
+
+1. Invoke the mapped `work_item.fetch` tool (`bin/harness
+   provider --op work_item.fetch --id <id>` prints the exact tool + args;
+   `{project}` from `provider.ado_project`). Capture its raw JSON result.
+2. Pipe that raw result into the same bootstrap the CLI path runs:
+
+   ```
+   printf '%s' '<raw-json>' | bin/harness fetch --from-raw
+   ```
+
+   `--from-raw` runs the identical normalize → classify → bootstrap, writing
+   `work-item.json` and `state.yaml`. On success note `run`, `mode`.
+
+## Advance
+
+Nothing further to do here. Advance:
+
+```
+bin/harness cursor --to <next-per-manifest> --run <run>
+```
+
+(`intake` in full mode, `preflight` in quick.)

package/.opencode/skills/dev-workflow/steps/fixup-task.md

@@ -0,0 +1,12 @@
+# Instruction: post-squash fixes (developer shape, mode `fixup`)
+
+You are fixing findings against ALREADY-SQUASHED task commits:
+
+1. For each finding, make the fix in the feature-branch checkout.
+2. Commit with `bin/harness commit --repo <repo> --fixup-of <task-id>` — the
+   bin/harness locates the task's integration commit and formats the `fixup!`
+   subject; autosquash folds it later.
+3. TDD-locked test files remain locked: a test change still requires the
+   flagged revision path (`verify-red --revise --reason`).
+4. Run the full suite before reporting. Status block lists finding → fix
+   mapping, evidence-grounded.

package/.opencode/skills/dev-workflow/steps/gate.md

@@ -0,0 +1,53 @@
+# Step: any gate (⟨approve-plan⟩, ⟨approve-impl⟩, ⟨approve-security⟩, …)
+
+A gate derives its decision from CAPTURED human input — you present and
+request; deterministic code decides (design.md RC3).
+
+1. `bin/harness gate --id <gate> --present --run <run>`
+2. Show the gate's artifact to the user **verbatim** (the manifest's
+   `presents:` names it — plan.md, task summary, security report…), plus the
+   options: plain gates → `APPROVED` / `rejected`; security gate →
+   `[1] fix-now [2] waive [3] defer`.
+3. Wait for the user's reply — it must arrive as a PLAIN TYPED CHAT
+   MESSAGE. The capture hook anchors decisions to UserPromptSubmit events
+   only; an AskUserQuestion answer arrives as a structured tool result,
+   is never captured, and the decide call will refuse with "no human
+   input after presentation" (dogfood-run finding — do not burn attempts
+   rediscovering this). Do not interpret the reply yourself.
+4. `bin/harness gate --id <gate> --decide --run <run>`
+   — never pass `--options` here: what a numbered reply means is DECLARED
+   data (the manifest's `dispositions`, e.g. the security gate's
+   `fix-now,waive,defer`), read by the CLI itself; a caller-supplied list
+   at decide time is refused (RC3).
+5. Outcomes:
+   - decision recorded → `bin/harness cursor --to <next>` (forward or the
+     declared `on_reject` target — `show` + the manifest tell you which).
+   - a REJECTION-side reply may carry notes after its option word
+     (`REJECTED — split T2 into two tasks` decides as rejected; the notes
+     ride into the on_reject step). FORWARD words stay bare: a qualified
+     approval like "APPROVED but…" (or "waive if…") never decides.
+   - refused (no qualifying reply / qualified FORWARD reply)
+     → the reply routes to **ad-hoc handling**: triage it
+     (`request-triage`), resolve with the user, then `--present` again
+     (re-presenting re-stamps the window) and repeat.
+6. Security gate only: a `defer` decision → the decide result carries a
+   `follow_up` field and logs a flagged `deferral-pending` event that
+   stays on the dashboard until you pair it — act on it now: create
+   the follow-up work item
+   `bin/harness provider --op work_item.create --title
+   "<summary>" --description "<finding + repo + severity>"` (github/gitlab/
+   local-markdown; a provider that declares it unsupported → comment on the
+   parent item instead), then clear the pending flag:
+   `bin/harness log-event --json
+   '{"kind": "deferral-recorded", "item": "<new-id>"}'`.
+7. Publish the mirror after the crossing — **once per preflighted repo**
+   (the `branches` artifact in `show` names them), never into the
+   workspace: `bin/harness publish-mirror --repo <preflighted-repo-path> --run <run>`.
+   **⟨approve-plan⟩ is BEFORE preflight** — no branch exists yet, so **skip
+   the mirror entirely at this gate** (there's nothing to snapshot into a
+   code branch). See SKILL.md's Publish rule. Best-effort/non-blocking.
+8. ⟨approve-impl⟩ only, BEFORE presenting: `bin/harness
+   write-back --milestone in_review --run <run>` (no-ops cleanly if
+   `write_back.on_in_review` is off, or — for an MCP-transport provider —
+   returning `mcp_guidance` instead of raising; invoke the named tool
+   yourself if you want live status sync).