cash-propose

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"。

Create a complete Cash change proposal — from requirement to validated artifacts — in a single workflow.

Input: The argument after $cash-propose is the requirement description. Examples:

• $cash-propose add dark mode
• $cash-propose fix the login page crash
• $cash-propose improve search performance

If no argument is provided, the workflow will extract requirements from conversation context or ask.

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.

Response language: All user-facing responses in this workflow MUST be written in Traditional Chinese unless the user explicitly requests another language. Keep shell commands, file paths, code identifiers, schema field names, and quoted source text verbatim.

Steps

1. Determine the requirement source

   a. Argument provided (e.g., "add dark mode") → use it as the requirement description, skip to deriving the change name below.

   b. Plan file available:

   • Check if the conversation context mentions a plan file path (plan mode system messages include the path like <name>.md)
   • If found, check whether that exact conversation-provided plan file path exists
   • If a plan file is found, use the AskUserQuestion tool to ask:
     • Option 1: 使用計畫檔
     • Option 2: 使用對話內容
   • If conversation context has no relevant discussion, mention this when presenting the choice
   • If the user picks the plan file → read it and extract:
     • plan_title (H1 heading) → use as requirement description
     • plan_context (Context section) → use as proposal Why/Motivation content
     • plan_stages (numbered implementation stages) → use for artifact creation
     • plan_files (all file paths mentioned) → use for Impact section
   • If the user picks conversation context → fall through to (c)

   c. Conversation context → attempt to extract requirements from conversation history

   • If context is insufficient, use the AskUserQuestion tool to ask what they want to build

   From the resolved description, derive a kebab-case change name (e.g., "add dark mode" → add-dark-mode). Do not keep archive-style date prefixes in active change names. If the source name starts with YYYY-MM-DD-, strip that date prefix before running "$cash_cli" new change; archived change names and directories are historical references, not active names to reuse.

   IMPORTANT: Do NOT proceed without understanding what the user wants to build.

2. Classify the change type

   Based on the requirement, classify the change into one of three types:

   Type	When to use
   Feature	New functionality, new capabilities
   Bug Fix	Fixing existing behavior, resolving errors
   Refactor	Architecture improvements, performance optimization, UI adjustments

   This determines the narrative emphasis in ## Motivation and ## Proposed Solution.

3. Scan existing specs for relevance

   Before creating the change, check if any existing specs overlap:

   1. Use the Glob tool to list all files matching openspec/specs/*/spec.md
   2. Extract directory names as the spec identifier list
   3. Compare against the user's description to identify related specs (max 5 candidates)
   4. For each candidate (max 3), read the first 10 lines to retrieve the Purpose section
   5. If related specs are found, display them as an informational summary

   IMPORTANT:

   • If related specs are found, display them but do NOT stop or ask for confirmation — continue to the next step
   • If no related specs are found, silently proceed without mentioning the scan

3b. Read open signals for prioritization (cash-propose only)

After scanning existing specs, read the signals under openspec/signals/ whose frontmatter status is open, and use them to inform how you prioritize this change's scope. This step belongs to cash-propose only.

• Read every signal file under openspec/signals/ and keep only those whose frontmatter status is open. Selecting which open signals are relevant to the current requirement is best-effort agent judgment.
• Surface the relevant open signals as an INFORMATIONAL prioritization summary — for example, which recurring issue classes or frictions might relate to this change — to help decide what to include in or exclude from scope.
• This read is purely informational. It MUST NOT block the workflow, MUST NOT require user confirmation to continue, and MUST NOT modify, create, or delete any signal. Read signals only; never write them.
• If openspec/signals/ is absent or contains no open signal, continue SILENTLY without printing any summary.

4. Create the change directory

   Before creation, resolve whether the selected name is active, parked, archived, or absent using "$cash_cli" list --json and "$cash_cli" list --parked --json, and inspect an existing active change's status and artifacts. An explicit request to continue a named active change selects resume without another confirmation. If the name merely collides with a newly derived name, ask whether to resume or choose another name. Parked changes require an explicit unpark decision before resuming; archived identities are historical and must not be overwritten or reused.

   Resume branch: do not run new change. Read existing artifacts and "$cash_cli" status --change "<name>" --json; retain the existing schema, TDD choice, completed tasks, and review history. If the requested requirement changes existing scope or decisions, hand off to $cash-ingest <name> with the agreed update and end this propose run. Otherwise continue step 4b, skip creation of every existing artifact, and create only missing artifacts in dependency order. Inventory expected capability spec paths from the proposal even when CLI status reports specs as done; fill missing capability files before treating applyRequires as complete. Validate the completed set and use the existing review re-run rules; allocate round filenames after the highest existing number even when the previous run passed, and never overwrite completed round files.

   New branch: only when the name is absent, select no-spec only when no capability observable behavior changes; tooling or file extensions alone do not qualify. If spec impact is uncertain, select spec-driven. Create every new change with --task-order dependency; resume preserves the existing schema and task order. Then run:

   "$cash_cli" new change "<name>" --agent codex --schema "<selected-schema>" --task-order dependency
   

   If creation nevertheless reports an identity collision, stop and report it; do not overwrite or blindly retry.

4b. Record this change's TDD choice

After a new change succeeds, or at the same point when continuing an existing change, read openspec/changes/<name>/.openspec.yaml before writing the proposal.

• If an unindented tdd: line already exists, skip this question and do not append another line. This is the mechanical once-per-change check for both new and continue paths.
• If the line is absent, use the AskUserQuestion tool to ask whether this change should use TDD. Offer exactly two choices:
  • 使用 TDD — recommended for behavior changes or large scope; record true.
  • 不使用 TDD — recommended for documentation, metadata, or small behavior-preserving refactors; record false.
• The existing Guardrails interaction fallback applies to this question.
• After the user answers, append exactly one unindented line: tdd: true or tdd: false, terminated by LF. If .openspec.yaml is non-empty and does not end with LF, write exactly one LF separator before the new line so the existing tail and the new key cannot merge. Preserve the content of every existing line and do not modify .cash.yaml.
• If the append fails, report the exact write error and stop the workflow. Do not continue to proposal authoring with an unrecorded choice.

5. Write the proposal

   On resume, if proposal.md exists, read and reuse it, skip its new artifact command, and proceed to the impact advisory and step 6. Existing content that needs correction is edited during validation/review, not recreated with new artifact.

   IMPORTANT — file path rules for the ## Impact section:

   • All file paths SHALL be written relative to the project root (e.g., src/lib/foo.ts, src-tauri/crates/core/src/bar.rs, openspec/specs/auth/spec.md).
   • Do NOT use relative fragments (e.g., parser/mod.rs, core/mod.rs) — preflight rejects them as non-anchored paths.
   • Do NOT wrap shell commands in backticks inside artifact text (e.g., `git mv a.rs b.rs`) — preflight's backtick extractor will otherwise mis-parse the command as a file reference.
   • When referring to a file without naming its concrete path, use descriptive prose (e.g., "Parser 入口檔") rather than a backticked path fragment.

   Get instructions:

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

   For no-spec, write exactly - Affected specs: none inside ## Impact and keep both New/Modified Capabilities sections empty or (none). Use only the selected schema graph: do not create or require delta specs for no-spec; design, tasks, validation and the full quality gate still apply.

   Use the template returned by the CLI as the proposal structure. Fill in every section, using the change type to guide the narrative emphasis, then write the content via CLI:

   "$cash_cli" new artifact proposal --change "<name>" --stdin <<'ARTIFACT_EOF'
   <proposal content>
   ARTIFACT_EOF
   

   If the command fails with a validation error, fix the content and retry.

   cash-propose impact granularity advisory

   • After writing the proposal and before creating design.md, count the affected-code path entries under proposal ## Impact across Modified, New, and Removed.
   • Exclude (none) placeholder lines. Count a directory entry as one entry, so the result is a lower bound.
   • When the affected-code path count exceeds 15, print an informational warning containing the count and recommend splitting the change by capability.
   • When the count is 15 or fewer, print nothing.
   • Treat 15 entries as silent and 16 entries as advisory.
   • This advisory MUST NOT block the workflow or require user confirmation.

6. Get the artifact build order

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

   Parse the JSON to get:

   • applyRequires: array of artifact IDs needed before implementation
   • artifacts: list of all artifacts with their status and dependencies

7. Create remaining artifacts in sequence

   Loop through artifacts in dependency order (skip proposal since it's already done):

   a. For each artifact that is ready (dependencies satisfied):

   • On resume, do not recreate an existing file even if the artifact is incomplete. Read it and retain its content; create only missing output files (for specs, compare the required capability paths individually). Correct invalid existing content through edits during validation, without discarding completed tasks. 停止並導向 ingest if the correction changes the requested contract or scope.

   • Check if the artifact is optional: If the artifact is NOT in the dependency chain of any applyRequires artifact (i.e., removing it would not block reaching apply), it is optional. Get its instructions and read the instruction field. If the instruction contains conditional criteria (e.g., "create only if any apply"), evaluate whether any criteria apply to this change based on the proposal content. If none apply, skip the artifact and show: "⊘ Skipped (not needed for this change)". Then continue to the next artifact.

   • Get instructions:

     "$cash_cli" instructions <artifact-id> --change "<name>" --json
     

   • The instructions JSON includes:

     • context: Project background (constraints for you - do NOT include in output)
     • rules: Artifact-specific rules (constraints for you - do NOT include in output)
     • template: The structure to use for your output file
     • instruction: Schema-specific guidance
     • outputPath: Where to write the artifact
     • dependencies: Completed artifacts to read for context
     • locale: The language to write the artifact in (e.g., "Japanese (日本語)"). If present, you MUST write the artifact content in this language. For spec files (specs/*/.md), the Spec-file language policy below takes precedence over locale.

   • Read any completed dependency files for context

   • Generate the artifact content using template as the structure

   • Apply context and rules as constraints - but do NOT copy them into the file

   • Write the artifact via CLI (the CLI handles directory creation and format validation):

     For design or tasks:

     "$cash_cli" new artifact <artifact-id> --change "<name>" --stdin <<'ARTIFACT_EOF'
     <content>
     ARTIFACT_EOF
     

     For specs (one command per capability):

     "$cash_cli" new artifact spec <capability-name> --change "<name>" --stdin <<'ARTIFACT_EOF'
     <delta spec content>
     ARTIFACT_EOF
     

     If the command fails with a validation error, fix the content and retry.

   • Show brief progress: "✓ Created "

   b. Continue until all applyRequires artifacts are complete

   • After creating each artifact, re-run "$cash_cli" status --change "<name>" --json
   • Check if every artifact ID in applyRequires has status: "done"
   • Stop when all applyRequires artifacts are done

   c. If an artifact requires user input (unclear context):

   • Use AskUserQuestion tool to clarify
   • Then continue with creation

   Artifact language for cash-propose

   All change artifacts produced by cash-propose (proposal.md, design.md, tasks.md, and any other non-spec artifact under openspec/changes/<change>/) MUST be written in Traditional Chinese, regardless of whether the CLI provides a locale field.

   This applies to artifacts generated in step 5 (proposal) and step 7 (remaining artifacts), and to any artifacts modified during the review loop fix actions.

   Spec-file language policy (delta and master specs):

   • openspec/changes/<change>/specs/<capability>/spec.md (delta spec)
   • openspec/specs/<capability>/spec.md (master spec)

   Spec files are written in Traditional Chinese prose with English structural keywords. Keep the following verbatim in English: ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements, ### Requirement:, #### Scenario:, ##### Example:, and the GIVEN / WHEN / THEN / AND step markers. Normative verbs (SHALL / MUST / SHOULD / MAY and their NOT forms) stay in English embedded inside Chinese sentences. Code identifiers, file paths, CLI commands, schema field names, and quoted source text stay verbatim. Requirement titles are written in Chinese; every title under ## MODIFIED Requirements or ## REMOVED Requirements, and the FROM title of every ## RENAMED Requirements entry, MUST be copied byte-for-byte from the current master spec — never retyped, reworded, or translated — because "$cash_cli" archive matches requirement titles verbatim and fails closed with requirement_identity_mismatch when a title does not match. Historical spec files under openspec/changes/archive/ are historical records and are not retroactively translated.

   Keep the following verbatim (do not translate) even inside Chinese prose:

   • Shell commands and CLI flags
   • File paths (absolute or repo-relative)
   • Code identifiers (function names, variable names, type names)
   • Schema field names (e.g., applyRequires, outputPath, dependencies)
   • Artifact IDs and capability slugs
   • Quoted source text from existing artifacts

   If the user explicitly requests another language later, follow the latest user instruction.

   The goal is predictable Chinese-facing artifacts for cash-propose while preserving exact technical references and keeping spec deltas compatible with master specs.

Artifact readiness gate

cash-propose 與 cash-ingest 在 inline self-review 後、validation 與品質關卡前 MUST 使用相同的 bounded readiness gate。這個 gate 是有限的 artifact 準備度檢查：它只在有具體修正與新證據時消耗 correction budget。

Analyze-Fix Loop

執行 "$cash_cli" analyze <name> --json，並對每個 failing gate 最多兩次 correction。一次 correction 必須先指出具體 diagnostic 或新證據，實際修改受影響 artifact，再重跑同一 gate。只重跑 command、改寫 diagnostic、改變輸出 scope 或重新分類 MUST NOT 算作 progress，也 MUST NOT 重置 budget；若相同 diagnostic 沒有新進展，立即停止該 gate。

Analyze 的 diagnostic signature multiset identity 使用 (dimension, severity, stable_location)；stable_location 與 validation 的 stable_path 只移除 terminal :<decimal-line>，保留其餘 path 或 location。Analyze identity 忽略 positional id、finding 順序、summary、recommendation 與其他可改寫 prose；validation identity 使用 (code, stable_path)，忽略 finding 順序與 message。兩者都必須保留相同 signature 的 occurrence count；reorder、summary／recommendation／message reword、無關 line shift 或無關 bytes edit 都不算 progress。無效、無關或只改文案的 edit MUST NOT 重置 budget。只有原 occurrence 消失，或由 dimension、severity 或 stable location 不同的 signature 取代，才算該 finding 有 progress。

Suggestion 只作 advisory，先排除於 readiness 計數之外。排除 Suggestion 後，Critical／Warnings-only／clean 三個結果互斥且完整：有 Critical 是 Critical；沒有 Critical 但有 Warning 是 Warnings-only；兩者皆無是 clean，即使仍有 Suggestion。Warnings-only 可進入 validation 或完成摘要，但必須逐項保留，不得以「已解決」或等義文字描述。

JSON validation gate

Analyze gate 通過後執行 "$cash_cli" validate "<name>" --json。Validation 也使用相同的最多兩次 correction、具體 diagnostic／新證據、實際 artifact edit、signature multiset、progress 與重複 diagnostic 停止規則；validation 未通過不得進入完成或 review 分支。

Not-ready handoff

Critical 尚存或 validation 未通過時，第一段先回報 not ready，再列出 locations、原因與下一步。此 not-ready branch 優先於通用完成或 handoff fallback；不得顯示 ready completion、提供開始實作選項或 invoke cash-apply。

Grounded artifact claims

在 proposal、design 或 task 寫下 grounded code-facing claims（現有 code、tests、configuration 或 runtime behavior）前，先讀取 claim 具名的最小來源範圍，並保存 path 與 symbol、heading 或 command；line number 不得是唯一定位。找不到支持時，移除事實斷言，或改寫為待驗證 task，或在會改變 contract／scope 時詢問使用者；不能把推測寫成事實。

Artifact 中的 size、count、duration、percentage、frequency 或 performance 數字必須標為 measured、estimated 或使用者／規格直接指定的 contract value。measured 必須記錄 observation method 與 result source；estimated 必須具名可確認或推翻該數字的 measurement，並列出依賴該估算的決策。

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、顏色或僅有格式差異承載唯一狀態。

9. Validation

   "$cash_cli" validate "<name>" --json
   

   Read the JSON result. If validation fails after the bounded correction budget, use the not ready handoff above: report locations, reasons and next steps, do not enter the quality gate, and do not invoke cash-apply. Enter the quality gate only when validation has passed.

10. Sub-Agent Review/Rating/Fix Loop

Run this review/rating/fix loop once per change, after the normal workflow has completed its required artifact or task work.

Entry conditions

• For cash-propose, start this loop only after proposal, design, specs, and tasks artifacts required for apply are complete AND "$cash_cli" validate "<name>" has passed. If validation fixes are required, complete them before entering this loop.
• For cash-apply, start this loop only after all implementation tasks are complete and tasks.md 全 [x], and Pre-gate notes recovery has checked or reconstructed implementation-notes.md.
• Do not run this loop per artifact or per task; the granularity is per-change.

Managed bundle publication

• This protocol applies to cash-apply task edits and to either workflow's review/self-check edits. After changing managed runtime, either canonical skill variant, or bundle version, complete publication before the next Cash command (including validate, instructions, touched, and task done), not merely before the next reviewer. Ordinary application/artifact edits do not trigger publication.
• Identify the installation mode and the initially verified bundle before editing. Do not treat unexplained pre-existing runtime/skill drift as part of this task or silently bless it. If the installer or launcher rejects an invalid/unsafe state, preserve its diagnostic and stop; do not hand-edit manifest digests, use --init-receipt, or automatically force an unrelated overwrite.
• In the canonical source repository, edit the .claude source or variant rules, run fish scripts/cash-skills/generate.fish when generation inputs changed, and keep cash-skills.version and the installer's BUNDLE_VERSION aligned and newer than the committed bundle when skills changed. Run relevant non-Cash generation/content checks, then ./install-cash-skills.fish --self to publish the portable manifest. This maintains the manifest, not a receipt. A failed generation or publication stops the workflow before any further Cash command. Do not publish while parallel workers are still writing managed files.
• In a vendored or receipt-based target, do not run source-only --self or reissue a receipt for edited content. Use the trusted source installer with the target's existing publication mode (--vendor <target> or --target <target>) only when that source contains the requested changes and the update is authorized. Preserve local edits; do not reinstall over them to clear an error. If the trusted source or a safe publication path is unavailable, stop and report the missing prerequisite. Unknown installation modes also stop.
• After successful publication, resume required verification and task/output recording. If a later fix changes managed bytes again, publish again before the next Cash command. Retain the instruction version with which an already-active review loop began.

Pre-round mechanical self-check (main agent, inline)