@jakkrichm/create-nexus-devflow 2.16.4 → 2.17.1

package/template/.agents/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/.agents/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`.
@@ -133,32 +141,37 @@ request and receipt keep both execution fields absent.
      isolated child through the current runtime. Do not discover, select, or
      depend on a globally installed role, skill, prompt, or another workflow
      such as TraversyFlow. If the runtime cannot start that generic child from
-     project-local instructions, or capability, isolation, identity, model, or
-     completion cannot be confirmed, use the manual path.
+     project-local instructions, or capability, isolation, identity, model,
+     completion, or access to the same ignored spec/snapshot inputs cannot be
+     confirmed, use the manual path in the original checkout.
 4. Record the full target SHA, full merge-base SHA, the exact local base ref
    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 +190,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 +221,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/.agents/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/.agents/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/.agents/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]

package/template/.agents/skills/complete/reference/completion-recovery.md

@@ -0,0 +1,248 @@
+# Completion recovery
+
+Use this contract before Complete requires a live spec, and before Status or
+Continuous selects new work. Archive and Git evidence determine the phase.
+`run.json`, modification times, archive titles, and commit subjects prove none of
+these transitions. Recovery grants no commit, merge, push, or cleanup approval.
+
+## Prepare one recoverable archive
+
+After Complete's final gates pass, but before any logging edits, record the full
+work branch ref, `HEAD`, local default branch ref and its current commit. Require
+that default commit to be an ancestor of the work branch. Resolve refs locally;
+do not fetch. Capture the verified working tree in a temporary Git index:
+
+```bash
+node --input-type=module -e '
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), "devflow-completion-"));
+const env = { ...process.env, GIT_INDEX_FILE: path.join(dir, "index") };
+try {
+  execFileSync("git", ["read-tree", "HEAD"], { env });
+  execFileSync("git", ["add", "-A", "--", "."], { env });
+  process.stdout.write(execFileSync("git", ["write-tree"], { env }));
+} finally {
+  fs.rmSync(dir, { recursive: true, force: true });
+}'
+```
+
+Run from the project root only after excluding unrelated work and Git conflicts.
+This writes local Git objects, not a commit or ref, and leaves the normal index
+untouched. Never force-add ignored files. Dirty submodules or required ignored
+inputs without separately recoverable exact bytes cannot support this proof.
+The source tree is evidence, not approval or a substitute for any quality gate.
+
+Before logging, record `absentOptional` as an array containing only
+`devflow/context/{xxx-slug}/findings.md` and/or `devflow/context/{xxx-slug}/review.md` when each
+exact path returns `ENOENT` from `lstat`, its parents are ordinary directories,
+and neither HEAD nor sourceTree contains it. Otherwise omit that path. This
+records original filesystem absence, never permission to discard evidence.
+Ignored existing files and symlinks are not absent. Reject other paths, duplicates,
+or contradictions; a missing field in an older annotation proves no absence.
+
+Start the archive with the original verified spec bytes, unchanged. Measure
+UTF-8 **bytes**, not characters or lines. Append two LF bytes and this single-line
+JSON comment before any Findings, Independent review, or Manual try guide section:
+
+```text
+<!-- devflow:completion {"schemaVersion":1,"specBytes":123,"specSha256":"<64 hex>","branch":"refs/heads/feature/name","head":"<full SHA>","baseRef":"refs/heads/main","baseCommit":"<full SHA>","sourceTree":"<full tree SHA>","absentOptional":[]} -->
+```
+
+Use `Buffer.length` and SHA-256 over the exact file bytes. To recover, locate the
+unique annotation boundary and remove only the two inserted line breaks before
+it (LF or CRLF). Test that prefix as raw bytes and uniform LF/CRLF candidates
+against both `specBytes` and `specSha256`; deduplicate identical candidates and
+accept only one exact match. This reconstructs hash-proven original bytes across
+ordinary Git EOL conversion. Mixed endings or custom filters without an exact
+match stop recovery. Never trim content, split on a Markdown heading, or accept a
+normalized digest instead of the original. Reject malformed/duplicate annotations.
+
+Build the complete archive in a temporary file first, including all resolved
+findings, the exact passing receipt when present, and any generated try guide.
+Validate it against its inputs, then place it at the intended absent archive path
+in `devflow/history/features/`, `fixes/`, or `rollbacks/`.
+Never overwrite an existing archive: a matching one enters recovery; a conflicting
+one stops for an exact path decision. Finish plan/overview bookkeeping, update
+`devflow/history/HISTORY.md`, then clean up the run workspace `devflow/context/{xxx-slug}/`.
+Do not append sections incrementally to an existing archive during recovery.
+
+## Screen candidates read-only
+
+Before matching a reused feature branch, apply the historical-build exclusion
+below. Do not treat a proved prior reversed build as pending completion of its
+replacement. If that exclusion cannot be proved, retain the candidate and stop
+for full proof rather than guessing from a different spec or archive name.
+
+Inspect current branch, `git status --porcelain=v1`, live spec/review and plan
+consistency, and relevant annotated archives. Check recorded local work refs with
+`git show-ref --verify --quiet <branch>`. A matching work branch/archive, a retained
+matching work ref after merge, or uncommitted completion changes/live evidence tied
+to that item is a recovery candidate. An explicit request to resume completion
+also requires full proof. Status reports candidates and routes them to Complete;
+it does not create a temporary index or claim the phase has passed full proof.
+
+For ordinary Status or a new Continuous invocation, a clean local default branch
+with consistent live state, no matching local work ref, and no pending completion
+evidence is settled history. An archive at its tip alone does not trigger recovery.
+Do not require historical `head`/`sourceTree` objects for that orientation; clean
+clones and Git pruning legitimately lose them. This is not a new claim about past
+verification. A reset stub alone proves nothing: check the refs, cleanliness, and
+live state too. Missing objects still block actual recovery and explicit resume.
+
+## Prove an actual recovery candidate
+
+For feature archives on a reused branch, exclude a prior build only when all of
+these read-only Git checks pass:
+
+- `../../feature/reference/build-history.md` proves its unique unchanged archive
+  addition on the local default, and the introducing commit's sole parent equals
+  that archive annotation's `baseCommit` on the same `baseRef`.
+- An exact completed, unchanged, reachable rollback record names that archive and
+  introducing commit; its commit is after the feature addition.
+- The current work branch descends from a post-rollback local default: that
+  rollback commit is an ancestor of the merge base of the current work branch
+  and local default. Its old archive remains byte/mode-identical in both trees
+  and the working tree, with no pending archive edits or retained review explicitly
+  targeting that old build.
+
+Different spec bytes, title, attempt, filename, or ancestry alone never exclude
+an archive. Missing, changed, or contradictory proof stops; this exception does
+not recover old missing inputs or waive current gates. It permits legacy branch
+reuse only after the old lifecycle is demonstrably finished and reversed.
+
+Require one annotated archive matching the recorded work branch, or the exact
+archive/commit proof in the merged phase below. A real live spec must match its
+recovered bytes; a cleaned-up workspace is also expected after merge. A different spec conflicts.
+For features, use the recovered spec's frozen `**Build attempt:**` and that exact
+archive path; never allocate a new attempt on resume. For a legacy feature spec
+without the field, the path plus existing annotation fixes the destination only
+after the prior-build proof in `../../feature/reference/build-history.md` at its
+recorded `baseCommit` uniquely establishes its attempt. Exclude the current archive from those prior
+builds. Do not edit the recovered bytes to insert metadata.
+
+Require all recorded commits and `sourceTree` to exist (`git cat-file -e`).
+Unreferenced source trees can be pruned by Git: missing objects stop recovery;
+request the original objects or an identified backup, never recreate a guessed
+baseline. An old archive without this annotation may be read as history, but
+cannot automatically recover a missing live spec through this contract.
+
+Use the temporary-index command above to inspect the present work tree without
+altering the real index. Compare trees with `git diff --raw -z <source> <current>`
+and inspect source blobs with `git show <sourceTree>:<path>`. Git trees use clean-
+filtered bytes; compare evidence through `git hash-object --path=<path> --stdin`
+when ordinary EOL conversion applies, while recovering the exact spec only by
+its archive digest above. Unsupported custom filters stop recovery. Inspect staged
+changes too; conflicting staged/working versions must be reconciled explicitly.
+Do not infer identity from ancestry alone, a matching filename, or a latest date.
+
+## Validate only the expected completion changes
+
+Reconstruct the original spec and evidence from the source tree and archive.
+Every changed path, file mode, addition, and deletion must be accounted for.
+Only these exact transformations can follow the captured source tree:
+
+- Add this one archive, with the exact spec prefix and annotation, resolved
+  findings copied with only the documented ID prefix, the original passing
+  receipt bytes, and a try guide for this spec when required or already generated.
+- Apply this work item's exact build-plan checkbox/parent changes, or its exact
+  rollback note. Update `devflow/history/HISTORY.md` with the release digest.
+  Change only the overview's existing source-hash value, using the documented hash contract.
+  A fix has no build-plan change.
+- Remove only resolved ledger entries present in that archive. Preserve every
+  `open`, `fixed`, and `unverified` entry byte-for-byte, including its ID.
+- Clean up the completed task run directory `devflow/context/{xxx-slug}/`.
+- Delete only the exact consumed prototype files already authorized for this
+  work item and identified by its design reference. No general cleanup is allowed.
+
+No other history, context, configuration, product, test, or ignore-rule changes
+are completion bookkeeping. Read the full diffs, not just a filename allowlist.
+Partial plan bookkeeping is recoverable only when each changed byte is one of
+these transformations and all unfinished operations can be identified exactly.
+Conflicting or partial archive/evidence content stops before any live reset.
+
+For independent review, validate the archived receipt against its original
+`Target commit`, original base/merge-base, exact recovered spec digest, reviewer
+identity, execution/context pairing, required Check result, and receipt sections.
+The annotation's `head` must equal that target, and its source tree may differ
+from the target only in the original review/findings evidence permitted by Audit.
+Never relabel the receipt as current at the later work commit or merge commit.
+When the original receipt has `Spec snapshot`, preserve that field unchanged.
+After live reset, the hash-proven original archive prefix may establish the same
+spec identity: require its exact digest to equal the receipt's `Spec hash` and the
+annotation's `specSha256`, and require the snapshot field's canonical path to
+contain that original target and hash. This is archived-receipt validation, not
+a current live receipt. Do not create a new snapshot or relabel the target.
+Conflicting retained snapshot bytes or unsafe paths still stop recovery; an
+absent local snapshot may use this exact archive proof after reset. This does
+not replace source-tree/product proof or recover other ignored evidence.
+The narrow completion changes above preserve the reviewed product; any other
+change requires restored exact active inputs and renewed gates/checkpoint/review.
+Never overwrite conflicting live evidence to obtain that restoration.
+
+Ignored local-only files are absent from this tree proof. Validate them using
+separately provable exact original bytes plus the archive and retained inputs,
+or stop and name the missing evidence. A local archive can match a still-existing
+work branch; its presence alone cannot bind an already-deleted branch to a squash
+commit. Do not force-add ignored workflow files to make recovery pass.
+
+## Interrupted archival, before the work commit
+
+Require the recorded work branch at the recorded `head`, the local default still
+at `baseCommit`, a complete matching archive, and only the validated partial or
+finished bookkeeping changes above. Reconcile archived and retained findings and
+review before changing anything. Do not duplicate sections or erase unresolved
+entries. If the archive is absent and live inputs are intact, use normal Complete;
+if both the archive and needed live input are missing, stop for recovery evidence.
+
+Read the recovered spec from a temporary file, preserving its exact bytes; do
+not overwrite the live stub merely to orient a fresh session. Repeat current-
+session Verify and required gates against that spec and the current product.
+Reuse a passing archived review only through the original-target checks above.
+If a gate needs active files restored, restore only proven matching originals
+with no conflicting live data, run the gate, and re-enter normal Complete. If
+verification or review changes evidence, stop and reconcile a new reviewed archive
+candidate explicitly; never silently append to the existing archive.
+
+Finish only the missing bookkeeping, with live workspace cleanup last. Show the concrete
+remaining diff and proposed conventional work commit, obtain normal commit
+approval, and continue at Complete Step 2. This archive does not authorize Git.
+
+## Work committed, awaiting merge
+
+Require a clean recorded work branch at one unambiguous final work commit whose
+sole parent is recorded `head`, with the default still at `baseCommit`. Compare the complete work
+commit tree to `sourceTree` and require exactly the finished transformations above.
+The tracked archive and final bookkeeping must be in that commit, not added later.
+For ignored evidence require the separate proof described above. Extra commits or
+post-commit drift stop for review, not another completion commit.
+
+Rerun current-session Verify and validate all required gates using the recovered
+spec and original receipt. Resume at Complete Step 3's merge approval. Never make
+a second work commit, reset evidence again, or treat earlier approval as covering
+new changes. Preserve the exact work commit SHA for merge verification.
+
+## Merge already completed
+
+Require a clean local default branch tip whose sole parent is the recorded
+`baseCommit`, and the complete finished tree and archive. If the work branch still
+exists, require its exact final work commit and tree equality with that default
+tip (`git diff --exit-code <workCommit>^{tree} <defaultTip>^{tree}`), including the
+archive blob. A squash merge normally does not contain the work commit as an
+ancestor. Tree equality alone without the matching base, archive, and completed
+bookkeeping is insufficient.
+
+If the work branch was deleted, require the tracked archive at the default tip,
+its exact source-tree/spec/branch annotation, and exactly the finished changes
+from sourceTree to that tip. An ignored archive without a provable commit binding
+must stop for user identification and supporting evidence. If the default has
+advanced or several commits/archives fit, stop and name the ambiguity instead of
+weakening this proof or searching by title.
+
+Do only pending cleanup already authorized for this work item; ask if cleanup
+approval is missing. Never repeat archival, the work commit, or the squash merge,
+and never create a cleanup commit on the default branch. If nothing remains,
+report the verified local merge once and leave Git unchanged. Push still needs
+its separate approval. A repeated resume follows this same no-op path.