@jakkrichm/create-nexus-devflow 2.17.5 → 2.17.7

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

@@ -102,6 +102,8 @@ the data model, stack, and conventions. Decide how big the feature is:
   those sub-items back under the parent in `build-plan.md` as an indented
   checklist (`4a`, `4b`, `4c` ...). Spec only the **first** sub-feature now; the
   rest get picked up on later `/feature` runs.
+  *Use the **4 Slicing Archetypes** ([`devflow/reference/slicing-archetypes.md`](file:///d:/Projects/devtools/nexus-devflow/devflow/reference/slicing-archetypes.md)) to guide the split: 🛹 Skateboard (core logic first), 🎭 Facade (UI/DX mock first), 🎯 Tracer Bullet (end-to-end slice), or 🧭 Journey (workflow steps).*
+
 
 Two levels of breakdown - don't confuse them:
 
@@ -198,7 +200,7 @@ Before the user reads it, turn on the spec yourself and try to break it. The
 cheapest place to catch a scope problem or an oversized step is here, before any
 code exists. Run the draft against these questions:
 
-- **Coverage.** What does this feature need that no step delivers? Push on the
+- **Coverage & Input Mapping.** What does this feature need that no step delivers? Run a mechanical **Input Coverage Test**: does every value this build produces, displays, or computes have a named source (input, DB column, formula, or settled decision) in the spec? Push on the
   unhappy paths the happy-path spec skipped: empty / missing / malformed input,
   the error / loading / empty states, the first-run case, failure of anything
   external it calls.
@@ -218,6 +220,7 @@ code exists. Run the draft against these questions:
   anything pushed to "out of scope" that this feature actually can't ship without?
 - **Done-whens.** Is each one observable and checkable by `/check`, or is it a
   vague "it works"? Make it concrete.
+- **Proportionality.** Does any proposed abstraction, dependency, service, config surface, or security mechanism lack a current requirement, or duplicate existing code/platform features? If so, remove it.
 - **Testing.** Does the predicted coverage match the gate - in-scope logic gets a
   test when a `test` command is declared in `AGENTS.md`, UI/integration rides on
   screenshot + build?

package/template/.agents/skills/feature/reference/feature-spec-template.md

@@ -14,18 +14,18 @@
 ## 1. Specification & Scope
 
 ### 1.1 Problem Statement
-{คำอธิบายปัญหาและที่มาของความจำเป็นในการพัฒนาฟีเจอร์นี้}
+{Description of the problem, background, and rationale for developing this feature}
 
 ### 1.2 In-Scope
-1. {ขอบเขตการทำงานข้อที่ 1}
-2. {ขอบเขตการทำงานข้อที่ 2}
+1. {In-scope item 1}
+2. {In-scope item 2}
 
 ### 1.3 Out-of-Scope
-- {สิ่งที่อยู่นอกเหนือขอบเขตหรือไม่ทำในรอบนี้}
+- {Items deliberately excluded or deferred to future features}
 
-### 1.4 Acceptance Criteria (เกณฑ์การยอมรับ)
-- [ ] **AC-1**: {เกณฑ์การตรวจรับข้อที่ 1}
-- [ ] **AC-2**: {เกณฑ์การตรวจรับข้อที่ 2}
+### 1.4 Acceptance Criteria
+- [ ] **AC-1**: {Acceptance criterion 1}
+- [ ] **AC-2**: {Acceptance criterion 2}
 
 ---
 
@@ -40,18 +40,18 @@
 - **Review Strategy**: One feature-level review packet at completion
 
 ### 2.3 Test Decision: Required (TDD) | Optional
-- **Rationale**: {เหตุผลความจำเป็นในการเขียน Unit Tests / TDD}
+- **Rationale**: {Reason for requiring Unit Tests / TDD}
 
 ---
 
 ## 3. Implementation Checklist (Strict TDD)
 
-- [ ] **Task 1: {หัวข้องานที่ 1}**
-  - [ ] 1.1 `[TDD-Red]`: {เขียน Test เคสล้มเหลว}
-  - [ ] 1.2 `[TDD-Green]`: {เขียนโค้ดขั้นต่ำเพื่อให้ Test ผ่าน}
-  - [ ] 1.3 `[TDD-Refactor]`: {Refactor และตรวจให้ 100% Tests Green}
+- [ ] **Task 1: {Task 1 title}**
+  - [ ] 1.1 `[TDD-Red]`: {Write failing unit or behavioral test}
+  - [ ] 1.2 `[TDD-Green]`: {Write minimal implementation to pass test}
+  - [ ] 1.3 `[TDD-Refactor]`: {Refactor and ensure 100% tests green}
 
-- [ ] **Task 2: {หัวข้องานที่ 2}**
+- [ ] **Task 2: {Task 2 title}**
   - [ ] 2.1 `[TDD-Red]`: ...
   - [ ] 2.2 `[TDD-Green]`: ...
   - [ ] 2.3 `[TDD-Refactor]`: ...
@@ -65,11 +65,11 @@
 - **Automated Test Matrix**: TBD
 - **Static Contract Verification**: TBD
 - **Package Smoke Test**: TBD
-- **Findings Ledger**: ตรวจสอบ `findings.md` สะอาด 100%
+- **Findings Ledger**: Verify `findings.md` is 100% clean
 
 ### 🎯 Axis 2: Spec Fidelity & Behavioral Acceptance Gate
-- [ ] **AC-1**: {หลักฐานการผ่านเกณฑ์ข้อที่ 1}
-- [ ] **AC-2**: {หลักฐานการผ่านเกณฑ์ข้อที่ 2}
+- [ ] **AC-1**: {Empirical proof for AC-1}
+- [ ] **AC-2**: {Empirical proof for AC-2}
 
 ---
 

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

@@ -70,10 +70,14 @@ Allocate the next sequential ID (`ADR-001`, `ADR-002`, ...) and create `devflow/
 ```markdown
 # ADR-xxx: {Title}
 
-- **Status**: Accepted
+- **Status**: Accepted | Assumed (Fast-tracked Assumption)
 - **Date**: {YYYY-MM-DD}
 - **Context**: {Why was this decision needed? What problem does it solve?}
 - **Decision**: {What did we decide to do?}
+- **Assumption Metadata** *(Required when Status is Assumed)*:
+  - **Assumption**: {What was assumed to unblock progress}
+  - **Risk Level & Blast Radius**: {Risk if assumption fails}
+  - **Ratification Plan**: {Trigger, date, or test to ratify as Accepted or Rejected}
 - **Alternatives Considered**:
   - *Option 1*: {Pros / Cons}
   - *Option 2*: {Pros / Cons}
@@ -82,6 +86,7 @@ Allocate the next sequential ID (`ADR-001`, `ADR-002`, ...) and create `devflow/
   - *Trade-offs / Risks*: {Costs, constraints, or follow-ups}
 ```
 
+
 ---
 
 ## 4. Closing & Handoff

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

@@ -26,7 +26,7 @@ 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 entry in Thai (`th` per user communication rules):
+Evaluate the user's raw idea and generate an enriched entry:
 - **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
@@ -37,17 +37,17 @@ Insert the new idea block directly under `## 📌 Pending Ideas` in `devflow/ide
 
 ```markdown
 ### [IDEA-001] {Brief idea title}
-- **บันทึกเมื่อ**: {YYYY-MM-DD}
-- **ไอเดียตั้งต้น**: {User's raw idea text}
+- **Recorded Date**: {YYYY-MM-DD}
+- **Original Idea**: {User's raw idea text}
 - **AI Feasibility & Tech**: {Feasibility and tooling analysis}
 - **Value & Potential**: {Value and impact analysis}
-- **Quick Seed (กันลืม)**:
+- **Quick Seed**:
   1. {Key point 1}
   2. {Key point 2}
-- **สถานะ**: `Pending` (Ready for pickup via `/feature IDEA-001` or `/discovery IDEA-001`)
+- **Status**: `Pending` (Ready for pickup via `/feature IDEA-001` or `/discovery IDEA-001`)
 ```
 
-*(If placeholder `*(ยังไม่มีไอเดียค้างอยู่...)*` exists, remove it upon recording the first idea)*
+*(If placeholder `*(No pending ideas...)*` exists, remove it upon recording the first idea)*
 
 ### 4. Output Summary
 Report to the user:

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

@@ -93,7 +93,12 @@ feature was started earlier and interrupted (often a cleared context). The spec
 its ticked steps are files, so pick up where it left off: read which steps are done,
 check the git branch and `git status`/log to see what is committed and what is still
 in the working tree, then continue from the **first unchecked step** instead of
-starting over.
+### Step 0 - Mechanical Input Coverage Pre-flight Gate
+
+Before touching code or executing build tasks, perform a positive **Input Coverage Test** against the active Living Spec:
+- Enumerate every value, state, or data field this implementation must produce, compute, or display (from the acceptance criteria and spec design).
+- For each required value, verify that the spec explicitly names where it comes from (e.g. database schema/column, API request parameter, calculated derivation from a named source, or explicit prior architectural decision).
+- **Anti-Hallucination Guard**: Any required value with no named source is an **Owed Decision**. Do NOT rationalize it as "just wiring" and do NOT silently invent an ad-hoc provider, schema field, or business rule. Stop and route to `/grill` or request user clarification before proceeding.
 
 ## Step 1 - branch
 
@@ -111,10 +116,13 @@ When implementing a rollback task, follow the exact safety procedure in `referen
 Work in small reviewable diffs, keeping progress in the selected spec.
 
 1. For logic or behavior changes with the test gate on, use Red-Green-Refactor: write a focused failing test, confirm the assertion fails for the missing behavior, implement the smallest change, then refactor with affected tests green. Preserve the user's existing work. Consult [TDD anti-patterns](tdd-anti-patterns.md) when test design needs it.
+   - **Proportional Engineering**: Add an abstraction, dependency, service, configuration surface, compatibility layer, or security mechanism only when the approved spec or an established repository requirement needs it now. Prefer existing code, standard library, and native platform features.
 2. Match the step's done-when and run focused checks. Documentation or formatting-only edits use structural checks and review; they do not require artificial unit tests. Capture relevant runtime or browser proof for behavioral criteria, following the selected Check policy.
 3. Fix failures caused by the change and rerun affected checks without requesting authorization again. Broaden verification when dependencies, failures, or risk justify it.
 4. Record the diff summary and evidence. Mark a step complete once its done-when passes and any configured per-step review has been approved. A repaired finding becomes `fixed` with resolution evidence; only a subsequent audit can close it. Apply the review cadence above before proceeding.
 
+Run a proportionality check before final verification: every new abstraction, dependency, service, configuration surface, compatibility layer, and security mechanism must trace to the approved spec or an established repository requirement. Remove speculative machinery this work added without weakening real trust-boundary validation, data-loss prevention, accessibility, or configured verification.
+
 At the final handoff, run the exact documented Verify command and all required gates. If there is no Verify command, use the project's declared build and test commands. Reuse a passing result for unchanged inputs within this pass; rerun affected gates after subsequent edits. Do not add tests or tools just to inflate the verification matrix.
 
 ### Ticket execution

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

@@ -87,6 +87,32 @@ When generating or logging test runs during `/implement` or `/check`:
 
 ---
 
+## 7. 5-Tier Test File Classification Strategy
+
+Do not write identical test patterns for all file types. Classify files into 5 distinct tiers:
+
+| Tier | Category / File Paths | Recommended Test Strategy | What NOT to do |
+| :--- | :--- | :--- | :--- |
+| 🧠 **Tier 1** | **Pure Logic & Algorithms**<br>`src/utils/`, `src/services/`, `lib/` | Fast in-memory Unit Tests with 100% boundary & edge cases coverage. Use TDD (Red-Green-Refactor). | Do not over-mock pure mathematical or transformation functions. |
+| 🎨 **Tier 2** | **UI Components**<br>`src/components/`, `src/pages/` | Component rendering, event dispatching, visual verification via Playwright / BrowserOS Neo. | **Prohibited**: Do not write trivial unit tests that merely assert static HTML tags exist. |
+| 🔌 **Tier 3** | **API & Data Integration**<br>`src/api/`, route handlers, DB models | Contract tests, schema validation (Zod), HTTP status codes, error payload shapes. | Do not test external third-party network APIs without isolated fakes. |
+| ⚙️ **Tier 4** | **Config & Build Tooling**<br>`*.json`, `*.yaml`, `scripts/` | Static contract validation (`npm run check:static`), budget linters (`npm run check:budgets`), smoke tests. | Do not skip static validation on build tool modifications. |
+| 📝 **Tier 5** | **Documentation & Prose**<br>`*.md`, `devflow/docs/` | Structural checks, markdown contract scans, and link integrity verification. | Do not write artificial unit test suites for documentation files. |
+
+---
+
+## 8. Acceptance Criteria (`AC-N`) Traceability Protocol
+
+To guarantee 100% spec fidelity, every automated test suite must trace back to the active Living Spec:
+- **Test Title Tagging**: Prefix test titles or describe blocks with the target Acceptance Criterion:
+  ```typescript
+  it('AC-1: enforces 32KB byte budget on SKILL.md files', async () => { ... });
+  it('AC-2: returns exit code 1 when budget violation occurs', async () => { ... });
+  ```
+- **Traceability Verification**: During `/check`, cross-reference every `- [ ] AC-N` against the passing test assertion name to ensure zero untracked requirements.
+
+---
+
 ## Relationship To DevFlow 2.6.x
 
 - **Classification**: Companion command & Engineering standard

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

@@ -300,8 +300,10 @@ expectations. Apply only the selected lens or lenses:
   - *Question Intent & Simpler Alternatives*: State what the change actually attempts in one sentence. Ask: is there a simpler, smaller, or more elegant way to achieve the same goal (reusing existing code, config vs code, solving at a different layer)?
   - *Full Call-Path Tracing*: Follow the call graph through real code paths (entry point → call sites → branches taken → state mutated → exit/side effect), including unchanged code on either side of the diff where bugs hide.
   - *Verify Claims & Edge Cases*: Does the traced path actually produce the claimed behavior? What inputs/states would break it (concurrency, retries, null/unicode/huge payloads, ordering)? What does it silently change?
+  - *Assumed Decision Debt Check*: Scan `devflow/decisions/` for any ADR with `Status: Assumed`. Flag unratified assumptions as `Q-xxx` (P2) to ensure ratification before production handoff.
   - *No Rubber-Stamping*: "LGTM" is prohibited. State what was traced, what was verified, and what evidence supports the verdict.
 
+
 Do not nitpick harmless style differences unless they signal drift from the local
 patterns. Prefer a short list of real findings over a broad list of guesses.
 
@@ -319,7 +321,8 @@ Maintain the durable record in `devflow/context/{xxx-slug}/findings.md` (or `dev
 3. Set severity honestly:
    - `P0`: critical blocking bug, data corruption, severe vulnerability, complete outage.
    - `P1`: serious defect, missing critical test, unhandled core error.
-   - `P2`: moderate debt, performance degradation, missing edge cases.
+   - `P2`: moderate debt, performance degradation, missing edge cases, or pure proportionality finding.
    - `P3`: minor improvement, code cleanup, cosmetic tweak.
+   *(For a proportionality finding, state in Suggested fix what can be deleted. An otherwise pure proportionality finding is P2 or P3. Raise to P0/P1 only when the unnecessary machinery causes a concrete reachable defect or violates an established security or data-integrity boundary.)*
 4. Set status: `open`, `fixed`, `closed`, `accepted`, or `invalid`.
 5. Display concise findings summary and next actions.

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

@@ -29,10 +29,11 @@ Use this when:
 - Identify technical, business, or timeline constraints.
 
 ### 2. Option Formulation (Divergent Phase)
-Provide at least 2-3 materially distinct approaches:
-- **Option A (Standard / Conservative)**: Low risk, proven pattern, minimal changes.
-- **Option B (Modern / Optimized)**: Best-practice architecture, balanced trade-off, scalable.
-- **Option C (Alternative / Unconventional)**: High innovation, simplified scope, or creative alternative.
+Provide at least 2-3 materially distinct approaches. Where applicable, map each option to its **Slicing Archetype** ([`devflow/reference/slicing-archetypes.md`](file:///d:/Projects/devtools/nexus-devflow/devflow/reference/slicing-archetypes.md)):
+- **Option A (Standard / Conservative)**: Low risk, proven pattern, minimal changes (e.g. *Skateboard* or *Tracer Bullet*).
+- **Option B (Modern / Optimized)**: Best-practice architecture, balanced trade-off, scalable (e.g. *Journey*).
+- **Option C (Alternative / Fast-Feedback)**: High innovation, simplified scope, or UX-first (e.g. *Facade*).
+
 
 ### 3. Trade-off Comparison Matrix
 Construct a structured evaluation table:

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

@@ -1,126 +1,36 @@
 ---
 name: check
-description: "[devflow] Check the running app, CLI, or server against the active spec's done-when criteria and capture observable pass or fail evidence without editing code. Use for /check, proving behavior before completion beyond builds and tests."
-argument-hint: "[{run-id, number, or name}]"
+description: "[devflow] Check the running app, CLI, or server against the active spec's done-when criteria and capture observable pass or fail evidence without editing source. Use /check to verify real feature behavior, or /check guide [latest|scope] for a read-only manual walkthrough: how to test manually, where to click, expected and incorrect results, or a human review path."
+argument-hint: "[guide] [latest | <step> | <path> | <route>]"
 ---
 
-# check - Dual-Axis Independent Verification Engine
+# check - verify behavior or explain how to try it
 
-$ARGUMENTS
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
 
-**First action:** Before project inspection, preflight, or any other tool call,
-publish `running` to `devflow/.state/run.json` using the dashboard activity
-contract in `AGENTS.md`.
-
-Where this sits in the workflow:
-
-    /implement  ->  [check]  ->  /complete
-    (built a       (dual-axis       (only once both
-     step or        review with      axes pass with
-     the feature)   empirical proof) evidence)
-
-`/implement` builds and does a quick build-plus-screenshot check inline. `/check` is the rigorous, repeatable gate for when a feature or step needs **empirical proof** on the running app and **two-axis code review** before merging.
-
-It changes no source and commits nothing — it executes, inspects, and reports observed facts.
-
----
-
-## Input
-
-- **Given an ID or name** (e.g. `/check 12`, `/check 012`) -> targets `devflow/context/{xxx-slug}/` and records audit ledger to `{xxx-slug}/findings.md`.
-- **With no argument** (`/check`) -> verifies the active run matching current git branch or single active spec.
-
----
-
-## Hybrid Browser Verification Engine
-
-Nexus-DevFlow uses a **Dual-Layer Browser Verification Hierarchy**:
-
-```text
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                    🌐 Hybrid Browser Verification Engine                    │
-├──────────────────────────────────────┬──────────────────────────────────────┤
-│ 1. Code-Driven Test Automation (CI)  │ 2. Interactive AI Visual QA (MCP)    │
-│    • Framework: Playwright           │    • Server: MCP browseros-neo       │
-│    • Command: npm run test:browser   │    • URL: http://127.0.0.1:9010/mcp  │
-│    • Purpose: Assertions, Headless,  │    • Purpose: Live DOM Inspection,   │
-│      Regression Suite & Pre-commit   │      Real Screenshot Proofs, /try    │
-└──────────────────────────────────────┴──────────────────────────────────────┘
-```
-
-1. **Layer 1: Code-Driven Repeatable Tests (Playwright)**:
-   - If `AGENTS.md` declares `Browser tests: <command>`, run that exact command as repeatable automated evidence.
-2. **Layer 2: Interactive AI Visual QA (MCP browseros-neo)**:
-   - When the `browseros-neo` MCP server (`http://127.0.0.1:9010/mcp`) is active, use it to inspect the live running app, verify rendered CSS/layout, test click flows, and capture actual screenshot proofs.
-
----
-
-## Step 1 - Build the Dual-Axis Review Matrix
+## Select the mode before any tool call
 
-Read the target spec from `devflow/context/{xxx-slug}/spec.md` and `devflow/context/coding-standards.md`. Prepare the inspection criteria across two independent axes:
+- `/check guide` or `$check guide`: generate a read-only manual walkthrough.
+  Pass remaining arguments such as `latest`, a step, a path, route, or command
+  to `reference/guide.md`. Read and follow that reference only. Do not write
+  activity state, run checks or the app, edit files, update spec status, or
+  produce verification receipts.
+- A natural-language request for instructions on how the user can manually test
+  or review a change also selects guide mode. If the request mixes a guide with
+  agent verification, clarify which mode to run first before any activity.
+- `/check` or `$check`, optionally with a verification scope: verify observed
+  behavior against the spec. Follow verification startup below, then read and
+  follow `reference/verify.md` only.
 
-1. **Axis 1 (Standards & Architecture Criteria)**:
-   - Coding conventions in `coding-standards.md`
-   - Deep Modules discipline (Small interface, deep implementation, clean seams, no leaky abstractions)
-   - Baseline 12 Fowler Code Smells (Primitive obsession, Feature envy, Shotgun surgery, Speculative generality, etc.)
-   - Multi-lane technical gates (Typecheck, test suites, zero secrets, zero P0/P1 findings)
-2. **Axis 2 (Spec Fidelity & Behavioral Observables)**:
-   - Line-by-line Acceptance Criteria (ACs) and "Done When" observables from `devflow/context/{xxx-slug}/spec.md`
-   - Scope Creep detection (Unrequested behavior in the diff)
-   - Missing Requirements detection (Unimplemented edge cases)
+Load only the selected reference. Do not read both references preemptively.
+Guide generation never satisfies a verification gate. The existing
+`qualityGates.regular.tryGuide` and `qualityGates.continuous.tryGuide` keys now
+select `/check guide`; their policy values and automatic invocation rules are
+unchanged. The separate `check` gates continue to select verification mode.
 
----
-
-## Step 2 - Get the App Running & Exercise Live Proof
-
-Use the project's real commands (from `AGENTS.md`):
-
-- **Web app**: Start (or reuse) the local dev server. Drive a real browser to relevant routes. If `Browser tests: <command>` is declared, run it. When MCP `browseros-neo` is active, connect to inspect live visual state.
-- **CLI**: Execute commands with representative input fixtures, asserting exit codes and output snapshots.
-- **Server / API**: Hit endpoints with real payloads and assert on HTTP response status and bodies.
-- **Library**: Exercise public interfaces through integration tests or sample scripts.
-
-> [!IMPORTANT]
-> **Evidence or it didn't happen**: Every verdict must be backed by empirical evidence (screenshot, command output, status code, response time). Never assume a pass from reading source code alone.
-
----
-
-## Step 3 - Dual-Axis Independent Report & State Update
-
-Format the report into two distinct, un-merged review axes:
-
-```markdown
-# 🔍 Verification Report: [Feature Name]
+## Verification startup (verification mode only)
 
-## ⚖️ Axis 1: Standards, Architecture & Quality Gate
-
-- **Technical Lanes**:
-  - [pass] Type Safety: `tsc --noEmit` (0 errors)
-  - [pass] Automated Tests: `npm test` (All tests green)
-  - [pass] Browser Tests: `npm run test:browser` (Playwright passed)
-  - [pass] Visual Inspection: MCP browseros-neo verified UI layout & zero console errors
-  - [pass] Security & Hygiene: Zero secrets, sanitized inputs
-  - [pass] Findings Ledger: 0 blocking P0/P1 in `devflow/context/{xxx-slug}/findings.md`
-- **Deep Modules & Architecture**:
-  - [pass] Seam Integrity: Public interfaces remain small, implementation details hidden.
-  - [pass] The Deletion Test: Complexity is concentrated inside the module, not scattered across callers.
-- **Code Smells Assessment**:
-  - [clean] 12 Fowler Code Smells evaluated across git diff: No critical smells detected.
-
-## 🎯 Axis 2: Spec Fidelity & Behavioral Acceptance Gate
-
-Line-by-line verification against `devflow/context/{xxx-slug}/spec.md`:
-- [pass] **AC-1 (<title>)**: <Observed empirical evidence / screenshot path>
-- [pass] **AC-2 (<title>)**: <Observed empirical evidence / terminal output>
-- [fail] **AC-3 (<title>)**: <Exact observed failure with reproduction command>
-- [clean] **Scope Creep Check**: No unrequested features or unnecessary abstractions introduced.
-- [clean] **Completeness Check**: 100% of spec requirements addressed.
-
----
-
-## 🚦 Final Routing & Verdict
-
-- **ALL PASSED**: Both axes green. Update `stage.md` (Passed -> Ready for `/complete`).
-- **ANY FAILURE**: Hand back to `/implement` with exact failure evidence and reproduction steps.
-- **UNVERIFIABLE**: Clearly document the gap and residual risk. Never fabricate a pass.
-```
+**First action:** Before project inspection, preflight, or any other tool call,
+publish `running` to `devflow/.state/run.json` using the dashboard activity
+contract in `AGENTS.md`, with command `check`. This precedes reading the
+verification reference. Guide mode must skip this startup entirely.

package/template/.claude/skills/check/reference/guide.md

@@ -0,0 +1,126 @@
+# Check guide - manual review guide
+
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
+
+Where this sits in the workflow:
+
+    /implement or /complete  ->  [check guide]  ->  human review
+    (work exists)                (manual           (where to go,
+                                  path)             what to click)
+
+`/check` proves behavior from the agent side. `/check guide` gives the user a practical
+manual walkthrough: start this command, open this route, click these controls,
+expect this result, and watch for these failure signs.
+
+It is always read-only. Do not edit files, write activity state, update spec
+status, run checks or the app, install dependencies, commit, merge, push, or
+produce verification receipts. Reading files and git status is allowed. A guide
+never counts as acceptance evidence or proof that any check passed.
+
+The quality-gate config controls when another workflow generates this guide
+automatically. An explicit `/check guide` or `$check guide` request always runs.
+A generated guide never counts as evidence that the user performed the walkthrough.
+
+## Input
+
+Optional scope:
+
+- no argument: use the active task spec in `devflow/context/{xxx-slug}/spec.md`
+- `latest`: use the most recent archive under `devflow/history/features/`,
+  `devflow/history/fixes/`, or `devflow/history/rollbacks/`
+- a step name or number: focus the guide on that current task step
+- a path, route, or command: include it as the main thing to try
+
+If there is no active feature and no useful archive, ask what change the user
+wants to try instead of guessing.
+
+## Step 1 - find the work to explain
+
+Read:
+
+- `AGENTS.md`
+- `devflow/config.json`
+- `devflow/context/{xxx-slug}/spec.md`
+- `devflow/context/project-overview.md`
+- `devflow/context/coding-standards.md`
+- `devflow/build-plan.md`
+- latest files under `devflow/history/features/`,
+  `devflow/history/fixes/`, and `devflow/history/rollbacks/`, if the current
+  feature is reset
+- git branch and working tree status
+
+For `latest`, use the most recent archive even when an active spec exists.
+Otherwise prefer the active spec. If the active spec is missing, use
+the most recent archived feature, fix, or rollback by filename or modification time and
+say that is what you used.
+
+Do not dump the spec. Pull out the routes, commands, UI surfaces, CLI commands,
+API endpoints, data states, and done-whens that matter for a human trying it.
+For a rollback, lead with the path that proves the removed behavior is gone, then
+include one unaffected regression path from the rollback spec.
+
+## Step 2 - identify how to run the app
+
+Use the Commands section in `AGENTS.md`. Match the project type:
+
+- **Web app** - dev server command, URL, and the route or screen to open.
+- **Server/API** - server command, base URL, endpoint, method, and expected
+  response shape.
+- **CLI** - exact command(s), arguments, and expected output.
+- **Library** - example command, test fixture, REPL snippet, or sample call.
+- **Hybrid app** - list the smallest set of commands needed, such as backend plus
+  web dev server.
+
+If the app may already be running, say how to reuse it. If a command is missing
+from `AGENTS.md`, report that as a gap rather than inventing certainty.
+
+## Step 3 - write the manual guide
+
+Produce a short guide with these sections:
+
+1. **Start** - commands to run and where to run them.
+2. **Open** - URLs, screens, tabs, API endpoints, or CLI commands.
+3. **Do** - clicks, inputs, selections, or command arguments.
+4. **Expect** - visible result, output, response, state change, file, or lack of
+   error.
+5. **Watch For** - common wrong outcomes, console or network errors, stale data,
+   missing fields, bad empty states, layout issues, or safety warnings.
+
+Keep it concrete. Prefer:
+
+    Open http://127.0.0.1:7788/api/snapshot
+    Expect a JSON object with `generated_at`, `services`, `projects`, and
+    `conflicts`.
+
+Avoid:
+
+    Check that the snapshot works.
+
+## Step 4 - include confidence and gaps
+
+End with:
+
+- **Best signal** - the one thing the user should try first.
+- **Optional deeper checks** - only if useful.
+- **Gaps** - anything the guide cannot know from the docs, such as missing route
+  names, seed data, credentials, or external services.
+
+If the feature is not user-visible, say so and provide the closest manual signal,
+such as an API response, CLI output, log line, or unit test command.
+
+## Rules
+
+- Read-only only. Do not edit, commit, merge, push, install, or delete.
+- Do not run the app or verification commands in guide mode. If the user asks
+  you to try it for them, leave guide mode and explicitly route to `/check`
+  verification, following its activity and authorization rules.
+- Do not pretend a path is known when the spec does not say it. Give the best
+  likely path and label uncertainty.
+- Keep the guide short enough to follow while the app is open.
+- Match the project's commands from `AGENTS.md`.
+
+## Formatting
+
+Format the output to match the project's conventions in
+`devflow/context/ai-interaction.md`: concise, scannable markdown, with numbered
+steps for the manual path and short bullets for warnings.