cash-apply

Project-local Cash CLI bootstrap

執行任何 Cash artifact command 前，MUST 先從目前目錄解析並驗證 Git root，再使用該 root 下的 absolute launcher；不得依賴 PATH 或外部 runtime：

cash_root="$(git rev-parse --show-toplevel)" || exit 1
cash_cli="$cash_root/.cash-skills/bin/cash"
test -x "$cash_cli" || exit 1

同一段 workflow 後續每個 artifact command MUST 使用 "$cash_cli"。

Implement tasks from a Cash change.

Input: Optionally specify a change name (e.g., $cash-apply add-auth). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Task tracking is file-based only. The tasks file's markdown checkboxes (- [ ] / - [x]) are the single source of truth for progress. Do NOT use any external task management system, built-in task tracker, or todo tool. When a task is done, edit the checkbox in the tasks file — that is the only way to record progress.

Prerequisites: The project-local launcher initialized above is required. If root resolution, launcher validation, or a Cash command fails, report the exact error and STOP.

Reader-facing output contract

四個 workflow 的 user-visible status、question、heading 與 summary MUST 先說明結果與下一步，再提供 diagnostics、locations 與其他證據。Cash 內部術語首次出現時，必須用一句繁體中文說明它對使用者的意義。固定 user-visible literals 使用繁體中文：使用計畫檔、使用對話內容、完成、開始實作、使用 change：、仍要繼續、停止、修正後繼續、繼續執行…、實作完成、本次完成、實作已暫停、遇到的問題、Artifacts 一致、發現 N 個問題，正在修正（第 M/2 次）、使用 TDD、不使用 TDD。commands、paths、identifiers、schema fields 與 quoted source text MUST 保持 verbatim；不得以 emoji、顏色或僅有格式差異承載唯一狀態。

Steps

1. Select the change

   If a name is provided, use it. Otherwise:

   • Infer from conversation context if the user mentioned a change
   • Auto-select if only one active change exists
   • If ambiguous, run "$cash_cli" list --json AND "$cash_cli" list --parked --json to get all available changes (including parked ones). Parked changes should be annotated with "(parked)" in the selection list. Use the AskUserQuestion tool to let the user select

   Always announce: "使用 change：" and how to override (e.g., $cash-apply <other>).

   If the AskUserQuestion tool is unavailable, ask the same question or options in plain text and wait for the user's response.

2. Check status to understand the schema

   "$cash_cli" status --change "<name>" --json
   

   If the command fails: show the error and STOP.

   If the command succeeds, check whether the change is parked (status can succeed even for parked changes):

   "$cash_cli" list --parked --json
   

   Look for the change name in the parked array of the JSON output.

   • If the change IS in the parked list (it's parked): Inform the user that this change is currently parked（暫存）. Use the AskUserQuestion tool to ask whether to continue. Two options:

     • 仍要繼續：Unpark the change and proceed with apply
     • 停止：結束 workflow

     If the user chooses to continue:

     "$cash_cli" unpark "<name>"
     

     Then mark it as in-progress:

     "$cash_cli" in-progress add "<name>"
     

     This is a silent operation — do not show the output to the user.

     Then re-run "$cash_cli" status --change "<name>" --json and continue normally.

   • If the change is NOT in the parked list: mark it as in-progress and proceed normally.

     "$cash_cli" in-progress add "<name>"
     

     This is a silent operation — do not show the output to the user.

   Parse the JSON to understand:

   • schemaName: The workflow being used (e.g., "spec-driven")
   • Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)

3. Get apply instructions

   "$cash_cli" instructions apply --change "<name>" --json
   

   This returns:

   • Context file paths (varies by schema)
   • Progress (total, complete, remaining)
   • Task list with status
   • CLI-owned dormancy evidence with status, reason, age_days, and idle_days
   • Dynamic instruction based on current state

   Handle states:

   • Always read missingArtifacts; it is present in every state.
   • If state: "blocked": show the non-empty missingArtifacts list and suggest using $cash-propose to create those artifacts first
   • If state: "all_done": run Pre-gate notes recovery below, then continue to the cash quality gate before any archive guidance
   • If state: "ready": proceed to implementation
   • Any other state or missing required field is a contract error; report it and STOP.

3b. Preflight check

The apply instructions JSON always includes preflight. Treat a missing preflight, missingFiles, driftedFiles, or staleness field as a contract error. Act on preflight.status:

• "clean": silently continue — no output needed.

• "warnings": display a brief summary, then continue automatically:

  ⚠ Preflight warnings:
  - Drifted files (modified after change was created): <list paths>
  - Change is <N> days old
  繼續執行…
  

  Only show the lines that are relevant (skip drifted if none, skip staleness if not stale).

• "critical": display missing files with their source artifact, then use the AskUserQuestion tool to ask the user:

  ⚠ Preflight: missing files detected
  - <path> (referenced in <source artifact>)
  - ...
  These files are referenced in the change artifacts but no longer exist on disk.
  

  Options: 仍要繼續 / 停止 If the user chooses 停止, end the workflow.

3c. Artifact quality check

Run "$cash_cli" analyze <change-name> --json to check cross-artifact consistency (Coverage, Consistency, Ambiguity, Gaps).

• Zero findings: silently continue.
• Warning/Suggestion only: display a one-line summary (e.g., "⚠ Artifact analysis: 2 warnings found") and continue automatically.
• Critical findings: display each Critical finding (summary + location + recommendation), then use the AskUserQuestion tool:
  • 修正後繼續 — fix contract-preserving artifact issues inline, re-run analysis, then proceed. If the fix changes contract/scope or requires a user decision, pause and hand off to $cash-ingest; this choice does not authorize guessing a new contract
  • 仍要繼續 — skip fixes and start implementation
  • 停止 — end the workflow

3d. Consume CLI-owned dormancy evidence

Before any state branch, read and validate dormancy from the apply instructions. The object MUST contain exactly these keys: status, reason, age_days, and idle_days; no key may be missing or unknown. status MUST be one of triggered, fresh, or unknown; reason MUST be a non-empty string; age_days MUST be a non-negative integer; and triggered／fresh require a non-negative integer idle_days while unknown requires idle_days: null (status/null coherence). A missing key, unknown key, wrong type, unknown status, or status/null incoherence is malformed dormancy: report the contract error and stop before any normal state or generic fallback.

cash-apply MUST NOT read created for dormancy, MUST NOT execute Git history queries, and MUST NOT recompute thresholds. The CLI's object is the only dormancy evidence.

• triggered: run "$cash_cli" drift <name> --json and display the complete drift report. If it contains a recommended_action, validate its exact structured shape using the drift routing contract; a report-only fork returns the recommendation and evidence to the main thread, while a main-thread flow presents explicit choices and waits for explicit user authorization before executing apply or ingest.
• fresh: skip a full drift run and continue the existing authorized task flow.
• unknown: report the supplied reason and preserve the evidence gap; do not call it fresh or triggered, and continue only the already authorized apply flow.

For all three statuses, only the validated CLI fields control the branch. No branch may issue a second dormancy calculation or history lookup.

4. Read context files

   Read the files listed in contextFiles from the apply instructions output. The files depend on the schema being used:

   • spec-driven: proposal, specs, design, tasks
   • Other schemas: follow the contextFiles from CLI output

5. Check project preferences

   Resolve the effective TDD setting before reading the remaining project preferences:

   • Find the first unindented line whose prefix is exactly tdd: in openspec/changes/<change>/.openspec.yaml; never scan later tdd: lines after finding it. If its entire suffix is exactly true or false, use that lowercase value as the change-level tdd value and set the source to change-level.
   • If the file has no unindented tdd: line, fall back to the project root .cash.yaml tdd value and set the source to global.
   • Any other suffix, including no space or a tab after the colon, is invalid. Print a warning containing the actual invalid suffix, then fall back to the project root .cash.yaml and set the source to global. Do not silently accept malformed values or inspect a later tdd: line.

   If the effective tdd value is true, apply TDD discipline throughout implementation:

   • Fetch TDD instructions by running "$cash_cli" instructions --skill tdd, then follow the returned instruction

   If the effective tdd value is false, do not apply TDD ordering.

   Regardless of the effective tdd value, when a task will add or modify any test, fetch test-quality instructions by running "$cash_cli" instructions --skill test-quality before the first test edit, then follow the returned instruction. When no test is added or modified, do not fetch it and do not add a test for form's sake.

   Read .cash.yaml in the project root for the remaining preferences. If audit: true is set, apply sharp-edges discipline throughout implementation:

   • When designing APIs or interfaces, evaluate through 3 adversary lenses (Scoundrel, Lazy Developer, Confused Developer)
   • When adding configuration options, verify defaults are secure and zero/empty values are safe
   • When accepting parameters, check for type confusion and silent failures
   • Fetch audit instructions by running "$cash_cli" instructions --skill audit, follow the discipline checklist (not the standalone 3-agent workflow)

   Use mutually exclusive execution modes from the CLI schedule.mode. In document mode only, dispatch the next contiguous [P] group when parallel_tasks: true; sequential fallback preserves explicit attribution for every [P] task. In dependency mode, dispatch only schedule.ready_ids in document order; never infer eligibility from adjacent [P] markers. With parallel tooling and parallel_tasks: true, dispatch independent ready tasks only after proving their allowed regions do not overlap. Otherwise execute ready_ids sequentially; missing parallel tooling never permits violating dependencies. When disjoint scope cannot be proven, serialize or request a dependency update through $cash-ingest.

6. Show current progress

   Display:

   • Schema being used
   • Effective TDD value and source, formatted as TDD: on（change-level）, TDD: off（change-level）, TDD: on（global）, or TDD: off（global）
   • Progress: "N/M tasks complete"
   • Remaining tasks overview
   • Dynamic instruction from CLI

7. Implement tasks (loop until done or blocked)

   Reminder: Track progress by editing checkboxes in the tasks file only. Do not use any built-in task tracker.

   Before processing any pending task, run the Implementation Notes Protocol's File creation rule below against the entry-state progress and implementation evidence. This happens before source edits or parallel dispatch, including partial resumes; do not wait until the quality gate to detect missing historical notes.

   For each pending task:

   • Show which task is being worked on
   • Re-read the sections of design and spec files that are relevant to this task's scope — do not rely on memory from earlier in the conversation, as context may have been compressed
   • Read the Implementation Contract for this task before editing any source file. If design.md exists and contains an ## Implementation Contract section (or contract content under another heading the design uses), read the part of it that covers this task's scope. The contract names the observable behavior, interface or data shape, failure modes, acceptance criteria, and scope boundaries you must satisfy. Treat the contract as the durable handoff — it is what the task will be measured against, regardless of who started the change.
   • Detect unclear or path-only tasks before writing code. A task is unclear if it:
     • only names files to edit ("edit foo.rs", "update bar.svelte") with no behavior, contract, or verification target;
     • is vague ("handle edge cases", "wire it up", "make it work");
     • conflicts with the implementation contract (asks for behavior the contract excludes, or omits behavior the contract requires). When this happens, pause. Either update the artifact (design or tasks) so the task names a concrete behavior and verification target, or report the blocker and wait for guidance. Do NOT silently guess against unclear requirements.
   • Map the task's evidence fields before editing any source file. Every pending task's checkbox description MUST carry non-empty delivery, verification, regression, success, and red fields, and they map onto the canonical discipline as primary target, regression targets, success marker, and failure marker. verification names exactly one primary target; regression names the related regression targets, or is N/A with a reason showing that primary target already covers the full related scope; success describes only the marker directly observable from that primary target and MUST NOT mix in regression, publication, or task completion results; red is N/A with a pure-refactor or remaining-task classification reason when no red phase applies. If any field is missing, holds a placeholder, or — when the effective tdd value is true — the red field contradicts the canonical TDD classification, take the existing unclear-task branch before any production edit: do not guess, do not write production code, and do not call task done.
   • Before writing code, re-read and understand the task, relevant spec, Implementation Contract, and actual call flow. A candidate is eligible only when it preserves observable behavior, interface／data shape, failure modes, acceptance criteria, trust-boundary validation, data-loss prevention, security, and accessibility. A pending task that conflicts with or is unclear against the contract MUST enter the existing unclear-task／blocker triage; MUST NOT use YAGNI to mark it complete or silently skip it.
   • Apply this ordered minimal-solution ladder and stop at the first eligible rung. If an earlier rung does not satisfy the contract, exclude it and continue:
     1. reuse — use an existing codebase helper, type, module, or established pattern.
     2. stdlib — use the language standard library when it fully covers the contract.
     3. native — use a platform, framework, or database native feature when it fully covers the contract.
     4. installed-dependency — use an already-installed dependency when it fully covers the contract; do not add a dependency for this rung.
     5. custom — write the smallest clear custom implementation that fully covers the contract.
   • When multiple candidates are eligible, choose the earlier rung. Within the same rung among candidates of comparable cost, choose stronger edge-case correctness first, then the candidate that follows the existing codebase pattern. A choice among contract-preserving candidates does not create a new pause condition.
   • Then check:
     1. Quality — derive values from existing state instead of duplicating; use existing types and constants over new literals
     2. Efficiency — parallelize independent async operations; avoid unnecessary awaits; match operation scope to actual need
     3. No Placeholders in artifacts — if the design or spec for this task contains placeholder language (TBD, TODO, "add appropriate handling"), pause and fix the artifact first or flag to the user. Do not implement against vague requirements.
     4. Examples as verification — if the spec for this task's scope includes ##### Example: blocks, treat them as high-fidelity acceptance references:
        • Cover every in-scope example's GIVEN/WHEN/THEN input and expected output, including every row of an example table, in the task's verification evidence.
        • Add cases beyond the examples when there is a concrete risk or boundary reason.
        • The examples are not a closed input set.
   • Make the code changes required
   • Keep changes minimal and focused
   • Managed bundle publication — if this task changed Cash-managed runtime or skills, follow the Managed bundle publication protocol in the shared gate below before the next Cash command, including verification commands and task done. Publication is required during the task loop, not only during review fixes. For parallel work, wait for all bundle-writing workers to finish and publish their combined authorized changes before recording any task; attribute generated files and manifest/version updates to the task that produced them rather than letting an automatic diff assign sibling work.
   • Verify before marking done — re-read the task description from the tasks file AND the relevant Implementation Contract content from design.md. For each requirement stated in the task description and each contract item that covers this task's scope, confirm it is addressed by your changes. Before calling task done, require verification evidence appropriate to the task: its named test, CLI, analyzer, or manual assertion must pass. After that primary target passes, run the targets named in the task's regression field; when that field is N/A, confirm its stated reason still holds. If any contract item, task requirement, or verification target is missing or failing, implement/fix it now. Do not mark the task complete until every part of the description is covered and the contract for this task is satisfied.
   • Before dispatch, save the full original task description byte-for-byte. Before tracking, fetch current full apply instructions and compact schedule, then uniquely match that original description to its current CLI ordinal. Require the same pending/ready task and unchanged contract; if the description is absent, duplicated or no longer eligible, stop without tracking. Never reuse a stale ordinal after task-list changes.
   • Mark task complete with the current matched ordinal. In dependency mode, use "$cash_cli" task done --change "<name>" <task-id> --path <path> [--path <path> ...] or explicit --no-files, including sequential execution. Only ordinary non-[P] tasks in document mode may use "$cash_cli" task done --change "<name>" <task-id> for automatic snapshot-diff attribution. This command marks the checkbox in tasks.md AND records which files were modified for this task.
   • Continue to next task

   Parallel task dispatch: Use Step 5's mutually exclusive mode selection: document mode selects consecutive [P] tasks; dependency mode selects eligible ready_ids. When parallel dispatch is enabled and scopes are proven disjoint, dispatch the selected tasks in a single message. Workers MUST NOT edit task checkboxes or run task done; each returns its task ID, verification evidence, and exact project-root-relative source paths it changed (include both endpoints of a rename and tracked deletions; exclude openspec/changes/ and internal state). The main agent verifies each result and serially runs "$cash_cli" task done --change "<name>" <task-id> --path <path> [--path <path> ...]. Use --no-files for a verified task with no source changes, never an omitted file list. Pass raw paths as separately quoted arguments. Shared files may appear in both task lists when both tasks modified disjoint regions; attribution is file-level, not hunk-level. Do not derive worker ownership from a whole-worktree diff. If any dispatched task fails or its file list cannot be established, pause and report; do not mark that task done. Explicit attribution is also required for [P] tasks executed sequentially as a fallback. Only ordinary non-[P] sequential tasks in document mode may retain the automatic snapshot-diff command above; dependency mode always requires explicit attribution.

   Pause if:

   • Task is unclear → ask for clarification

   Refuted premise triage

   在 task loop 的 actual call flow 檢查或驗證執行後，若 evidence 顯示 task／design 的 refuted premise，先執行以下既有兩個互斥 blocker triage 分支。兩個分支優先於 bounded repair 與通用 error／blocker fallback；只有未被涵蓋的其他 failure 才能進入 fallback。

   • 繼續分支（mechanism replacement，contract 不變）：原設計指定的機制在目標平台或現實不可行，但 observable behavior、interface／data shape、failure modes、acceptance criteria 與 scope 全部不變，且替代手段不需要 a synchronization primitive, identity/generation type, or state machine not defined in design.md → 依 Implementation Notes Protocol 記錄 deviation 後繼續且不消耗 bounded repair budget。若在多個都保留 contract 的替代手段之間選擇，也屬此分支，不觸發 pause。
   • 暫停分支（contract／範圍／行為變更）：refuted premise 改變 contract、scope、observable behavior 或 user-visible trade-off，或替代手段需要 a synchronization primitive, identity/generation type, or state machine not defined in design.md，或存在其解答可能改變 contract／scope 的 open question → 記錄 evidence、暫停並導向 $cash-ingest。此分支不得以 generic fallback 或 repair budget 取代。

   兩個分支 MUST 互斥：當繼續分支的條件全部成立時，不得走暫停分支；當任一暫停條件成立時，不得以 deviation 繞過。契約不變的 mechanism replacement 不消耗 bounded repair budget。

   • Other errors or blockers not covered by the blocker triage above → report and wait for guidance
   • User interrupts

Execution evidence protocol

For every named executable verification target in this task loop, preserve恰好一個狀態；四態互斥：passed-current、passed-prior、not-run或blocked。一般執行失敗 MUST be blocked with outcome_kind: failed; an external unavailable prerequisite MUST be blocked with outcome_kind: unavailable，而 blocked evidence MUST preserve command、scope、result/diagnostic 與具體 blocker。Static conformance notes may remain separate, but純靜態 inspection MUST NOT算作 executed pass。

Each execution evidence record MUST contain command、scope、result_source、result，以及 source_fingerprints、test_fingerprints、config_fingerprints、environment_fingerprints 四組 gate-specific identity。每組 identity 要嘛列出目前值，要嘛以具體理由標為不適用；environment identity 至少涵蓋 working directory、執行檔/version 與 target 實際讀取的環境變數。合法 prior 來源只包含仍可引用的原始 command output/host record，或帶有上述完整 shape 的 repository-owned record；摘要性 prose 不是合法來源。

State selection uses deterministic precedence。任何 current execution outcome MUST優先於 passed-prior：current success MUST使用 passed-current，current failed/unavailable MUST使用對應的 blocked outcome kind，兩者都不得被 prior pass 遮蔽。只有本輪完全沒有可歸屬的 execution outcome 且決定重用 prior 時，才逐項比較 relevant identity；全部相符才可使用 passed-prior，任一 prior record/identity gate 缺失或不相符一律 not-run。後續相關 source、test、config 或 environment 變更會使舊的 current/prior pass 失效，必須重新分類。不得以 blocked 掩飾未嘗試。

本 protocol 不新增 Cash CLI command，也不建立新的持久化格式；evidence stays in the current task/review handoff and the named command output。

Bounded repair and minimal parallel worker packet

For a task failure, first apply the上述兩個互斥 blocker triage 分支。機制替換且 contract 不變時，依 Implementation Notes Protocol 記 deviation 後繼續且不消耗 repair budget；contract／範圍／行為變更或需要未定義設計機制時立即走 pause／ingest。Only after neither triage branch matches, classify an Expected behavioral RED (保留 RED evidence、繼續 GREEN、不計入 repair 次數) or a setup、syntax、compile 或 test repair。