release: dev -> main — deep-dive audit fixes, middle-tier gating

.github/workflows/ci-test.yml

@@ -2,16 +2,18 @@
 # 🧪 CI · Test
 # ----------------------------------------------------------------------------
 # Purpose : Run unit + Playwright e2e tests across Linux & Windows
-# Trigger : Push to `main`/`dev`, PRs targeting `main`, manual dispatch
+# Trigger : Push to `main`/`dev`, PRs targeting `main` and `dev`, manual dispatch
 # Jobs    : unit  — `bun turbo test` + config_assistant Go tests on linux
 #                    only (windows dropped — see
 #                    unit-tests matrix comment; free windows-latest runners
 #                    can't fit the suite in a reasonable CI budget)
 #           e2e   — Playwright chromium on linux + windows (matrix)
 # Gate    : Required status check on the `main` ruleset — full suite gates
 #           dev → main PRs. Pushes to `dev` also get a full run (dev is the
-#           integration/testing branch), but feat/fix → dev PRs are gated by
-#           typecheck only (see ci-typecheck.yml) to keep CI budget sane.
+#           integration/testing branch). feat/fix → dev PRs run the unit
+#           matrix as a required check (#370: the Typecheck-only gate let an
+#           assertion-level regression merge and keep dev red for 75min);
+#           E2E stays push-on-dev + dev→main only to keep CI budget sane.
 # Notes   : `cancel-in-progress: false` — every main/dev push gets a full run
 #           No trigger on feat/* or fix/* (frequent changes).
 # ============================================================================
@@ -26,6 +28,7 @@ on:
   pull_request:
     branches:
       - main
+      - dev
   workflow_dispatch:
 
 concurrency:

.github/workflows/specgit-accept.yml

@@ -0,0 +1,100 @@
+name: SpecGit Acceptance
+
+on:
+  pull_request:
+    # Delivery PRs target dev (fast-integration layer) and are promoted to
+    # main via the release PR — main's legacy branch protection also requires
+    # the SpecGit Acceptance check, so the verdict must run on both targets.
+    # dev→main promotion stays governed by the protect-main Ruleset's four
+    # required checks.
+    branches: [dev, main]
+
+permissions:
+  contents: read
+
+jobs:
+  specgit-acceptance:
+    name: SpecGit Acceptance
+    runs-on: ubuntu-latest
+    # Must exceed the slowest required sibling (Unit Tests (linux) runs
+    # ~28min on PRs): the verdict waits for every policy check to reach a
+    # terminal state before evaluating.
+    timeout-minutes: 45
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # Check out the PR head branch by name so HEAD is on the branch
+          # (not the detached merge ref): the execution context gate reads
+          # live git. Falls back to the default ref on non-PR events.
+          ref: ${{ github.head_ref || github.ref }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+
+      # This repo is a bun workspace and does not vendor the SpecGit CLI;
+      # install the published CLI instead of building from source. Pinned
+      # with a caret floor (#366): the CLI releases multiple times a day and
+      # an unpinned install would let an unnoticed upstream change flip CI
+      # acceptance verdicts repo-wide.
+      - name: Install specgit CLI
+        run: npm install -g specgit@^0.5.0
+
+      - name: Wait for sibling checks
+        # The verdict must see the OTHER required checks in a terminal
+        # state. Sibling jobs start in parallel AND may not have registered
+        # their check-runs yet, so an empty poll is not "done": wait until
+        # every name in spec_git/policy.yaml is present with a terminal
+        # conclusion. This job is not in the policy, so no self-deadlock.
+        env:
+          GH_TOKEN: ${{ github.token }}
+          WAIT_REPO: ${{ github.repository }}
+          WAIT_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          node --input-type=module <<'EOF'
+          import { readFileSync } from 'node:fs';
+          // Minimal parse of policy.yaml's required_checks block list —
+          // avoids a yaml dependency in this bun-based repo.
+          const policy = readFileSync('spec_git/policy.yaml', 'utf8');
+          const section = policy.slice(policy.indexOf('required_checks:'));
+          const required = [...section.matchAll(/^\s*-\s*(.+)$/gm)].map((m) => m[1].trim());
+          const headers = {
+            authorization: 'Bearer ' + process.env.GH_TOKEN,
+            accept: 'application/vnd.github+json',
+          };
+          const url = 'https://api.github.com/repos/' + process.env.WAIT_REPO
+            + '/commits/' + process.env.WAIT_SHA + '/check-runs?per_page=100';
+          const terminal = new Set(['completed']);
+          const terminalHas = (byName, name) => {
+            if (byName.has(name)) return terminal.has(byName.get(name));
+            const retried = [...byName.keys()].find((k) => k.startsWith(name + ' ('));
+            return retried !== undefined && terminal.has(byName.get(retried));
+          };
+          // Must outlast the slowest required sibling (Unit Tests (linux)
+          // runs ~28min on PRs); the job timeout above bounds this too.
+          const deadline = Date.now() + 40 * 60 * 1000;
+          while (Date.now() < deadline) {
+            const res = await fetch(url, { headers });
+            if (!res.ok) throw new Error('check-runs API ' + res.status);
+            const payload = await res.json();
+            const byName = new Map(payload.check_runs.map((r) => [r.name, r.status]));
+            const missing = required.filter((n) => !terminalHas(byName, n));
+            if (missing.length === 0) {
+              console.log('All required checks are in a terminal state.');
+              process.exit(0);
+            }
+            console.log('Waiting for: ' + missing.join(', '));
+            await new Promise((r) => setTimeout(r, 10000));
+          }
+          console.error('Timed out waiting for sibling checks.');
+          process.exit(1);
+          EOF
+
+      - name: specgit finish
+        run: specgit finish --json
+        env:
+          GH_TOKEN: ${{ github.token }}

.opencode/command/specgit-finish.md

@@ -0,0 +1,27 @@
+---
+description: Run the SpecGit evidence verdict and drive the fix loop to exit 0
+---
+
+# /specgit-finish
+
+Thin trigger for the acceptance verdict. The canonical behavior lives in the
+AGENTS.md SpecGit block; this command only launches it.
+
+## Steps
+
+1. Run from the delivery branch:
+
+   ```bash
+   specgit finish --json
+   ```
+
+2. Branch on the exit code:
+   - `exit 0` → produce the merge brief (issues + PR + CI run links + the
+     verdict) and ask the user to approve the merge. Do not merge yourself
+     without approval.
+   - `exit 1` → read `errors[].fix` / gate failures, fix exactly what they
+     name, re-run. Loop until exit 0.
+   - `exit 3` → report the environment problem (gh auth / network); never
+     edit the record or the policy to work around it.
+3. Iron rules: never weaken `spec_git/policy.yaml` to pass; `--json` is the
+   only parse surface; a non-zero verdict never merges.

.opencode/command/specgit-issue.md

@@ -0,0 +1,22 @@
+---
+description: Start a SpecGit delivery from a title or existing issue number
+---
+
+# /specgit-issue
+
+Thin trigger for the delivery bootstrap. The canonical behavior lives in the
+AGENTS.md SpecGit block; this command only launches it.
+
+## Steps
+
+1. Collect the argument: `$ARGUMENTS` is either an issue title (create) or a
+   pure number (reuse). Multiple arguments = N issues in one delivery.
+2. Run from the repo root:
+
+   ```bash
+   specgit issue "$ARGUMENTS" --json
+   ```
+
+3. On success report the brief: issue URL(s), PR URL (draft), branch name.
+4. Switch to the delivery branch and begin the TDD loop.
+5. On error, read `errors[].fix` and follow it — never bypass the record.

.opencode/hooks/specgit-merge-guard.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# SpecGit merge guard (managed by specgit init). Exit 2 = block with reason.
+command=$(printf '%s' "$1" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{const j=JSON.parse(s);process.stdout.write((j.tool_input&&j.tool_input.command)||'')}catch{process.stdout.write('')}})")
+
+case "$command" in
+  gh\ pr\ merge*)
+    # Real-time verdict: re-evaluate the delivery before letting a merge
+    # through. Verdicts are never persisted, so compute one now.
+    if specgit finish >/dev/null 2>&1; then
+      exit 0
+    fi
+    echo "specgit: merge blocked - 'specgit finish' does not exit 0 right now. Fix what the failures name; never weaken spec_git/policy.yaml to pass." >&2
+    exit 2
+    ;;
+  git\ push\ origin\ main*|git\ push\ origin\ +main*|git\ push\ origin\ HEAD:main*)
+    echo "specgit: direct push to main is not the delivery path. Deliveries go: specgit issue -> PR -> CI -> specgit finish (exit 0) -> merge." >&2
+    exit 2
+    ;;
+esac
+exit 0

.specgit.yaml

@@ -0,0 +1,8 @@
+version: 1
+delivery: issue374
+context:
+  kind: branch
+  branch: feat/375-issue375
+issues:
+  - 374
+pr: 375

AGENTS.md

@@ -4,22 +4,22 @@
 ## Git Workflow (铁律)
 
 ```
-feat/**, fix/** ──PR(Typecheck 门禁)──▶ dev ──push 触发全量测试──▶
+feat/**, fix/** ──PR(Typecheck + Unit Tests 门禁)──▶ dev ──push 触发全量测试──▶
     dev ──手动 release-fork──▶ prerelease 测试版
     dev ──PR(全量测试门禁)──▶ main ──手动 release-fork──▶ 正式版
 ```
 
-**分层门禁**：`dev` 是快速集成层（仅 Typecheck），`main` 是正式质量门禁（Typecheck + 全量 Unit Tests + E2E）。所有改动通过 PR 流转，禁止直推 `main` 和 `dev`（由 GitHub Rulesets 强制）。
+**分层门禁**：`dev` 是快速集成层（Typecheck + Unit Tests (linux)；E2E 不阻塞），`main` 是正式质量门禁（Typecheck + 全量 Unit Tests + E2E）。所有改动通过 PR 流转，禁止直推 `main` 和 `dev`（由 GitHub Rulesets 强制）。
 
 | Branch | 直推 | PR 门禁 | CI 触发 | Purpose |
 |--------|------|---------|---------|---------|
 | `{type}/**` | ✅ 允许 | — | ❌ 不跑 | 开发分支，频繁变更 |
-| `dev` | ❌ 禁止 | PR 必须通过 **Typecheck** | ✅ push 触发 Typecheck + 全量测试 | 快速集成层 |
+| `dev` | ❌ 禁止 | PR 必须通过 **Typecheck + Unit Tests (linux)** | ✅ push 触发 Typecheck + 全量测试 | 快速集成层 |
 | `main` | ❌ 禁止 | PR 必须通过 **Typecheck + Unit Tests + E2E (linux + windows)** | ✅ push 触发全量 | 正式质量门禁 + 发版 |
 
 **流程**：
 1. 从 `main` 切出 `feat/**` 或 `fix/**` 分支开发
-2. PR → `dev`（Typecheck 门禁，快速合并）
+2. PR → `dev`（Typecheck + Unit Tests (linux) 门禁，快速合并）
 3. push 到 `dev` 自动触发全量测试验证
 4. 从 `dev` 手动 `release-fork` → 产出 **prerelease** 测试版
 5. PR `dev` → `main`（全量测试门禁：Typecheck + Unit Tests + E2E）
@@ -240,3 +240,51 @@ Triage uses the five canonical labels `needs-triage`, `needs-info`, `ready-for-a
 ### Domain docs
 
 This repository uses a multi-context domain-document layout rooted at `CONTEXT-MAP.md`. See `docs/agents/domain.md`.
+
+<!-- specgit:block:start -->
+## SpecGit delivery harness
+
+Managed by `specgit init`. Everything between the markers is rewritten on
+re-init; keep manual guidance outside them.
+
+### The delivery story
+
+- Start with `specgit issue <title-or-number>...`: it creates or reuses
+  the issues, branches, opens the draft pull request that closes every
+  bound issue, and writes `.specgit.yaml`. Re-running resumes; it is
+  idempotent.
+- Finish with `specgit finish`: the verdict, derived from real git, PR,
+  and CI evidence. Exit code 0 is the only "done".
+
+### Repair and diagnostics
+
+- `specgit pr` repairs the pull-request binding: with no arguments it
+  auto-discovers the pull request for this head branch, errors with a fix
+  when none is found, and refuses with a list when several match.
+- `specgit status` shows local evidence only: record, state, drift,
+  origin. `specgit doctor` probes git, repository, origin, gh, and
+  policy.
+
+### Issue granularity
+
+One issue = one independently verifiable WHY. If a deliverable cannot be
+verified on its own evidence, split it before binding.
+
+### Iron rules
+
+- `specgit finish` exit code other than 0: never request merge. Fix the
+  delivery, not the gate.
+- Never weaken `spec_git/policy.yaml` to make a verdict pass.
+- `--json` is the only parse surface: stdout is exactly one JSON
+  document; never scrape human-readable output.
+<!-- specgit:block:end -->
+
+## Tool-call discipline (hard rules)
+
+- Never fan out duplicate or near-duplicate queries. One question, one
+  tool call; if the answer is already in context, make zero calls.
+- Parallel tool batches must contain distinct, independently justified
+  calls. Before sending a batch, verify no two calls answer the same
+  question. A repeated identical call is a bug regardless of intent.
+- Long CI waits use `sleep N && <single check>`, never repeated watches
+  of the same resource. One watch command, one result.

CLAUDE.md

@@ -175,3 +175,41 @@ pushes to `main`/`dev` are blocked by GitHub Rulesets. Branch names: `{type}/{sh
 (`feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `release`, `hotfix`), enforced by
 Ruleset. Commits/PR titles: conventional `type(scope): summary`. All PRs must reference an
 existing issue (`Fixes #N`). Curated DAG configs are owned by the `opencode-dag-config` repo.
+
+<!-- specgit:block:start -->
+## SpecGit delivery harness
+
+Managed by `specgit init`. Everything between the markers is rewritten on
+re-init; keep manual guidance outside them.
+
+### The delivery story
+
+- Start with `specgit issue <title-or-number>...`: it creates or reuses
+  the issues, branches, opens the draft pull request that closes every
+  bound issue, and writes `.specgit.yaml`. Re-running resumes; it is
+  idempotent.
+- Finish with `specgit finish`: the verdict, derived from real git, PR,
+  and CI evidence. Exit code 0 is the only "done".
+
+### Repair and diagnostics
+
+- `specgit pr` repairs the pull-request binding: with no arguments it
+  auto-discovers the pull request for this head branch, errors with a fix
+  when none is found, and refuses with a list when several match.
+- `specgit status` shows local evidence only: record, state, drift,
+  origin. `specgit doctor` probes git, repository, origin, gh, and
+  policy.
+
+### Issue granularity
+
+One issue = one independently verifiable WHY. If a deliverable cannot be
+verified on its own evidence, split it before binding.
+
+### Iron rules
+
+- `specgit finish` exit code other than 0: never request merge. Fix the
+  delivery, not the gate.
+- Never weaken `spec_git/policy.yaml` to make a verdict pass.
+- `--json` is the only parse surface: stdout is exactly one JSON
+  document; never scrape human-readable output.
+<!-- specgit:block:end -->