Auto Pass

---
name: auto-pass
description: >
  Canonical main-chain orchestrator for locked/current refinement-owned sources
  (DP-backed or JIRA Epic-backed). It routes a source through breakdown,
  engineering, and verify-AC without taking over their mutation authority.
  Trigger: "auto-pass {KEY}", "快速通關 {KEY}", "完整流程 {KEY}" when the source
  is LOCKED and artifacts are current. `{KEY}` 可以是 `DP-NNN` 或 JIRA Epic key。
metadata:
  author: Polaris
  version: 0.2.0
---

# Auto-pass

`auto-pass` 是 locked/current refinement-owned source 的主鏈 orchestrator。它的工作是解析
source、建立或 resume source-scoped ledger、依序 dispatch `breakdown -> engineering ->
verify-AC`，並在流程抵達 terminal state 時產出 durable report。

它不是施工 skill，也不是 release skill。`auto-pass` 不直接改 code、不直接寫 task.md、
不建立 generic GitHub PR、不判定 AC PASS/FAIL，也不執行 merge、release、deploy 或
production write。

## Source Gate

`auto-pass` 接受 `spec-source-resolver.md` 解析出的任一 refinement-owned source。當前覆蓋：

- **DP-backed source**：`DP-NNN`，或指向
  `docs-manager/src/content/docs/specs/design-plans/DP-NNN-*` container 內的 path。
- **JIRA Epic-backed source**：JIRA Epic key（例：`GT-NNN`、`KB2CW-NNN`），或指向
  `docs-manager/src/content/docs/specs/companies/{company}/{EPIC}/` container 內的 path。

進入 execution 前必須確認（與 source type 無關）：

- 只能解析到唯一 source container。
- container `index.md` frontmatter `status` 是 `LOCKED`。
- `refinement.md` 與 `refinement.json` 存在且 current。
- ledger `source.refinement_hash` 對齊 current refinement artifact。

未 LOCK、缺 artifact、artifact stale、duplicate source、無法被 resolver 解析出唯一 container
的 source 都不得進入 execution；必須 route 回 owning skill 或 terminal `blocked_by_gate_failure`。
所有 source-type 共用同一條 gate，沒有特殊豁免路徑。

## Ledger Contract

每次 orchestration 必須使用主 checkout 絕對路徑底下的 ledger：

```text
{source_container}/artifacts/auto-pass/YYYYMMDD-HHMMSS-ledger.json
```

`{source_container}` 由 `spec-source-resolver.md` 決定，DP-backed source 落在
`design-plans/DP-NNN-*/`，JIRA Epic-backed source 落在 `companies/{company}/{EPIC}/`；
ledger writer path glob 受 `scripts/lib/evidence-producers.json` parity 保護。

ledger schema、consent enum、terminal enum、resume 欄位與 JIRA status consent schema 以
`.claude/skills/references/auto-pass-ledger.md` 為準，並由
`scripts/validate-auto-pass-ledger.sh` 驗證。

啟動 `auto-pass` 代表使用者同意本 source 內的重新評估、重新拆分與 task repair。這份同意
只能透過 ledger artifact 傳給下游，不可用 conversation memory 代替。

## JIRA Status Sync Consent (D12)

當 source 為 JIRA Epic-backed（`source.type=jira`）時，第一次在同一 session 內 dispatch
`auto-pass {JIRA_KEY}` 必須先 prompt 使用者確認 JIRA status transition consent：

> auto-pass 將在 breakdown / engineering / verify-AC 各階段同步 JIRA Epic 與子單 status
> （例如 `In Development` / `子任務開發完畢` / `完成`），是否同意？(y/n)

行為合約：

- 使用者同意（`y`）→ 寫入 ledger `consent_policy.jira_status_sync=true`，並建立 session-scoped
  marker：

  ```text
  .polaris/runtime/auto-pass-jira-consent-{session_id}-{JIRA_KEY}
  ```

  marker 內容為 JSON `{ "source_id": "...", "granted_at": "ISO8601", "session_id": "..." }`。
  同 session 後續 `auto-pass {JIRA_KEY}` call 偵測 marker 存在即不再 prompt。

- 使用者否決（`n`）→ 立刻 abort，terminal `user_aborted`，不寫 JIRA transition、不建立 marker。

- 缺 `session_id` 時改用短 TTL fallback（30 分鐘 mtime check），marker 命名為
  `.polaris/runtime/auto-pass-jira-consent-fallback-{JIRA_KEY}`；TTL 過期視同未同意，
  下一次 call 重新 prompt。

DP-backed source（`source.type=dp`）不需要此 prompt，因為 DP container 沒有 external JIRA
status surface 需要同步。consent schema、marker 格式與 validator 期望以
`.claude/skills/references/auto-pass-ledger.md` § JIRA Status Consent 為準。

## Producer-Owned Writer (DP-226)

ledger 與 resume artifact 的 durable write 必須走 deterministic producer writer，
不再依賴 Claude `Write` / `Edit` / `MultiEdit` tool 的 per-call env 注入，也不
保留 DP-225 dogfood 期間的 Bash heredoc workaround。

呼叫方式：

```bash
bash scripts/write-producer-owned-artifact.sh \
  --producer-token auto-pass:source \
  --path {source_container}/artifacts/auto-pass/YYYYMMDD-HHMMSS-ledger.json \
  --body-file /absolute/path/to/staged-body.json \
  --source-container {source_container} \
  --source-id {SOURCE_ID}
```

`{SOURCE_ID}` 是 resolver 回傳的 canonical key（DP-NNN 或 JIRA Epic key），
`{source_container}` 對應 DP-backed `design-plans/DP-NNN-*/` 或 JIRA Epic-backed
`companies/{company}/{EPIC}/` container。

stage 對應的 producer token：

| Stage | Token |
|-------|-------|
| ledger 建立（source） | `auto-pass:source` |
| ledger 更新（breakdown phase） | `auto-pass:breakdown` |
| ledger 更新（engineering phase） | `auto-pass:engineering` |
| ledger 更新（verify-AC phase） | `auto-pass:verify` |
| resume artifact write（session_handoff） | `auto-pass:verify`（同 entry） |

resume artifact write 必須額外帶 `--ledger-path /abs/ledger.json` 與
`--source-id {SOURCE_ID}`；writer 將以這些 context 呼叫 `validate-auto-pass-resume.sh`，
缺 context 一律 fail-closed，不留下 invalid artifact。

writer 行為摘要：

- 讀 `scripts/lib/evidence-producers.json`，token-first lookup + path glob enforce；
  token 不在 `producer_tokens[]` 或 path 不在 `path_globs[]` 時 exit 2 不寫檔。
- temp file + atomic rename；final-path 需驗證的 artifact（ledger / resume）
  在 validator fail 時 rollback 既有內容。
- 成功時 stderr log `[write-producer-owned-artifact] producer=... path=...`，
  作為 post-task reflection attribution 來源。

`POLARIS_PRODUCER` env 仍由 hook（`pre-write-language-policy.sh` /
`no-direct-evidence-write.sh`）辨識，但只在 deterministic 觸發路徑（如 producer
script 內部）使用，不得透過 Claude tool per-call env 模擬 producer。

## Dispatch Boundary

`auto-pass` 只 dispatch owning skills：

1. `breakdown` 產生或修正本 source（DP-backed 或 JIRA Epic-backed）的 work orders。
2. `engineering` 依 authoritative task.md 施工、驗證並建立 non-draft workspace PR。
3. `verify-AC` 驗收 V work order 並產生 current verification disposition。
4. `refinement`（**amendment mode only**, DP-212）：當 `{source_container}/refinement-inbox/*.md`
   出現或 verify-AC 回 `spec_issue` 時，dispatch refinement 消費 inbox、把 implementation detail
   微調寫回 `refinement.md` / `refinement.json`，counter +=1 後 loop 回 breakdown。Amendment
   不向使用者發問、不重做 Phase 0/1/2 discovery、不能改 LOCKED scope（由
   `validate-refinement-locked-scope.sh` 把關）。

inner skill 的 mandatory gates 保持原樣。任何 planner-owned gap、scope escalation、AC spec
issue、consent 外 external write、blocked conflict 或 unknown probe 都必須回到 owning skill 或
明確 pause / blocked；`auto-pass` 不得手動補欄位來通過 gate。

## Execution Loop

execution loop 以最後一次 breakdown PASS snapshot 作為本輪 required PR set：

1. Validate source 與 ledger consent。
2. Dispatch `breakdown`；PASS 後讀 `task_snapshot` marker 並更新 ledger snapshot。
3. 依 task DAG dispatch `engineering`；PR opened / ready 必須由 PR freshness 與 completion
   proof marker 判讀。
4. Dispatch `verify-AC`；verification disposition 必須 current，缺 V task / AC artifact 時回
   breakdown owning scope。
5. 所有 required PR opened / ready 且 verification disposition current 時 terminal `complete`，
   寫 final report，然後執行 terminal complete closeout chain：
   `scripts/mark-spec-implemented.sh {SOURCE_ID} --auto-archive`。

`auto-pass {KEY} resume` 必須先跑 `scripts/validate-auto-pass-resume.sh`，確認 ledger
`pause.kind=session_handoff`、resume artifact 與 source match，並沿用原 ledger 的 counters /
snapshot / drift retry。不得用新 ledger 重置 loop state。

Inner skill HALT 不等於 user decision。若 deterministic marker / validator sidecar 已 PASS，
auto-pass 必須繼續 dispatch；只有 context pressure / runtime pressure 才可寫
`pause.kind=session_handoff` 與 resume artifact。

**Recoverable HALT 必須繼續 dispatch（不可停下等使用者確認）**：

`engineering -> breakdown` 與 `breakdown -> refinement-inbox` 都是 SKILL.md 明文允許的
backward transition，且各自有 loop counter cap。當 inner skill 因 recoverable signal HALT
（plan-defect、verify command typo、scope escalation 等 1-token spec fix）時，auto-pass
**必須**：

1. 更新 ledger `stage_events`，evidence_path 指向 sidecar 絕對路徑。
2. 增對應 `loop_counters` 計數（例如 `engineering_to_breakdown`）。
3. cap check：counter >= 3 才 terminal `loop_cap_reached`；否則直接 dispatch 下一個 owning
   skill，不可停下回報「next step: breakdown」就交還 user。
4. 把 inner skill 的 user-facing "next step" Report 當成 evidence source，**不是** auto-pass
   orchestrator 的 terminal signal。

auto-pass 的合法 terminal 只有：`complete`、`loop_cap_reached`、`blocked_by_gate_failure`
（probe UNKNOWN 或 unrecoverable env issue）、`paused_for_session_handoff`（context /
runtime pressure 且 resume artifact 已寫）。Inner skill 的「Report」邊界不是 orchestrator
邊界；recoverable HALT 自動 loop 才符合使用者啟動 auto-pass 的 consent。

probe result 只能來自 DP-201 proof-of-work marker、task frontmatter 或 validated ledger。若
`scripts/auto-pass-probe.sh` 無法判讀 outcome，terminal 必須是 `blocked_by_gate_failure`；
不可用 inner skill final answer 或 raw prose 補判斷。

Planning backward transition counter 採 source-level cap：`engineering -> breakdown` 與
`breakdown -> refinement-inbox` 任一 counter 達 3 時 terminal `loop_cap_reached`。
`verify-AC -> engineering` 的 implementation drift retry 另計；同一 V item 連續 3 次仍 FAIL 時
terminal `blocked_by_gate_failure`。

**Amendment loop (DP-212)**：`breakdown_to_refinement_inbox` 在 amendment mode 自動 loop，
不是 hard-stop——每次 inbox 出現 → dispatch refinement amendment → 寫回 refinement artifact
→ counter +=1 → 繼續 dispatch breakdown。只有 counter > 3 才 terminal `loop_cap_reached`。
amendment 若命中 LOCKED scope guard（改到 Goal / Background / Decisions / Scope / AC），
`validate-refinement-locked-scope.sh` exit 2 + 標 inbox `rejected_by_scope_guard=true`，
auto-pass 必須 terminal `blocked_by_gate_failure` 並輸出 follow-up DP seed。

## Breakdown Consent Handoff

dispatch `breakdown` 時，envelope 必須包含主 checkout ledger 絕對路徑：

```text
AUTO_PASS_LEDGER_PATH=/absolute/path/to/ledger.json
```

`breakdown` 必須用 ledger validator 確認 schema、source match、三個 consent boolean、
canonical `consent_excludes` enum 與 timestamp ordering。缺 token、relative path、source
mismatch、invalid schema 或 task write 早於 ledger start/resume 都必須 fail-stop。

## Dispatch Envelope Worktree Resolution (D33)

dispatch `engineering` / `verify-AC` 進入 task-scoped 階段時，envelope 必須帶上
`worktree_resolution`，由 `scripts/resolve-task-worktree.sh` 解析：

```bash
bash scripts/resolve-task-worktree.sh \
  --source-id   {SOURCE_ID} \
  --work-item-id {WORK_ITEM_ID} \
  --format json
```

envelope schema：

```json
{
  "worktree_resolution": {
    "status": "FOUND" | "NONE",
    "path": "/absolute/path/to/.worktrees/<repo>-engineering-<KEY>" | null,
    "task_key": "DP-230-T13",
    "resolver_version": 1
  }
}
```

行為合約：

- `FOUND`：path 必須與 resolver 輸出 byte-identical；下游 skill 在該 worktree 內施工 /
  驗收。verify-AC envelope 的 `worktree_resolution.path` 與 resolver 輸出對齊。
- `NONE`（engineering first-cut pre-setup）：若 task 還沒有 engineering branch/worktree
  setup receipt，這是正常初始狀態，不是 user-facing terminal。orchestrator 必須 dispatch
  `engineering`，由 `engineering-branch-setup.sh` 依 authoritative task.md 建立 fresh
  branch/worktree；setup 完成後重新執行 resolver，必須得到 `FOUND` 才能進 implementation /
  verify。
- `NONE`（post-setup / resume / verify-AC）：orchestrator 升 terminal
  `blocked_by_missing_worktree`；不得自己猜測 path 或 fallback 到 main checkout。
- `POLARIS_DISPATCH_WORKTREE_AMBIGUOUS`（resolver exit 2）：orchestrator 必須 fail-stop
  terminal `blocked_by_gate_failure`，不得自選其中一個 path。
- envelope 缺 `worktree_resolution` 欄位 → schema validator fail-stop + stderr
  `POLARIS_DISPATCH_WORKTREE_RESOLUTION_MISSING`。

## Routing Policy

Full development workflow intent 依 source-state matrix route。`{KEY}` 可為 `DP-NNN`
或 JIRA Epic key（例：`GT-NNN`），由 `spec-source-resolver.md` 解析：

| Trigger | Source state | Route |
|---------|--------------|-------|
| `建 DP` / `建一個 DP` | no source container | `refinement`（建立新 DP container） |
| `完整流程 {KEY}` / `快速通關 {KEY}` | `DISCUSSION` / missing artifact / stale artifact | `refinement {KEY}` |
| `完整流程 {KEY}` / `快速通關 {KEY}` | `LOCKED` + current refinement artifact | `auto-pass {KEY}` |
| `{KEY} -> PR -> 升版` | `LOCKED` + current refinement artifact | `auto-pass {KEY}`；report tail 提示 `framework-release` |
| `framework-release {KEY}` | workspace PR opened + verification current | `framework-release` |
| `framework-release {KEY}` | workspace PR opened + verification stale | `auto-pass {KEY}` refresh verify-AC，不重跑 breakdown |
| `auto-pass {KEY} resume` | ledger `pause.kind=session_handoff` + valid resume artifact | resume same ledger |

`auto-pass` 只接 locked/current refinement-owned source；未 LOCK、artifact stale 或 missing
source 的 case 都回 upstream owning skill，不在本 skill 內補 refinement / breakdown artifact。
DP-backed 與 JIRA Epic-backed source 共用同一條 routing matrix。

## Probe Command

T3 起 `auto-pass` 使用 deterministic probe helper。`{SOURCE_ID}` 可為 `DP-NNN`
或 JIRA Epic key；helper 自行依 resolver 結果走對應 container：

```bash
bash scripts/auto-pass-probe.sh {SOURCE_ID}

bash scripts/auto-pass-probe.sh \
  --repo /absolute/path/to/main-checkout \
  --stage source \
  --source-id {SOURCE_ID}

bash scripts/auto-pass-probe.sh \
  --repo /absolute/path/to/main-checkout \
  --stage breakdown \
  --source-id {SOURCE_ID} \
  --work-item-id {SOURCE_ID}-T1 \
  --ledger /absolute/path/to/ledger.json
```

helper 輸出 JSON，至少包含 `stage`、`status`、`terminal_status`、`next_action` 與
`evidence_path`。`status=UNKNOWN` 一律視為 blocked，不可推測 PASS。

## Friction Log Capture (DP-214)

orchestration 過程中遇到下列訊號時，必須立刻呼叫 helper 把摩擦點寫入 ledger
`friction_log[]`，作為下次 refinement / sprint planning 的 signal source。**不可**只在
口頭報告交代：

- inner skill HALT 後又繼續 dispatch（deterministic marker 已 PASS）。
- 手動補 artifact 欄位才能通過 validator。
- 缺 deterministic gate / helper script，本輪靠人類操作補位。
- 必須 set 環境變數才能跑通某個流程。
- validator 與 contract / hook 出現邏輯衝突。
- 產出語言違反 workspace language policy，需手動回拉。

寫入方式：

```bash
scripts/append-auto-pass-friction.sh "$AUTO_PASS_LEDGER_PATH" \
  --stage <source|breakdown|engineering|verify-AC|framework-release|post-task> \
  --kind  <friction_kind_enum_value> \
  --summary "<zh-TW 短語句，建議 280 chars 內>"
```

helper 保證 atomic write、enum 驗證與 soft-limit warning。enum、writer path 與
deterministic trigger map 由 `.claude/skills/references/friction-capture-contract.md`
作為 canonical contract；schema 仍以 `.claude/skills/references/auto-pass-ledger.md`
§ Friction Log 為準。

terminal report 透過 `validate-auto-pass-report.sh` 重新聚合 ledger 條目並驗
`friction_log_summary` 一致；報告不得手寫 summary 數字。

## Auto-Friction Triggers (DP-220)

DP-220 起，下列 5 個 friction signal 由 deterministic trigger 自動寫入
`friction_log[]`，不再依賴 orchestrator 口頭判斷。每個 trigger 都在 helper / hook /
probe / counter 內就近呼叫 `append-auto-pass-friction.sh`，且 helper 內建 NOOP
boundary（`AUTO_PASS_LEDGER_PATH` 未設或 ledger 不存在時 silent exit 0），所以同樣
的 scripts 也能在非 /auto-pass 流程中安全執行。

| Signal | Trigger site | Kind | Notes |
|--------|--------------|------|-------|
| `gate_failure` | `scripts/gate-hook-adapter.sh` | `deterministic_gap` | gate exit 2 後在 gate-failure ledger 寫入之後立刻呼叫 |
| `workaround_taken` | `.claude/hooks/pre-write-language-policy.sh` | `env_bypass` | `POLARIS_LANGUAGE_POLICY_BYPASS=1` explicit bypass；`POLARIS_PRODUCER` 不觸發 |
| `stage_retry` | `scripts/auto-pass-increment-counter.sh` | `inner_skill_halt_bypass` | 同 transition counter 1→2 時 emit；後續 increments 由 counter 自身管理，cap 由 probe ledger_terminal() enforce |
| `probe_unknown` | `scripts/auto-pass-probe.sh` | `deterministic_gap` | `emit(status="UNKNOWN", ...)` 時呼叫；包含 missing marker、invalid JSON、ledger stale 等 |
| `context_pressure` | orchestrator (LLM) | `other` | 寫 `pause.kind=session_handoff` 之前手動呼叫 helper，summary 帶 resume artifact path |

deterministic triggers（前 4 條）已內建在 scripts / hooks，**不需要 orchestrator 主動呼叫**。
context_pressure 是唯一仍由 LLM 主導的 trigger：寫 pause artifact 前必須先呼叫
`append-auto-pass-friction.sh --kind other --summary "context_pressure: ..."`，再寫
`pause` block，否則 terminal report 會缺這次 handoff 的 friction 證據。

Counter 寫入專用 helper：

```bash
scripts/auto-pass-increment-counter.sh "$AUTO_PASS_LEDGER_PATH" \
  --transition <engineering_to_breakdown|breakdown_to_refinement_inbox|verify_ac_to_engineering> \
  --stage <stage>
```

counter 1→2 transition 會自動 append `inner_skill_halt_bypass` friction；orchestrator
仍是 transition 寫入的唯一 caller，但不再需要分別呼叫 counter writer 與 friction
helper。

Trigger 與 enum 對應（refinement 原文 → helper enum）：

- `gate_failure` → `deterministic_gap`
- `workaround_taken` → `env_bypass`
- `stage_retry` → `inner_skill_halt_bypass`
- `probe_unknown` → `deterministic_gap`
- `context_pressure` → `other`

新增 deterministic friction trigger 時，必須在 mechanism-registry 對應 row 加上
`runtime` annotation，並更新本表 + 對應 selftest。

## Skill Workflow Boundary Gate (DP-230 D40)

每段 cross-skill transition（`refinement -> breakdown -> engineering -> verify-AC`，
或回到 `refinement (amendment)`）必須以 deterministic boundary gate 收尾，避免
inner skill session 把 mutation 寫到自己 owning scope 之外：

1. dispatch inner skill 之前先呼叫
   `scripts/skill-workflow-boundary-gate.sh --skill {next_skill} --start --source-container ...`
   建立該 skill 的 session baseline（engineering 額外需 `--task-md`）。
2. inner skill HALT / 完成後，先呼叫
   `scripts/skill-workflow-boundary-gate.sh --skill {prev_skill} --check --source-container ...`
   驗證上一段 skill 只動到自己 owning scope；exit 1 +
   `POLARIS_SKILL_WORKFLOW_BOUNDARY_BLOCKED:{skill}` 視為 deterministic gate failure，
   ledger 寫 `gate_failure` friction、terminal `blocked_by_gate_failure`，不 silently
   進入下一段。
3. 同一 source container 內 refinement / breakdown / engineering / verify-AC 各自
   擁有獨立 baseline（baseline path 以 `{skill}|{container}` hash 區分），
   `/auto-pass` 不得共用同一份 baseline。

bypass env（`POLARIS_LANGUAGE_POLICY_BYPASS`、`POLARIS_SKILL_BOUNDARY_BYPASS`）在
boundary gate 中無效（AC-NEG16）；amendment loop 與 LOCKED scope guard 共用此
gate 作為 cross-skill mutation 保護層。

## Terminal Boundary

`auto-pass` 的成功終點是：

- 最後一次 breakdown PASS snapshot 內所有必要 workspace PR 已 opened / ready。
- verification disposition current。
- durable report produced。

framework workspace 的 merge、sync-to-polaris、tag、GitHub release 與 closeout 只能由
`framework-release` 負責。`auto-pass` report 只能輸出下一步 trigger，不得執行 release tail。

## Final Report

每次 terminal 都必須產生 durable report：

```text
{source_container}/artifacts/auto-pass/YYYYMMDD-HHMMSS-report.json
```

report schema 以 `.claude/skills/references/auto-pass-report.md` 為準，並由
`scripts/validate-auto-pass-report.sh` 驗證。`complete` report 若沒有 issue / blocker /
manual item / follow-up / sunset candidate，不需要 DP seed；其他 terminal 或含 sunset candidate
時必須有 follow-up DP seed reference。

Overlap cleanup disposition 只能使用：

- `keep`
- `narrow`
- `deprecate-note`
- `follow-up-sunset`

`follow-up-sunset` 只建立 follow-up DP seed，不得在同一 PR 刪除 skill、routing row 或行為性
deprecation。framework workspace 下一步若是 release，report 只輸出 `framework-release` tail
trigger，不執行 release。