@jakkrichm/create-nexus-devflow 2.16.3 → 2.17.0

package/template/.agents/skills/feature/SKILL.md

@@ -126,6 +126,10 @@ build plan starts high-level.
 
 ## Step 3 - write the spec
 
+Before review, allocate the selected feature ID's build attempt using
+`reference/build-history.md`: first build 1, otherwise one greater than
+the maximum proven prior attempt after all prior builds were reversed. For attempt N > 1, append `--build-N` to the slug and archive path (e.g. `086-export--build-2.md`).
+
 For the one (sub-)feature being built now, allocate sequential ID (`xxx-slug`) and create a dedicated workspace at `devflow/context/{xxx-slug}/`. Write the full living spec to
 `devflow/context/{xxx-slug}/spec.md`, following `reference/feature-spec-template.md`. Also initialize `stage.md` and `findings.md` in that folder. The first heading and build-plan identity must use this canonical form:
 
@@ -133,8 +137,10 @@ For the one (sub-)feature being built now, allocate sequential ID (`xxx-slug`) a
 # Feature: <title>
 
 **From build-plan:** feature <id>
+**Build attempt:** <positive integer>
 ```
 
+
 Fill every section:
 - Goal, Problem Statement, and In/Out of scope
 - Acceptance Criteria (AC-1, AC-2, ...)

package/template/.agents/skills/feature/reference/build-history.md

@@ -0,0 +1,79 @@
+# Build history identity
+
+Read metadata from the archived original spec, not appended findings or review.
+Read the feature ID from its `**From build-plan:**` or supported legacy
+feature field, not its title or filename. Normalize the numeric part by removing
+leading zeros and the optional letter to lowercase (`012A` becomes `12a`). Match
+that complete ID, never a substring. Use the archived spec's positive integer
+`**Build attempt:**`; duplicate or malformed fields stop selection. A legacy
+first-build archive without it counts as attempt 1 only when its spec identity
+and unsuffixed `NN-name.md` path agree unambiguously. Derive the expected name
+from its own spec, not today's renamed plan title. Text such as `Build 2` in a
+title proves no attempt.
+For new paths, pad the numeric part to at least two digits, keep its letter, and
+use the spec title's lowercase kebab-case slug. Append `--build-N` only for N > 1.
+An archive declaring an attempt must agree with that computed path.
+The double hyphen is reserved: slug normalization collapses punctuation runs to
+one hyphen, so a first build titled `Export Build 2` uses `04-export-build-2.md`,
+while a later attempt 2 titled `Export` uses `04-export--build-2.md`.
+
+Before freezing a new spec, check its exact planned archive path in `devflow/history/features/` and branch.
+Require `lstat` to return `ENOENT` for the archive leaf; any existing entry,
+including a dangling symlink, blocks it. Present parents must be ordinary
+directories. Require a valid branch name and no existing or namespace-conflicting
+local branch ref (inspect `git for-each-ref refs/heads/`, including packed refs).
+Also require no prior use of the archive path in available Git history:
+
+```bash
+git log --all --reflog --full-history --format=%H -- <planned-archive-path>
+```
+
+Any result or inspection failure stops before spec review with the exact collision.
+Do not auto-bump the attempt or rename reviewed work to avoid it. These checks
+apply to new specs; existing completion must run its recovery routing first so
+its own archive is reconciled rather than rejected. Preserve already-reviewed
+legacy spec bytes, branch, and any proven recovery destination.
+
+A legacy rebuild can preserve a reviewed spec without this field. Its completion
+annotation must freeze the original `baseCommit`: resolve only prior builds and
+their completed reversals present at that base, derive `max(attempts) + 1`, and
+require the exact resulting archive path. For an integrated archive, its unique
+introducing commit's sole parent must equal that base. For unfinished completion,
+use Complete's phase proof. The path checks this derived attempt; it never supplies
+the number. Missing or ambiguous proof stops without rewriting the archived spec.
+Settled history numbering and rollback selection do not require the annotation's
+historical `head` or `sourceTree`; actual completion recovery still requires them.
+
+Before using prior builds or reversals, prove each selected record on the local
+default branch. Resolve the unique introducing commit with:
+
+```bash
+git log --full-history --diff-filter=A --format=%H <local-default> -- <archive-path>
+git log --full-history --format=%H <introducing-commit>..<local-default> -- <archive-path>
+```
+
+The first result must contain exactly one commit which actually adds the path;
+the second must be empty. Confirm the current blob and mode equal that addition
+(use Git's normal EOL normalization for a working-file comparison). Inspect the
+record at that commit, not an uncommitted replacement. Reject orphan, overwritten,
+deleted/re-added, renamed, multiply-added, or conflicting records. Never choose
+the newest commit, file count, or timestamp to resolve ambiguity.
+
+A build is reversed only by a completed `**Type:** Rollback` record in `devflow/history/rollbacks/` with its exact
+`**Target archive:**` and full `**Target commit:**`, matching feature ID, verified
+or complete status and finished steps. Its `Target parent` must match the target's
+sole parent. Prove that rollback record's unique unchanged addition
+by the same procedure, reachable on the local default after the target build.
+Require a non-merge rollback commit containing that record and its completed
+plan bookkeeping. Uncommitted, malformed, changed, or merely rollback-looking
+files are not completed reversals. Conflicting or duplicate reversals stop.
+
+Include exact rollback references retained on the selected plan line; missing
+referenced records are a blocker, not an empty history. For a new unchecked feature,
+use 1 when there are no prior records; otherwise
+require every prior build to have one proven completed reversal and allocate
+`max(attempts) + 1`. Duplicate attempts or inconsistent/missing history stop with
+the exact paths and missing proof. Search only this feature's records and their
+exact reversal references. Ignored local-only history without introducing-commit
+proof cannot establish a rebuild or rollback target; stop without force-adding or
+migrating it. Ordinary first builds do not require prior history.

package/template/.agents/skills/idea/SKILL.md

@@ -26,32 +26,32 @@ When invoked:
 3. Allocate the next sequential ID (e.g. `IDEA-001`, `IDEA-002`).
 
 ### 2. AI Feasibility & Value Analysis
-Evaluate the user's raw idea and generate an enriched summary in **Thai (`th`)**:
-- **ไอเดียตั้งต้น (Raw Idea)**: ข้อความที่ผู้ใช้ระบุ
-- **AI Feasibility & Tech**: ประเมินความเป็นไปได้ (ง่าย / ปานกลาง / ซับซ้อน) พร้อมแนะนำ Library, API, หรือแนวทางเทคนิคเบื้องต้น
-- **Value & Potential**: คุณค่า ประโยชน์ และความน่าสนใจของฟีเจอร์นี้
-- **Quick Seed (สรุปประเด็นกันลืม)**: 2-3 ประเด็นทางเทคนิคหรือแนวทางการต่อยอด เพื่อให้กลับมาอ่านทีหลังแล้วจำบริบทได้ทันที
+Evaluate the user's raw idea and generate an enriched entry in Thai (`th` per user communication rules):
+- **Raw Idea**: The user's input description
+- **AI Feasibility & Tech**: Feasibility rating (Easy / Medium / Complex) along with recommended libraries, APIs, or architectural approaches
+- **Value & Potential**: Business value, user benefits, and strategic impact
+- **Quick Seed**: 2-3 key technical nuances or seed points to preserve context for later pickup
 
 ### 3. Append to `devflow/ideas.md`
 Insert the new idea block directly under `## 📌 Pending Ideas` in `devflow/ideas.md`:
 
 ```markdown
-### [IDEA-001] {หัวข้อไอเดียสั้นๆ}
+### [IDEA-001] {Brief idea title}
 - **บันทึกเมื่อ**: {YYYY-MM-DD}
-- **ไอเดียตั้งต้น**: {ข้อความที่ผู้ใช้ป้อน}
-- **AI Feasibility & Tech**: {บทวิเคราะห์ความเป็นไปได้และเครื่องมือ}
-- **Value & Potential**: {บทวิเคราะห์คุณค่าและความน่าสนใจ}
+- **ไอเดียตั้งต้น**: {User's raw idea text}
+- **AI Feasibility & Tech**: {Feasibility and tooling analysis}
+- **Value & Potential**: {Value and impact analysis}
 - **Quick Seed (กันลืม)**:
-  1. {ประเด็นสำคัญที่ 1}
-  2. {ประเด็นสำคัญที่ 2}
-- **สถานะ**: `Pending` (หยิบไปทำได้ด้วย `/feature IDEA-001` หรือ `/discovery IDEA-001`)
+  1. {Key point 1}
+  2. {Key point 2}
+- **สถานะ**: `Pending` (Ready for pickup via `/feature IDEA-001` or `/discovery IDEA-001`)
 ```
 
-*(หากมีข้อความ `*(ยังไม่มีไอเดียค้างอยู่...)*` ให้ลบออกเมื่อมีไอเดียแรก)*
+*(If placeholder `*(ยังไม่มีไอเดียค้างอยู่...)*` exists, remove it upon recording the first idea)*
 
 ### 4. Output Summary
 Report to the user:
 - Allocated Idea ID: `[IDEA-xxx]`
 - Summary of Feasibility & Value analysis
 - Seed points saved
-- Instructions for promotion: "เมื่อพร้อมลงมือทำ สามารถพิมพ์ `/feature IDEA-xxx` หรือ `/discovery IDEA-xxx` ได้ทันที"
+- Instructions for promotion: "Ready to implement? Run `/feature IDEA-xxx` or `/discovery IDEA-xxx` anytime."

package/template/.agents/skills/rollback/SKILL.md

@@ -53,16 +53,23 @@ skill.
 
 ## Step 1 - resolve the exact feature
 
-Match the requested number or name against both the checked build-plan items and
-`devflow/history/features/*.md`. Exclude the directory README.
-
-Use the archive path to locate the commit that added it:
-
-    git log --diff-filter=A --format="%H %s" HEAD -- <archive-path>
-
-Use the newest matching commit reachable from the current branch. Confirm the
-archive was added by that commit and its subject and diff are consistent with the
-requested feature. If the target is a merge commit, stop before Step 2 and before
+Resolve the requested number or name to one checked build-plan ID; for an archive
+path, read its exact spec identity first and match that checked item. Then gather
+all exact-ID feature archive candidates using `../feature/reference/build-history.md`.
+Normalize the stable ID, retaining its letter, and read attempts from verified
+spec metadata/history proof, never arbitrary title or filename suffixes.
+
+For each candidate, require its unique introducing commit on the local default
+and prove the archive blob and mode have not changed since that addition. Exclude
+builds with a proven completed reachable rollback naming that exact archive and
+introducing commit. The checked item must have exactly one unreversed build.
+An explicit archive request stays bound to that exact path: reject it if already
+reversed, rather than silently choosing another build. Ambiguous, orphan,
+overwritten, multiply-added, or missing records stop with their exact paths and
+missing proof. Do not select by newest commit, filename order, or rollback date.
+
+Confirm the selected commit's diff is consistent with the requested feature.
+If the target is a merge commit, stop before Step 2 and before
 writing or changing `devflow/context/{xxx-slug}/spec.md`. Do not record a
 target parent or choose a mainline. Publish `blocked` to
 `devflow/.state/run.json`, explain that DevFlow cannot safely infer which
@@ -129,6 +136,12 @@ Allocate sequential ID (`xxx-slug`) and create `devflow/context/{xxx-slug}/`. Wr
 - compatibility work that is allowed, if any
 - exact verification commands and observable removal criteria
 
+Before freezing a new rollback spec, apply the archive-path and branch-availability
+checks in `../feature/reference/build-history.md` to its planned branch and
+`YYYY-MM-DD-<exact-target-archive-stem>.md` destination. Retain `--build-N` in the
+target stem when present. A collision stops for an explicit decision; never
+renumber the target or silently rename reviewed work. Existing completion recovery runs first.
+
 The first build step must apply the target commit's product diff in reverse using
 the guarded Type: Rollback behavior in `/implement`. Later steps may repair only
 the specific downstream compatibility issues named in the spec. Do not use a

package/template/.claude/skills/analyze/SKILL.md

@@ -21,10 +21,10 @@ contract in `AGENTS.md`.
 ```text
 # 1. Ingest specific file from any path (PDF, DOCX, XLSX, Image, CSV, Text)
 /analyze C:\Users\...\Downloads\customer-spec.pdf
-/analyze ./mockup.png ./schema.xlsx "ระบบสะสมแต้มสมาชิก"
+/analyze ./mockup.png ./schema.xlsx "Loyalty point system"
 
 # 2. Ingest raw text or requirement from chat
-/analyze "ลูกค้าต้องการระบบผ่อนชำระ 0% เชื่อมกับ KBank Payment Gateway..."
+/analyze "Customer requested 0% installment plan connected to KBank Payment Gateway..."
 
 # 3. Scan pending unassigned files in devflow/inbox/
 /analyze
@@ -46,50 +46,50 @@ contract in `AGENTS.md`.
 
 ---
 
-### Step 1: Auto-Allocate Workspace & Ingestion (Frictionless Ingest)
+## Step 1: Auto-Allocate Workspace & Ingestion (Frictionless Ingest)
 1. **Allocate REQ-ID**: Generate sequential ID format `REQ-YYYYMMDD-NNN` (e.g. `REQ-20260903-001-point-system`).
 2. **Create Request Workspace**:
    ```text
    devflow/inbox/{REQ-ID}/
-   ├── raw/                # เก็บไฟล์ต้นฉบับ (PDF, Word, Excel, Images, Email)
-   ├── parsed.md           # ข้อความ/ตารางที่สกัดออกมาแล้ว (Clean Markdown)
-   └── clarifications.md   # รายการคำถามที่ต้องไปถาม Stakeholder เพิ่ม
+   ├── raw/                # Original source files (PDF, Word, Excel, Images, Email)
+   ├── parsed.md           # Extracted structured text/tables (Clean Markdown)
+   └── clarifications.md   # Questions and clarifications checklist for stakeholders
    ```
 3. Copy or save incoming files into `devflow/inbox/{REQ-ID}/raw/`.
 
 ---
 
-### Step 2: Parse & Normalize Requirement (`parsed.md`)
+## Step 2: Parse & Normalize Requirement (`parsed.md`)
 1. Extract text and tables from all raw files:
    - For Office/PDF docs: Invoke `convert-any-to-md` or document extractor.
    - For Web URLs / Confluence / Notion: Invoke `defuddle`.
    - For Images / Wireframes / Screenshots: Conduct Multimodal Vision OCR and describe layout and fields.
 2. Structure into `devflow/inbox/{REQ-ID}/parsed.md`:
-   - **Executive Summary**: วัตถุประสงค์หลักของ Requirement
-   - **Target Persona & User Stories**: ใครทำอะไร เพื่ออะไร
-   - **Functional Requirements (FR)**: รายการฟังก์ชันและ Business Rules
-   - **Non-Functional Requirements (NFR)**: Performance, Security, PDPA, Retention
-   - **Data Entities & Fields**: ฟิลด์ข้อมูลและชนิดข้อมูลเบื้องต้น
+   - **Executive Summary**: Core purpose and business objective of the requirement
+   - **Target Persona & User Stories**: Who performs what action and why
+   - **Functional Requirements (FR)**: List of functions and business rules
+   - **Non-Functional Requirements (NFR)**: Performance, Security, PDPA/Privacy, Data Retention
+   - **Data Entities & Fields**: Data fields, schemas, and initial types
 
 ---
 
-### Step 3: Codebase Impact & Blast Radius Analysis (`codebase-impact.md`)
-*(ดำเนินการเมื่อเป็นระบบเดิม / Brownfield Codebase)*
+## Step 3: Codebase Impact & Blast Radius Analysis (`codebase-impact.md`)
+*(Execute when operating on an existing system / brownfield codebase)*
 
 1. Search codebase patterns using `grep_search`, `rg`, and AST analysis for affected models, controllers, APIs, and routes.
 2. Calculate **Blast Radius & Complexity Score**:
-   - **Affected Files & Modules**: รายการไฟล์ที่ต้องแก้ไขหรือสร้างใหม่
-   - **API & Contract Breaking Risk**: ตรวจสอบว่ากระทบกับ API เดิมหรือ Third-Party หรือไม่
-   - **Complexity Rating**: `Low` | `Medium` | `High` | `Extreme` พร้อมเหตุผล
+   - **Affected Files & Modules**: List of files to be modified or newly created
+   - **API & Contract Breaking Risk**: Check if existing APIs or third-party contracts are impacted
+   - **Complexity Rating**: `Low` | `Medium` | `High` | `Extreme` with rationale
 3. Save analysis report to `devflow/analysis/{REQ-ID}/codebase-impact.md`.
 
 ---
 
-### Step 4: Socratic Gap Detection & Clarification Checklist (`clarifications.md`)
+## Step 4: Socratic Gap Detection & Clarification Checklist (`clarifications.md`)
 1. Apply `grilling` and `domain-modeling` lenses to detect gaps:
-   - **Missing Edge Cases**: เงื่อนไขขอบ, กรณีข้อมูลผิดพลาด, เน็ตหลุด, Concurrent Requests
-   - **Ambiguous Business Rules**: กฎที่ยังคลุมเครือ ไม่ระบุ SLA หรือขั้นตอนที่ชัดเจน
-   - **Security & Authorization**: การกำหนด Role, สิทธิ์การเข้าถึงข้อมูล, ข้อมูลส่วนบุคคล (PII)
+   - **Missing Edge Cases**: Boundary conditions, error states, network drops, concurrent requests
+   - **Ambiguous Business Rules**: Unclear policies, unspecified SLAs, or undefined workflows
+   - **Security & Authorization**: Role definitions, access permissions, personal identifiable data (PII)
 2. Generate an actionable checklist in `devflow/inbox/{REQ-ID}/clarifications.md` for the SA to take directly into stakeholder meetings.
 
 ---

package/template/.claude/skills/audit/SKILL.md

@@ -110,14 +110,22 @@ the fresh-session handoff; Phase B must omit `Actual execution` so the legacy
 request and receipt keep both execution fields absent.
 
 1. Require an active spec with every build step checked and status `verified`, a
-   non-default work branch, a reliable merge base, and a clean working tree.
+   non-default work branch, a reliable merge base, and a working tree matching
+   the target except existing `devflow/context/{xxx-slug}/review.md` and
+   `devflow/context/{xxx-slug}/findings.md` evidence.
    Independent mode accepts only a locally recorded remote default branch,
    local `main`, or local `master` as its enforceable base ref. Stop when none
    reliably covers the active work.
-   The current full `HEAD` must be the approved review checkpoint, including the
-   verified spec. Never create that commit inside Audit. If work is dirty, stop
-   and ask the user to approve a review checkpoint through `/implement`, even
-   when normal checkpoint commits are disabled.
+   The current full `HEAD` must be the approved application-code checkpoint.
+   Include the verified spec when tracked; for a new ignored-spec request, prepare
+   the exact local `Spec snapshot` under the reference contract. Never force-add
+   it or change ignore visibility. Never create a commit inside Audit. If any
+   tracked, staged, unstaged, or untracked path other than those two evidence
+   paths differs from the target, stop and ask the user to approve a review
+   checkpoint through `/implement`, even when normal checkpoint commits are
+   disabled. Do not create a checkpoint solely for review/findings changes.
+   This normal Phase A exception never allows snapshot Git differences or
+   overwriting conflicting completion-recovery evidence.
 2. Read installed adapters from `.nexus/nexus-devflow.json` or manifest when valid.
    Detect `.agents/skills` as `antigravity`/`codex`/`copilot` and `.claude/skills`
    as `claude`.
@@ -139,26 +147,30 @@ request and receipt keep both execution fields absent.
    used to calculate it, exact spec SHA-256, current adapter and model,
    requested reviewer adapter and model, requested execution from
    `review.independentExecution`, workflow, and
-   whether the configured Check gate is required. Write the pending template
-   into `devflow/context/{xxx-slug}/review.md`.
+   whether the configured Check gate is required. For a new ignored-spec request,
+   create or reuse the exact snapshot first and record `Spec snapshot` as defined
+   in the reference. Never add that field to an existing pending or completed
+   record. Write the pending template into `devflow/context/{xxx-slug}/review.md`.
 5. Execute the configured path:
    - For `manual`, set dashboard activity to `ready` and give the exact handoff
      command for the selected adapter. Claude Code uses
      `/audit independent current`; Google Antigravity uses
      `/audit independent current`; Codex uses `$audit independent current`;
      Copilot and OpenCode receive the equivalent plain-language instruction.
-     Tell the user to open a fresh session with only the handoff, not the builder
-     chat.
+     Tell the user to open a fresh session in the original checkout with only the
+     handoff, not the builder chat. Include target/base SHAs and, when present,
+     the exact snapshot path and spec hash.
    - For `automatic`, freeze all parent product, test, spec, and config changes.
      Start one generic isolated child without the builder transcript. Instruct
      it to read the project-local Audit skill and
      `reference/independent-review.md` from the current adapter tree, then
-     execute Phase B against the prepared request. All review instructions come
-     from that installed DevFlow project. The reviewer may write only
-     `devflow/context/{xxx-slug}/findings.md` and `devflow/context/{xxx-slug}/review.md`; it must
-     not repair code, change the spec, commit, or perform external actions. Wait
-     for completion, then reread and validate the normal receipt before
-     continuing. Record `fresh subagent` as its reviewer context.
+     execute Phase B using the same local spec/snapshot inputs against the
+     prepared request. All review instructions come from that installed DevFlow
+     project. The reviewer may write only `devflow/context/{xxx-slug}/findings.md`
+     and `devflow/context/{xxx-slug}/review.md`; it must not repair code, change
+     the spec, commit, or perform external actions. Wait for completion, then
+     reread and validate the normal receipt before continuing. Record `fresh subagent`
+     as its reviewer context.
 
 If automatic execution fails or any required property becomes uncertain, keep
 the pending request intact, set activity to `ready`, and stop with the existing
@@ -177,7 +189,9 @@ Use this phase when a current pending request exists in `devflow/context/{xxx-sl
    `HEAD` matches `Target commit`, the recorded base ref still produces the
    recorded merge base, the exact spec hash matches, and no path differs from
    the target except `devflow/context/{xxx-slug}/review.md` and
-   `devflow/context/{xxx-slug}/findings.md`. Stop on any mismatch or stale state.
+   `devflow/context/{xxx-slug}/findings.md`. When `Spec snapshot` is present, verify
+   both raw spec/snapshot hashes and every path, visibility, and Git condition in
+   the reference. Stop on any mismatch or stale state.
 2. Proceed only from the fresh reviewer handoff. Record `fresh session` for a
    manual reviewer or `fresh subagent` for an automatic isolated reviewer. This
    is a declaration, never cryptographic proof. If the reviewer has the builder
@@ -206,6 +220,9 @@ Use this phase when a current pending request exists in `devflow/context/{xxx-sl
 After changes are requested, the builder repairs through `/implement`, obtains
 approval for a new checkpoint, and prepares a new request. The next reviewer
 pass reviews the complete new delta, not only the old findings.
+A local-spec-only revision may reuse the same approved product HEAD after normal
+spec and verification gates, with a new snapshot/request and full fresh review;
+it never requires an empty commit.
 
 ## Step 1 - gather context
 

package/template/.claude/skills/audit/reference/independent-review.md

@@ -68,6 +68,56 @@ work branch, and `Base commit` cannot equal `Target commit`. If none of those
 base refs reliably covers the active work, stop instead of creating a receipt
 whose review range cannot be re-derived.
 
+## Local spec snapshot
+
+For a new request whose verified spec is intentionally ignored, keep application
+code in the approved checkpoint and freeze the spec outside Git. Add exactly one
+field after `Spec hash`, using a plain path with no backticks:
+
+```markdown
+**Spec snapshot:** devflow/.state/review-specs/<Target commit>-<Spec hash>.md
+```
+
+Substitute the request's full lowercase target SHA and lowercase spec hash. This
+is the only permitted snapshot path; duplicate fields or another path are
+malformed. Tracked-spec requests do not need this field. Existing requests and
+receipts without it retain their previous hash, freshness, and execution rules.
+Never retroactively add `Spec snapshot` to a pending or completed record.
+
+Phase A prepares the copy before publishing a new pending request:
+
+1. Read the verified active spec as raw bytes and calculate its SHA-256 without
+   decoding, trimming, or normalizing line endings. Use that digest as `Spec hash`.
+2. Use `lstat` on the selected project root and every directory below it leading
+   to the spec and snapshot. Require ordinary directories, a regular spec file,
+   and a regular file for any existing snapshot. Reject symbolic links, including
+   dangling links. Ancestor aliases above the selected root are not inspected.
+   Create missing snapshot directories only beneath verified ordinary parents;
+   a missing snapshot leaf is allowed only for exclusive creation below them.
+3. Require both paths to be ignored and untracked, absent from the index and
+   `Target commit`. Check ignore status separately for each path, require no
+   entries from `git ls-files --stage -- <spec-path> <snapshot-path>` or
+   `git ls-tree -r --name-only <target> -- <spec-path> <snapshot-path>`, and
+   distinguish expected absence from Git failure. Never force-add files or
+   change ignore visibility to make these checks pass.
+4. Create the snapshot exclusively, for example with Node's `fs.open` using
+   `wx`, then write the raw byte buffer and close the handle. If it already
+   exists, reuse only an ordinary file whose bytes exactly match the spec.
+   Conflicting bytes, unsafe paths, or a failed write stop preparation; never
+   overwrite or repair the existing snapshot in place.
+5. Read both files back and require identical raw bytes and the recorded hash.
+   Recheck their path and Git conditions before writing the request. Keep the
+   snapshot unchanged through review and completion; do not automatically delete
+   or regenerate it to make an existing receipt pass.
+
+The target/base fields bind application code; `Spec hash` binds both local files.
+The snapshot is an input, never another allowed dirty Git path. Manual handoff
+names the original checkout, target/base SHAs, snapshot path, and hash. An
+automatic child must be able to read those same ignored inputs and installed
+project-local skills. If that access cannot be confirmed, retain the request and
+use the manual fresh-session handoff in the original checkout. Do not copy local
+inputs externally or substitute a clone/worktree that lacks them.
+
 ## Completed receipt
 
 Keep the request fields unchanged and replace `pending` with `passed` or
@@ -131,6 +181,9 @@ A receipt is current only when all of these hold:
   equals `Base commit`, and it remains a locally recorded remote default branch,
   local `main`, or local `master`.
 - The exact task spec bytes still match `Spec hash`.
+- When `Spec snapshot` is present, both raw files match that hash and every
+  snapshot path, visibility, and Git condition above still holds. Missing or
+  changed snapshot inputs make the record stale; Git failure never passes.
 - No tracked, staged, unstaged, or untracked path differs from the target except
   `devflow/context/{xxx-slug}/review.md` and `devflow/context/{xxx-slug}/findings.md`.
 - The completed reviewer adapter matches `Requested reviewer`.
@@ -149,8 +202,11 @@ A receipt is current only when all of these hold:
   record the actual value.
 
 Any other code, test, configuration, spec, or acceptance-criteria change makes
-the receipt stale. A stale receipt never proves the new state. Prepare a new
-request against a new approved checkpoint and review the whole delta again.
+the receipt stale. A stale receipt never proves the new state. Product changes
+need a new approved checkpoint. A local-spec-only revision may reuse the same
+approved product HEAD after normal spec and verification gates, with a new
+snapshot, a new request, and a full fresh review. Never create an empty commit
+just to capture ignored spec changes or edit a passed receipt into a new review.
 
 The adapter, model, and context fields are declared metadata. DevFlow proves
 the target and staleness, but it cannot cryptographically prove that a separate

package/template/.claude/skills/brainstorm/SKILL.md

@@ -37,7 +37,7 @@ Provide at least 2-3 materially distinct approaches:
 ### 3. Trade-off Comparison Matrix
 Construct a structured evaluation table:
 
-| Option | Pros (ข้อดี) | Cons (ข้อเสีย) | Effort & Complexity | Verdict / Status |
+| Option | Pros | Cons | Effort & Complexity | Verdict / Status |
 | :--- | :--- | :--- | :--- | :--- |
 | **Option A** | ... | ... | Low / Med / High | ... |
 | **Option B** | ... | ... | Low / Med / High | **Recommended** |

package/template/.claude/skills/complete/SKILL.md

@@ -33,6 +33,15 @@ passes.
 Read `devflow/config.json`. A missing file means the built-in defaults apply.
 If the file exists but is invalid, stop and point the user to `/doctor`.
 
+Before requiring a real active spec, check for pending completion using
+`reference/completion-recovery.md`. A matching archive may mean archival was
+interrupted, the work commit awaits merge, or the merge already finished. Follow
+that phase instead of restarting logging. Missing or ambiguous evidence stops
+with concrete recovery steps; an archive or clean context never authorizes selecting new work.
+Recovery uses archive and Git proof, never dashboard activity as authority.
+
+For a normal completion with no recovery in progress, continue below.
+
 Confirm the target work is actually finished: `devflow/context/{xxx-slug}/spec.md`
 holds a real spec, its steps are built on a branch, and `Verify`, or the fallback
 build and tests, passes. If any of the
@@ -45,6 +54,7 @@ Read `devflow/context/{xxx-slug}/review.md` (or `devflow/context/review.md`) whe
 changes-requested, malformed, or stale record is always a blocker because the
 user already initiated that gate, even when its configured policy is `manual`.
 
+
 ## Configured regular quality gates
 
 Use `qualityGates.regular` for this work item:
@@ -103,6 +113,15 @@ evidence is missing.
 
 ## Step 1 - log the work
 
+Follow `reference/completion-recovery.md` to capture the source tree and compact
+archive annotation before any logging edits. Preserve the exact verified spec
+prefix, its UTF-8 byte length and SHA-256, branch, original HEAD, and local base.
+Record the reference's narrow `absentOptional` proof before creating any optional
+findings/review stub on an older installation; tree absence alone is insufficient.
+Prepare the entire archive, including the sections below and any generated try
+guide, before placing it at its destination in `devflow/history/features/`, `fixes/`, or `rollbacks/`. An existing matching archive
+enters recovery; never overwrite it or append duplicate sections.
+
 Check whether the spec is a feature, fix, or rollback. A fix is marked
 `Type: Fix` and has no build-plan number. A rollback is marked `Type: Rollback`
 and records the exact target feature, archive, commit, and parent.
@@ -122,11 +141,14 @@ delete the `prototypes/` folder now.
 
 ## Step 2 - make the work commit on feature branch
 
-Stage everything on the branch (any uncommitted step work plus the Step 1 logging
+Show the complete product and logging diff with the proposed commit message,
+then obtain explicit commit approval. Only then stage the reviewed branch work
+(any uncommitted step work plus the Step 1 logging
 changes) and make one conventional work commit on the active branch (for example `feat: <feature>`,
 `fix: <name>`, or `revert: roll back <feature>`). `Verify`, or the fallback build
 and tests, must pass first.
 
+
 ## Step 3 - Mandatory Delivery Gate (Ask User First)
 
 > [!IMPORTANT]