fix(设备实名): 无当前卡时按绑定卡实名回退并初始化单槽当前卡

- 设备资产解析外层 real_name_status：存在当前使用卡时沿用该卡状态，无任何当前卡时任一有效绑定卡已实名即视为已实名
- 手工绑定与设备导入：设备最大槽位为 1 且有效绑定唯一时，在同一事务内将该绑定初始化为当前使用卡；多卡设备不推断
- 同步 asset-device、personal-customer 主 Spec；归档变更并附存量核对清单（75 条单槽唯一待修复绑定，其中 16 条已实名）

.agents/rules/ponytail.md

@@ -1,30 +0,0 @@
-# Ponytail, lazy senior dev mode
-
-You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
-
-Before writing any code, stop at the first rung that holds:
-
-1. Does this need to be built at all? (YAGNI)
-2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
-3. Does the standard library already do this? Use it.
-4. Does a native platform feature cover it? Use it.
-5. Does an already-installed dependency solve it? Use it.
-6. Can this be one line? Make it one line.
-7. Only then: write the minimum code that works.
-
-The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
-
-Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
-
-Rules:
-
-- No abstractions that weren't explicitly requested.
-- No new dependency if it can be avoided.
-- No boilerplate nobody asked for.
-- Deletion over addition. Boring over clever. Fewest files possible.
-- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
-- Question complex requests: "Do you actually need X, or does Y cover it?"
-- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
-- Mark intentional simplifications with a `ponytail:` comment. If the shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic), the comment names the ceiling and the upgrade path.
-
-Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

.agents/skills/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,55 @@
+# Phase boundaries
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make — continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+Work top to bottom at the boundary. The first **yes** wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** Is everything in this session — the exploration, the decisions, the dead ends — disposable? If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal — the old session stays resumable.
+
+The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
+
+**3. Do you need to hand off?** `/handoff` is narrow. You need it only when you are:
+
+- swapping to a **new harness** (Claude → Codex),
+- moving to a **new directory** or repo,
+- sending the work to a **colleague**,
+- or forking a side task you found **mid-phase** without derailing what you're doing.
+
+That list is the whole clause. What `/handoff` buys is **portability** — a file that travels. If nothing is travelling, you don't need it.
+
+**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
+
+**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop — this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
+
+`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except **Continue** turns a **primary source** into a **secondary source** — the session as it happened, replaced by a summary of it. The trade is always the same shape:
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `/handoff`) | Lossy       | Less  | Lots         |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
+
+## These are judgement calls
+
+The questions are not objective — each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.

.agents/skills/ask-matt/SKILL.md

@@ -14,13 +14,13 @@ A **flow** is a path through the skills. Most paths run along one **main flow**,
 
 The route most work travels. You have an idea and want it built.
 
-1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail.)
-2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions):
+1. **`/grill-with-docs`** — sharpen the idea by interview. Start here whenever you are **working in a working directory**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No working directory? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail, which makes it the better of the two whenever a repo is there to leave it in.)
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (a prototype lives in its own directory, which is exactly what `/handoff` is for — see Phase boundaries):
    - **`/handoff`** out, then open a fresh session against that file,
    - **`/prototype`** to answer the question with throwaway code,
    - **`/handoff`** back what you learned, and reference it from the original idea thread.
 3. **Branch — is this a multi-session build?**
-   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **clearing context between each one**.
+   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
    - **No** → **`/implement`** right here, in the same context window.
 
    Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
@@ -29,7 +29,7 @@ The route most work travels. You have an idea and want it built.
 
 Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
 
-The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/handoff` and continue in a fresh thread.
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~150k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/compact` at the nearest phase boundary and carry on (see Phase boundaries).
 
 ## On-ramps
 
@@ -58,20 +58,32 @@ Two model-invoked references that run *beneath* the other skills — each the si
 - **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
 - **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
 
-## Crossing sessions
+## Phase boundaries
 
-- **`/handoff`** — when a thread is full or you need to branch off (e.g. into a `/prototype` session), this compacts the conversation into a markdown file. You don't continue in place — you **open a new session and reference that file** to carry the context across. It's the bridge between context windows, in either direction. Use it when you want a **fresh session** but need the **current conversation preserved**.
-- **`/compact`** (built-in) — stay in the **same conversation**, letting the earlier turns be summarized. Use it at **intentional breaks between phases**, when you don't mind losing the verbatim history. Don't compact mid-phase — the agent can lose its way. `/handoff` forks; `/compact` continues.
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. At the **boundary** between two of them you have five options, and picking between them is the fuzziest decision in this whole map:
+
+- **Continue** — stay put. Costs nothing, loses nothing.
+- **`/clear`** — empty the window, when nothing here matters to what's next.
+- **`/handoff`** — write a portable markdown file. Narrow: only for a **new harness**, a **new directory**, a **colleague**, or forking a side task **mid-phase**. What it buys is portability.
+- **Subagent** — send a tightly-scoped task to its own window and get a report back.
+- **`/compact`** — compress this context and seed a fresh session with it. The **default**, at the bottom of the tree rather than the first reach.
+
+Read [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) for the ordered tree — the five questions, the reasoning behind each branch, and why the primary-source cost makes **Continue** the one to rule out first. Make the decision **at** a boundary; mid-phase, continue or split the rest into subagents.
 
 ## Standalone
 
 Off the main flow entirely.
 
-- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo.
-- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway from day one — keep the answer, delete the code. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
+- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but **stateless**: it saves nothing locally and builds no `CONTEXT.md`. Reach for it when you are **not working in a working directory** — sharpening a plan, a design, a piece of writing, anything with no repo under it. If you are in a working directory, use `/grill-with-docs` instead: it runs the same interview and leaves a paper trail, so it is strictly the better one.
+- **`/grilling`** — the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `/grill-me` and `/grill-with-docs` are the two named ways in, and `/triage`, `/wayfinder` and `/improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
+- **`/resolving-merge-conflicts`** — work an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finish the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
+- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
 - **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
+- **`/wizard`** — for the steps only a **human** can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop.
+- **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
-- **`/writing-great-skills`** — reference for writing and editing skills well.
+- **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.
 
 ## Precondition
 

.agents/skills/caveman/SKILL.md

@@ -1,49 +0,0 @@
----
-name: caveman
-description: >
-  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
-  filler, articles, and pleasantries while keeping full technical accuracy.
-  Use when user says "caveman mode", "talk like caveman", "use caveman",
-  "less tokens", "be brief", or invokes /caveman.
----
-
-Respond terse like smart caveman. All technical substance stay. Only fluff die.
-
-## Persistence
-
-ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
-
-## Rules
-
-Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
-
-Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
-
-Pattern: `[thing] [action] [reason]. [next step].`
-
-Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
-Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
-
-### Examples
-
-**"Why React component re-render?"**
-
-> Inline obj prop -> new ref -> re-render. `useMemo`.
-
-**"Explain database connection pooling."**
-
-> Pool = reuse DB conn. Skip handshake -> fast under load.
-
-## Auto-Clarity Exception
-
-Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
-
-Example -- destructive op:
-
-> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
->
-> ```sql
-> DROP TABLE users;
-> ```
->
-> Caveman resume. Verify backup exist first.

.agents/skills/code-review/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: code-review
-description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
 ---
 
 Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
-- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+- **Spec** — does the code faithfully implement the originating issue / spec?
 
 Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
 
@@ -28,7 +28,7 @@ Look for the originating spec, in this order:
 
 1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
 2. A path the user passed as an argument.
-3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
 4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
 
 ### 3. Identify the standards sources
@@ -57,8 +57,6 @@ Each smell reads *what it is* → *how to fix*; match it against the diff:
 
 ### 4. Spawn both sub-agents in parallel
 
-Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
-
 **Standards sub-agent prompt** — include:
 
 - The full diff command and commit list.

.agents/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -18,7 +18,7 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th
 
 ### 2. Spawn sub-agents
 
-Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface for the deepened module.
 
 Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
 

.agents/skills/diagnose/SKILL.md

@@ -1,117 +0,0 @@
----
-name: diagnose
-description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
----
-
-# Diagnose
-
-A discipline for hard bugs. Skip phases only when explicitly justified.
-
-When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
-
-## Phase 1 — Build a feedback loop
-
-**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
-
-### Ways to construct one — try them in roughly this order
-
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Iterate on the loop itself
-
-Treat the loop as a product. Once you have _a_ loop, ask:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
-
-Do not proceed to Phase 2 until you have a loop you believe in.
-
-## Phase 2 — Reproduce
-
-Run the loop. Watch the bug appear.
-
-Confirm:
-
-- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
-- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
-
-Do not proceed until you reproduce the bug.
-
-## Phase 3 — Hypothesise
-
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before the fix** — but only if there is a **correct seam** for it.
-
-A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
-
-**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
-
-If a correct seam exists:
-
-1. Turn the minimised repro into a failing test at that seam.
-2. Watch it fail.
-3. Apply the fix.
-4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
-
-## Phase 6 — Cleanup + post-mortem
-
-Required before declaring done:
-
-- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
-- [ ] Regression test passes (or absence of seam is documented)
-- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

.agents/skills/diagnose/scripts/hitl-loop.template.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-# Human-in-the-loop reproduction loop.
-# Copy this file, edit the steps below, and run it.
-# The agent runs the script; the user follows prompts in their terminal.
-#
-# Usage:
-#   bash hitl-loop.template.sh
-#
-# Two helpers:
-#   step "<instruction>"          → show instruction, wait for Enter
-#   capture VAR "<question>"      → show question, read response into VAR
-#
-# At the end, captured values are printed as KEY=VALUE for the agent to parse.
-
-set -euo pipefail
-
-step() {
-  printf '\n>>> %s\n' "$1"
-  read -r -p "    [Enter when done] " _
-}
-
-capture() {
-  local var="$1" question="$2" answer
-  printf '\n>>> %s\n' "$question"
-  read -r -p "    > " answer
-  printf -v "$var" '%s' "$answer"
-}
-
-# --- edit below ---------------------------------------------------------
-
-step "Open the app at http://localhost:3000 and sign in."
-
-capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
-
-capture ERROR_MSG "Paste the error message (or 'none'):"
-
-# --- edit above ---------------------------------------------------------
-
-printf '\n--- Captured ---\n'
-printf 'ERRORED=%s\n' "$ERRORED"
-printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

.agents/skills/diagnosing-bugs/SKILL.md

@@ -9,6 +9,12 @@ A discipline for hard bugs. Skip phases only when explicitly justified.
 
 When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
 
+## Redact
+
+This skill has you show commands, outputs and captured artifacts. **Redact every secret first** — write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
+
+If the redacted output is not enough to diagnose the bug, say so and ask the user.
+
 ## Phase 1 — Build a feedback loop
 
 **This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
@@ -46,11 +52,11 @@ The goal is not a clean repro but a **higher reproduction rate**. Loop the trigg
 
 ### When you genuinely cannot build a loop
 
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
 
 ### Completion criterion — a tight loop that goes red
 
-Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (show the invocation and its output, redacted), and that is:
 
 - [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
 - [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).

.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -11,6 +11,9 @@
 #   capture VAR "<question>"      → show question, read response into VAR
 #
 # At the end, captured values are printed as KEY=VALUE for the agent to parse.
+#
+# `capture` prints its value back to the terminal, where the agent reads it — so
+# capture observations, and leave signing in to the user as a `step`.
 
 set -euo pipefail
 

.agents/skills/grilling/SKILL.md

@@ -3,10 +3,20 @@ name: grilling
 description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
 ---
 
-Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
 
-Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
 
-If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+Each question should be formatted like so:
 
-Do not act on it until I confirm we have reached a shared understanding.
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree — settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it — don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report — ask the rest of the frontier now. The _decisions_ are the user's — put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

.agents/skills/grilling/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Grilling"
-  short_description: "Stress-test thinking one question at a time"
+  short_description: "Stress-test thinking a round of questions at a time"

.agents/skills/improve-codebase-architecture/SKILL.md

@@ -24,7 +24,7 @@ This command is _informed_ by the project's domain model and built on a shared d
 
 Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
 
-Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
 
 - Where does understanding one concept require bouncing between many small modules?
 - Where are modules **shallow** — interface nearly as complex as the implementation?

.agents/skills/prototype/LOGIC.md

@@ -1,13 +1,15 @@
 # Logic Prototype
 
-A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+A single, self-contained HTML file — a **shareable demo** — that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer — a designer, a PM, a domain expert — and let them feel the model for themselves. So it speaks their language, not the code's.
 
 ## When this is the right shape
 
 - "I'm not sure if this state machine handles the edge case where X then Y."
 - "Does this data model actually let me represent the case where..."
 - "I want to feel out what the API should look like before writing it."
-- Anything where the user wants to **press buttons and watch state change**.
+- Anything where someone wants to **press buttons and watch state change**.
 
 If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
 
@@ -15,17 +17,11 @@ If the question is "what should this look like" — wrong branch. Use [UI.md](UI
 
 ### 1. State the question
 
-Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
 
-### 2. Pick the language
+### 2. Isolate the logic in a portable module
 
-Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
-
-Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
-
-### 3. Isolate the logic in a portable module
-
-Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
+Put the actual logic — the bit that's answering the question — in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
 
 The right shape depends on the question:
 
@@ -34,46 +30,38 @@ The right shape depends on the question:
 - **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
 - **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
 
-Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
 
-This is what makes the prototype useful past its own lifetime: when the question's been answered, the validated reducer / machine / function set can be lifted into the real module on its own.
+### 3. Build the shareable HTML file
 
-### 4. Build the smallest TUI that exposes the state
+One file, plain HTML/CSS/JS — no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it.
 
-Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
+Write it for a non-developer. Every label is in **domain language**, not code — buttons and state read like the business, not the reducer. Explain in plain words what's happening.
 
-Each frame has two parts, in this order:
+Lay it out with a clean hierarchy, top to bottom:
 
-1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
-2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user  [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state** — the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons** — one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs** — a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario — the situation it sets up and what to watch for — and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
 
-Behaviour:
+Choose scenarios that demonstrate the awkward cases — the happy path, a tricky edge case, an attempt at something that should be illegal — the ones hard to reason about on paper.
 
-1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
-2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
-3. **Re-render** the full frame after every action — don't append, replace.
-4. **Loop until quit.**
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks — nothing that competes with the state and the buttons.
 
-The whole frame should fit on one screen.
+### 4. Hand it over
 
-### 5. Make it runnable in one command
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
 
-Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
+### 5. Capture the answer and the prototype
 
-If the host project has no task runner, just put the command at the top of the prototype's README.
-
-### 6. Hand it over
-
-Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
-
-### 7. Capture the answer and the prototype
-
-Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the TUI shell rides along to the throwaway branch that keeps the prototype as a primary source.
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps the prototype as a primary source — and being one self-contained file, it stays trivially re-runnable there.
 
 ## Anti-patterns
 
 - **Don't add tests.** A prototype that needs tests is no longer a prototype.
-- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
 - **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
-- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
-- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.

.agents/skills/prototype/SKILL.md

@@ -11,7 +11,7 @@ A prototype is **throwaway code that answers a question**. The question decides
 
 Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
 
-- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a single shareable HTML file — free-play buttons plus tabbed guided walkthroughs — that pushes the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.
 - **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
 
 The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
@@ -19,7 +19,7 @@ The two branches produce very different artifacts — getting this wrong wastes
 ## Rules that apply to both
 
 1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
-2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
+2. **Trivial to run.** A UI prototype starts from one command in the project's task runner — `pnpm <name>`, `python <path>`, `bun <path>`, etc. A logic demo is a single HTML file the user double-clicks. Either way, no thinking required to start it.
 3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
 4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
 5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.

.agents/skills/setup-matt-pocock-skills/SKILL.md

@@ -37,7 +37,7 @@ Lead each section with the recommended answer so the user can accept it in a wor
 
 **Section A — Issue tracker.**
 
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
 
 Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
 

.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md

@@ -1,6 +1,6 @@
 # Issue tracker: GitHub
 
-Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
 
 ## Conventions
 

.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md

@@ -1,6 +1,6 @@
 # Issue tracker: GitLab
 
-Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+Issues and specs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
 
 ## Conventions
 

.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md

@@ -1,6 +1,6 @@
 # Issue tracker: Local Markdown
 
-Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
+Issues and specs for this repo live as markdown files in `.scratch/`.
 
 ## Conventions
 

.agents/skills/tdd/SKILL.md

@@ -23,6 +23,8 @@ A **seam** is the public boundary you test at: the interface where you observe b
 
 Ask: "What's the public interface, and which seams should we test?"
 
+When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — use the `/codebase-design` skill for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
+
 ## Anti-patterns
 
 - **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.

.agents/skills/to-issues/SKILL.md

@@ -1,84 +0,0 @@
----
-name: to-issues
-description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.
-disable-model-invocation: true
----
-
-# To Issues
-
-Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
-
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
-
-## Process
-
-### 1. Gather context
-
-Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker and read its full body and comments.
-
-### 2. Explore the codebase (optional)
-
-If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
-
-Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
-
-### 3. Draft vertical slices
-
-Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
-
-<vertical-slice-rules>
-
-- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
-- A completed slice is demoable or verifiable on its own
-- Any prefactoring should be done first
-
-</vertical-slice-rules>
-
-### 4. Quiz the user
-
-Present the proposed breakdown as a numbered list. For each slice, show:
-
-- **Title**: short descriptive name
-- **Blocked by**: which other slices (if any) must complete first
-- **User stories covered**: which user stories this addresses (if the source material has them)
-
-Ask the user:
-
-- Does the granularity feel right? (too coarse / too fine)
-- Are the dependency relationships correct?
-- Should any slices be merged or split further?
-
-Iterate until the user approves the breakdown.
-
-### 5. Publish the issues to the issue tracker
-
-For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. These issues are considered ready for AFK agents, so publish them with the correct triage label unless instructed otherwise.
-
-Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field.
-
-<issue-template>
-## Parent
-
-A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
-
-## What to build
-
-A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation.
-
-Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it here and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
-
-## Acceptance criteria
-
-- [ ] Criterion 1
-- [ ] Criterion 2
-- [ ] Criterion 3
-
-## Blocked by
-
-- A reference to the blocking ticket (if any)
-
-Or "None - can start immediately" if no blockers.
-
-</issue-template>
-
-Do NOT close or modify any parent issue.

.agents/skills/to-prd/SKILL.md

@@ -1,75 +0,0 @@
----
-name: to-prd
-description: Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
-disable-model-invocation: true
----
-
-This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
-
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
-
-## Process
-
-1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
-
-2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
-
-Check with the user that these seams match their expectations.
-
-3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
-
-<prd-template>
-
-## Problem Statement
-
-The problem that the user is facing, from the user's perspective.
-
-## Solution
-
-The solution to the problem, from the user's perspective.
-
-## User Stories
-
-A LONG, numbered list of user stories. Each user story should be in the format of:
-
-1. As an <actor>, I want a <feature>, so that <benefit>
-
-<user-story-example>
-1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
-</user-story-example>
-
-This list of user stories should be extremely extensive and cover all aspects of the feature.
-
-## Implementation Decisions
-
-A list of implementation decisions that were made. This can include:
-
-- The modules that will be built/modified
-- The interfaces of those modules that will be modified
-- Technical clarifications from the developer
-- Architectural decisions
-- Schema changes
-- API contracts
-- Specific interactions
-
-Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
-
-Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
-
-## Testing Decisions
-
-A list of testing decisions that were made. Include:
-
-- A description of what makes a good test (only test external behavior, not implementation details)
-- Which modules will be tested
-- Prior art for the tests (i.e. similar types of tests in the codebase)
-
-## Out of Scope
-
-A description of the things that are out of scope for this PRD.
-
-## Further Notes
-
-Any further notes about the feature.
-
-</prd-template>

.agents/skills/to-questionnaire/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: to-questionnaire
+description: Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
+disable-model-invocation: true
+---
+
+Turn something the user can't answer alone into a **questionnaire** — a Markdown document they hand to one person to fill in async, or fill out together over a meeting. The recipient holds knowledge the user lacks; the questionnaire pulls it out of them.
+
+**Grill the send, not the subject.** Interview the user only about the _send_, which they can always answer: who it goes to, and what they need back. The questions in the document then target the **gap** between what the recipient knows and what the user needs.
+
+1. **Who is it going to?** Ask, in one exchange, the recipient's role, expertise, and relationship to the user. This fixes the questionnaire's tone and how much context it must carry. Done when you know who the recipient is and what they know that the user doesn't.
+
+2. **What do you need back?** Ask, in one exchange, the specific decisions or facts the user can't resolve alone and needs from this person. Done when you have a concrete list of what the user must walk away able to do or decide.
+
+3. **Write the questionnaire.** Draft questions aimed at the gap from steps 1–2, following the Document structure below. Write it to `to-questionnaire-<slug>.md` in the current directory (slug from the topic) and report the path. Done when the file exists and every item the user named in step 2 is covered by a question.
+
+## Document structure
+
+Frame the document as a **discovery questionnaire**: the user lacks context, the recipient holds it. Order questions most-important-first — async means you may only get one pass — and group them under `##` headings by theme once there are more than a handful. Write it using the template below.
+
+<questionnaire-template>
+
+# <Questionnaire title>
+
+**Purpose:** why this questionnaire exists and the decision riding on it.
+
+**From:** <the user> — **To:** <the recipient> — **How your answers will be used:** <where they go>
+
+## Context
+
+One paragraph orienting a recipient who wasn't in the user's head. Enough to answer well, not a page.
+
+## How to answer
+
+Deadline and rough effort. Partial answers and "I don't know" are useful — flag anything you're unsure of rather than skipping it.
+
+## <Theme heading>
+
+One `##` section per theme. Under each, its questions, most-important-first. Every question is one idea — never compound — with an answer stub directly beneath, and a one-line _why this matters_ only where the question could be misread or invite a throwaway answer.
+
+<question-example>
+### What load is the system expected to handle at launch?
+
+_Why this matters: it decides whether we provision for burst traffic now or defer it._
+
+>
+</question-example>
+
+## Anything else?
+
+A closing catch-all: anything we didn't ask that we should know?
+
+</questionnaire-template>

.agents/skills/to-questionnaire/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "To Questionnaire"
+  short_description: "Front-load questions into a doc for someone to answer"
+policy:
+  allow_implicit_invocation: false

.agents/skills/to-spec/SKILL.md

@@ -4,7 +4,7 @@ description: Turn the current conversation into a spec and publish it to the pro
 disable-model-invocation: true
 ---
 
-This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know.
+This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.
 
 The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
 

.agents/skills/to-tickets/SKILL.md

@@ -103,5 +103,3 @@ The end-to-end behaviour this ticket makes work, from the user's perspective —
 </issue-template>
 
 In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
-
-Work the frontier one ticket at a time with `/implement`, clearing context between tickets.

.agents/skills/triage/SKILL.md

@@ -73,7 +73,7 @@ Show counts and a one-line summary per item. Let the maintainer pick.
 
 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
 
-4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
+4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
 
 5. **Apply the outcome:**
    - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).

.agents/skills/wait-what/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: wait-what
+description: Stop. That last message did not land — re-pitch it.
+disable-model-invocation: true
+---
+
+Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`.

.agents/skills/wait-what/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Wait What"
+  short_description: "Re-pitch that — simpler, with the context I'm missing"
+policy:
+  allow_implicit_invocation: false

.agents/skills/wayfinder/SKILL.md

@@ -14,7 +14,7 @@ Wayfinder is **planning** by default: each ticket resolves a decision, and the m
 
 ## Refer by name
 
-Every map and ticket is an issue, so it has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride *inside* the name, never stand in for it.
+Every map and ticket is an issue, so it has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride _inside_ the name, never stand in for it.
 
 ## The Map
 
@@ -72,12 +72,12 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr
 
 ## Ticket Types
 
-Every ticket is either **HITL** — human in the loop, worked *with* a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
+Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
 - **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/research` **subagent**. Use when knowledge outside the current working directory is required.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
-- **Grilling** (HITL): Conversation via the /grilling and /domain-modeling skills, one question at a time. The default case.
-- **Task** (HITL or AFK): Manual work that must happen before a *decision* can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that *does* rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
+- **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
+- **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
 
 ## Fog of war
 

.agents/skills/wizard/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: wizard
+description: Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
+---
+
+# Wizard
+
+A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets), confirms at every stage, and shows how many stages are left. It might configure third-party services, run a one-off migration, or move the project from one state to another.
+
+The delightful UX is already solved by [template.sh](template.sh) — stage-by-stage progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point — never hand-edit it.
+
+A wizard is ephemeral by default — built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo.
+
+## Process
+
+### 1. Scope the procedure
+
+Work out every manual step the human must take and every value that gets captured along the way. Read the repo first — don't ask cold:
+
+- For setup: `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, framework config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference is a value the wizard must produce).
+- For a migration or transition: the current state, the target state, and the irreversible actions between them.
+
+Then show the user the ordered list of stages and the values each produces, and confirm — they may add, drop, or reorder.
+
+**Done when:** every stage is named in order, and for each captured value you know (a) where the human gets it, (b) where it's written (`.env`, a GitHub secret, both, or nowhere — some stages are pure actions), and (c) whether it's secret (hidden entry) or public.
+
+### 2. Map each stage's journey
+
+For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills — e.g. "Dashboard → Developers → API keys → Reveal test key → copy". Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs — never invent steps that may not exist.
+
+**Done when:** every stage traces to concrete instructions a stranger could follow.
+
+### 3. Author the wizard
+
+Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — and set `TOTAL_STAGES` to the number of stages you wrote.
+
+Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every persisted value, `set_secret` only the values CI actually needs, and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible — keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker.
+
+### 4. Verify and hand off
+
+- `bash -n <script>`; run `shellcheck` if available.
+- `chmod +x <script>`.
+- Don't run it end-to-end yourself — it opens browsers and blocks on human input. Trace it statically instead: every value from step 1 is captured and lands where step 1 said, and every `set_secret` name exactly matches a `secrets.*` reference in CI.
+- Tell the user how to run it. If it's a repeatable setup path, commit it and link it from the README so the next person runs the script instead of asking an AI.

.agents/skills/wizard/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Wizard"
+  short_description: "Generate an interactive setup wizard"

.agents/skills/wizard/template.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+#
+# A wizard — walks a human through a manual procedure step by step.
+# Generated by the /wizard skill.
+#
+# Everything above the "STAGES" marker is the wizard library: do not hand-edit
+# it. Author the per-step stages below the marker.
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# Wizard library — delightful, consistent UX. Identical across every wizard.
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# Author sets this at the top of the stages section.
+TOTAL_STAGES=0
+
+_STAGE_INDEX=0
+ENV_FILE="${ENV_FILE:-.env}"
+WRITTEN_ENV=()    # KEYs written to ENV_FILE this run
+WRITTEN_SECRET=() # secret NAMEs set this run
+SKIPPED=()        # things we couldn't do (e.g. gh missing)
+
+# _clear — wipe the terminal so only the current step is on screen. No-op when
+# output isn't a terminal, so piped logs stay readable.
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "Title" — opening frame: what this wizard does.
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  %s stages%s\n\n' "$DIM" "$TOTAL_STAGES" "$RESET"
+  printf '%s  You drive the browser; this wizard tells you exactly what to do and\n' "$DIM"
+  printf '  captures the values you copy back. Stop any time with Ctrl-C and re-run\n'
+  printf '  later — it remembers values already saved.%s\n' "$RESET"
+  pause "Ready to start?"
+}
+
+# stage "Name" — clear the screen, then announce a stage and show progress.
+# Clearing keeps only the current step on screen.
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  printf '\n%s%s▸ Stage %s/%s · %s%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET"
+}
+
+# say "..." — a plain instruction line.
+say()  { printf '  %s\n' "$1"; }
+# step "..." — a numbered-feeling action the human takes in the browser.
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL — open in the human's browser, cross-platform incl. WSL.
+open_url() {
+  local url="$1"
+  printf '  %s↗ opening%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else warn "couldn't open a browser — visit it manually: $url"; fi
+  } >/dev/null 2>&1 || warn "couldn't open a browser — visit it manually: $url"
+}
+
+# pause "msg" — wait for the human to confirm they've done the manual part.
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-Press Enter to continue}" "$RESET"
+  read -r _ || true
+}
+
+# confirm "question" — y/N gate; returns success on yes.
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || true
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+# _existing KEY — current value of KEY in ENV_FILE, if any.
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  printf '%s' "${line#*=}"
+}
+
+# ask KEY "Prompt" — read a value into $KEY. Offers the existing .env value as
+# a default on re-runs (Enter keeps it). Visible input (non-secret).
+ask() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || true
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "Prompt" — like ask, but input is hidden.
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || true
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE — upsert KEY=VALUE into ENV_FILE (creates it; replaces
+# any existing line). Idempotent.
+write_env() {
+  local key="$1" value="$2" tmp
+  touch "$ENV_FILE"
+  tmp=$(mktemp)
+  grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  mv "$tmp" "$ENV_FILE"
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ wrote%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+# set_secret NAME VALUE — set a GitHub Actions repo secret via gh. Falls back
+# to a warning (and records it) if gh is unavailable or unauthenticated.
+set_secret() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if printf '%s' "$value" | gh secret set "$name" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ set%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name (set it manually: gh secret set $name)")
+  warn "skipped GitHub secret $name — gh not ready; set it later"
+}
+
+# set_var NAME VALUE — set a GitHub Actions repo variable (non-secret).
+set_var() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if gh variable set "$name" --body "$value" >/dev/null 2>&1; then
+      printf '  %s✓ set%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "skipped GitHub variable $name — gh not ready; set it later"
+}
+
+# finish — clear, then a closing summary of everything configured.
+finish() {
+  _clear
+  printf '\n%s%s  ✓ Setup complete%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "wrote ${#WRITTEN_ENV[@]} value(s) to $ENV_FILE: ${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "set ${#WRITTEN_SECRET[@]} GitHub secret(s): ${WRITTEN_SECRET[*]}"
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "still to do by hand:"
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES — author this section. One stage() per step the human takes.
+# Replace the example below. Set TOTAL_STAGES to match the stages you write.
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=1
+
+banner "Stripe setup"
+
+# ── Example stage: replace with your real steps ───────────────────────────
+stage "Stripe — API keys"
+say "We'll grab your Stripe test keys and store them for local dev + CI."
+open_url "https://dashboard.stripe.com/test/apikeys"
+step "On the API keys page, copy the Publishable key (starts pk_test_)."
+ask STRIPE_PUBLISHABLE_KEY "Paste the publishable key:"
+step "Click 'Reveal test key' on the Secret key row, then copy it."
+ask_secret STRIPE_SECRET_KEY "Paste the secret key:"
+write_env STRIPE_PUBLISHABLE_KEY "$STRIPE_PUBLISHABLE_KEY"
+write_env STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"
+set_secret STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"   # CI needs this one
+# ──────────────────────────────────────────────────────────────────────────
+
+finish

.agents/skills/write-a-skill/SKILL.md

@@ -1,117 +0,0 @@
----
-name: write-a-skill
-description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
----
-
-# Writing Skills
-
-## Process
-
-1. **Gather requirements** - ask user about:
-   - What task/domain does the skill cover?
-   - What specific use cases should it handle?
-   - Does it need executable scripts or just instructions?
-   - Any reference materials to include?
-
-2. **Draft the skill** - create:
-   - SKILL.md with concise instructions
-   - Additional reference files if content exceeds 500 lines
-   - Utility scripts if deterministic operations needed
-
-3. **Review with user** - present draft and ask:
-   - Does this cover your use cases?
-   - Anything missing or unclear?
-   - Should any section be more/less detailed?
-
-## Skill Structure
-
-```
-skill-name/
-├── SKILL.md           # Main instructions (required)
-├── REFERENCE.md       # Detailed docs (if needed)
-├── EXAMPLES.md        # Usage examples (if needed)
-└── scripts/           # Utility scripts (if needed)
-    └── helper.js
-```
-
-## SKILL.md Template
-
-```md
----
-name: skill-name
-description: Brief description of capability. Use when [specific triggers].
----
-
-# Skill Name
-
-## Quick start
-
-[Minimal working example]
-
-## Workflows
-
-[Step-by-step processes with checklists for complex tasks]
-
-## Advanced features
-
-[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
-```
-
-## Description Requirements
-
-The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
-
-**Goal**: Give your agent just enough info to know:
-
-1. What capability this skill provides
-2. When/why to trigger it (specific keywords, contexts, file types)
-
-**Format**:
-
-- Max 1024 chars
-- Write in third person
-- First sentence: what it does
-- Second sentence: "Use when [specific triggers]"
-
-**Good example**:
-
-```
-Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
-```
-
-**Bad example**:
-
-```
-Helps with documents.
-```
-
-The bad example gives your agent no way to distinguish this from other document skills.
-
-## When to Add Scripts
-
-Add utility scripts when:
-
-- Operation is deterministic (validation, formatting)
-- Same code would be generated repeatedly
-- Errors need explicit handling
-
-Scripts save tokens and improve reliability vs generated code.
-
-## When to Split Files
-
-Split into separate files when:
-
-- SKILL.md exceeds 100 lines
-- Content has distinct domains (finance vs sales schemas)
-- Advanced features are rarely needed
-
-## Review Checklist
-
-After drafting, verify:
-
-- [ ] Description includes triggers ("Use when...")
-- [ ] SKILL.md under 100 lines
-- [ ] No time-sensitive info
-- [ ] Consistent terminology
-- [ ] Concrete examples included
-- [ ] References one level deep

.agents/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,22 @@
+# Skill mechanics
+
+The skill-specific branch of [`writing-for-agents`](SKILL.md): what changes when the document is a skill — frontmatter, the invocation choice, and router skills. Everything else about writing it is the universal reference in `SKILL.md`.
+
+## Invocation
+
+Two choices, trading the two loads:
+
+- A **model-invoked** skill keeps a `description`, so the agent can fire it autonomously — and other skills can reach it. You can still type its name: model-invocation always _includes_ user reach; a description only ever adds agent discovery, never removes the human's. The description is the skill's top-level context pointer, forced to stay loaded at all times — permanent context load in exchange for discoverability. A model-invoked skill whose content is all reference is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Mechanics: omit `disable-model-invocation`, and write a model-facing description carrying the trigger branches (the pointer-writing rules in `SKILL.md` apply in full).
+- A **user-invoked** skill strips the description from the agent's reach: only the human typing its name can invoke it, and no other skill can. Zero context load, but it spends cognitive load — you are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped.
+
+Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
+
+Shared reference that two user-invoked skills both need can live in neither — with no descriptions, neither can fire the other. Push it to a plain file outside the skill system: external reference any skill can point at.
+
+## Splitting by invocation
+
+The invocation cut of splitting (the sequence cut lives in `SKILL.md`): split off a model-invoked skill when you have a distinct leading word that should trigger it on its own — a trigger word you actually use in your prompts — or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
+
+## Router skills
+
+When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each, so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no description, so nothing but the human can reach them.

.agents/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: writing-for-agents
+description: Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
+---
+
+Reference for writing any document an agent consumes — a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable — the agent taking the same _process_ every run, not producing the same output.
+
+When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.
+
+## Context pointers
+
+A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material — and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
+
+A pointer does two jobs — state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
+
+- **Front-load the leading word** — the pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
+- **Cut identity the body already carries.**
+
+## The two loads
+
+Every document and pointer you add spends one of two budgets:
+
+- **Context load** — the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn, spending tokens and attention whether or not it fires.
+- **Cognitive load** — the cost on the human: which documents exist and when to reach for each. The human is the index. Not a cost to minimise — it is the price of human agency; spend it where human judgement matters, remove it where it does not.
+
+Material reached only through a pointer escapes context load at the price of the pointer's own line; material with no pointer at all rides entirely on cognitive load.
+
+## Information hierarchy
+
+A document is built from two content types — **steps** (the ordered actions the agent performs) and **reference** (definitions, rules, facts consulted on demand) — that mix freely: all steps (a recipe), all reference (a review's rules, this skill), or both. The core decision is where each piece sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-file step** — the primary tier: what the agent does, in order.
+2. **In-file reference** — consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell.
+3. **Disclosed reference** — pushed out into a separate file, reached by a context pointer, loaded only when the pointer fires. Spans a sibling file in the same folder through fully external reference that lives anywhere and any document can point at.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder — out of the main file and behind a pointer — so the top stays legible. Not primarily a token optimisation: it is how the hierarchy is protected. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. When a document has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one.
+
+**Co-location** is the within-file companion: where the ladder decides _how far down_ a piece sits, co-location decides _what sits beside it_ once there. Keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. The test: the document should read like documentation written for the agent — grouped material reads that way; scattered material does not. (Distinct from duplication: that repeats one meaning in two places; scattering fragments one meaning across many.)
+
+**Sprawl** is the failure mode here: a document simply too long, even when every line is live and unique. Attention thins across the excess, and every extra line is one more to keep relevant. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion** — the condition that tells the agent the work is done. Two properties make it a lever:
+
+- **Clarity** — can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**: ending the step before it is genuinely done, attention slipping to _being done_. The visible steps still ahead — the **post-completion steps** — supply the pull; the criterion's clarity is the resistance. Defend in order: **sharpen the bound first** (local and cheap); only if it is irreducibly fuzzy _and_ you observe the rush, hide the later steps by splitting the sequence — and hiding only works across a real context boundary (a hand-off or a subagent dispatch; an inline call leaves the later steps in context and clears nothing).
+- **Demand** — how much it requires. "Every modified model accounted for" forces thorough work where "produce a change list" does not. Demand drives **legwork** — the digging the agent does within the work, latent in the wording rather than written as its own step — and it is not step-bound: "every rule applied" binds a body of flat reference just as "every step done" binds a sequence, which is how an all-reference document still carries an exhaustiveness bar.
+
+The strongest criteria are both checkable and exhaustive.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when the cut earns it:
+
+- **By sequence** — split a run of steps where the post-completion steps tempt the agent to rush the one in front of it. Keeping them out of view drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's later steps to what follows, inviting premature completion.
+- **By invocation** — skill-specific: see [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md).
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the document (_lesson_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free; reach for an existing word first.
+
+It anchors twice. In the body, _execution_: the agent reaches for the same behaviour every time the word appears, and inside flat reference it focuses attention on a class of thing to look for. In a pointer, _invocation_: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the material and reaches it more reliably.
+
+Hunt for opportunities to refactor with leading words. A triad spelled out at three sites, a pointer spending a sentence to gesture at one idea — each is a passage begging to collapse into a single token:
+
+- "fast, deterministic, low-overhead" → _tight_ (a _tight_ loop).
+- "a loop you believe in" → _red_ — a fuzzy gate becomes a binary observable state (the loop goes _red_ on the bug, or it doesn't).
+
+You win twice: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every document is carrying restatements that leading words retire — go find them.
+
+**Negation** is the failure mode beside this lever: steering by prohibition drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; the negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Prompt the **positive** — state the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+## Pruning
+
+- Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** — the same meaning in more than one place — costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. (The accidental inverse of a leading word, which repeats a token on purpose, never the meaning.)
+- The **environment** is a source of truth too — `package.json` scripts, config files, the directory layout, `--help` output — and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale.
+- Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live.
+- Hunt **no-ops** sentence by sentence: an instruction the model already obeys by default pays load to say nothing. The test — does it change behaviour versus the default? — is model-relative, not reader-relative: two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The test also grades leading words: a word too weak to beat the default (_be thorough_ when the agent is already thorough-ish) is a no-op, and the fix is a stronger word (_relentless_), not a different technique.

.agents/skills/writing-for-agents/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Writing for Agents"
+  short_description: "Write documents agents consume"

.agents/skills/writing-great-skills/GLOSSARY.md

@@ -1,201 +0,0 @@
-# Glossary — Building Great Skills
-
-The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; the root virtue is **Predictability**, and every term below is a lever on it. This is the disclosed reference for [`writing-great-skills`](SKILL.md).
-
-The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean). Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
-
-**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
-
-## Predictability
-
-The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
-
-_Avoid_: consistency, reliability, robustness, output-determinism
-
-## Invocation
-
-How a skill is reached — and the two loads you pay for the choice.
-
-### Model-Invoked
-
-A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always _includes_ user reach. There is no model-only state: a description only ever _adds_ agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load.
-
-_Avoid_: ability, tool, capability
-
-### User-Invoked
-
-A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-_only_, where **model-invoked** is user-_and-agent_). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it.
-
-_Avoid_: procedure, workflow, command
-
-### Description
-
-The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**.
-
-_Avoid_: frontmatter, summary
-
-### Context Pointer
-
-A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches — and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
-
-_Avoid_: link, reference, import
-
-### Context Load
-
-The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills.
-
-_Avoid_: token cost, context bloat
-
-### Cognitive Load
-
-The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
-
-_Avoid_: human index, burden, overhead
-
-### Router Skill
-
-A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply.
-
-_Avoid_: dispatcher, menu, registry, index, router procedure
-
-### Granularity
-
-How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
-
-_Avoid_: chunking, modularity
-
-## Information Hierarchy
-
-How a skill's content is arranged, and how far down the ladder each piece sits.
-
-### Information Hierarchy
-
-A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
-
-- **Steps** — in-file, primary
-- **Reference**, in-file — secondary
-- **Reference**, disclosed — behind a **context pointer**
-
-A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
-
-_Avoid_: structure, organization, layout
-
-### Steps
-
-The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
-
-_Avoid_: workflow, instructions, choreography
-
-### Reference
-
-Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
-
-_Avoid_: supporting material, docs, background
-
-### External Reference
-
-**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other.
-
-_Avoid_: doc, resource, knowledge base
-
-### Progressive Disclosure
-
-Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
-
-_Avoid_: lazy loading, chunking
-
-### Co-location
-
-Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
-
-_Avoid_: grouping, clustering, cohesion
-
-### Sprawl
-
-_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
-
-_Avoid_: bloat, length, size, verbosity
-
-## Steering
-
-The levers that shape the agent's runtime behaviour toward **Predictability**.
-
-### Branch
-
-A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
-
-_Avoid_: path, case, fork
-
-### Leading Word
-
-A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
-
-A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
-
-_Avoid_: keyword, term, motif
-
-### Completion Criterion
-
-The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
-
-_Avoid_: done condition, exit condition, stopping rule
-
-### Legwork
-
-The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
-
-_Avoid_: scope, effort, diligence, coverage
-
-### Post-Completion Steps
-
-The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
-
-_Avoid_: horizon, fog of war, lookahead
-
-### Premature Completion
-
-_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
-
-_Avoid_: premature closure, the rush, rushing, shortcutting
-
-### Negation
-
-_Failure mode._ Steering by prohibition — telling the agent what _not_ to do — which drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; _never write verbose comments_, and verbosity is the pattern the agent has just read. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Its **leading word** is the _elephant_: whatever a prohibition names into the frame. Cure: prompt the **positive** — describe the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail on a behaviour you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
-
-_Avoid_: ironic rebound, don't-prompting, the pink elephant
-
-## Pruning
-
-Keeping a skill lean — each remedy paired with the failure it cures.
-
-### Single Source of Truth
-
-The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
-
-_Avoid_: home, canonical location
-
-### Duplication
-
-_Failure mode._ The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
-
-_Avoid_: repetition, redundancy
-
-### Relevance
-
-Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
-
-_Avoid_: load-bearing, staleness, freshness
-
-### Sediment
-
-_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
-
-_Avoid_: accretion, bloat, cruft, rot
-
-### No-Op
-
-_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
-
-A leading word is a _technique_; No-Op is a _verdict_ on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
-
-_Avoid_: redundant instruction, restating the obvious, belaboring

.agents/skills/writing-great-skills/SKILL.md

@@ -1,83 +0,0 @@
----
-name: writing-great-skills
-description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
-disable-model-invocation: true
----
-
-A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.
-
-**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.
-
-## Invocation
-
-Two choices, trading different costs:
-
-- A **model-invoked** skill keeps a **description**, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to **context load** — the description sits in the window every turn. Mechanics: omit `disable-model-invocation`, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
-- A **user-invoked** skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends **cognitive load**: _you_ are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped.
-
-Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
-
-When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each.
-
-## Writing the description
-
-A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body:
-
-- **Front-load the skill's leading word** — the description is where it does its invocation work.
-- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
-- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause.
-
-## Information hierarchy
-
-A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
-
-1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a **completion criterion**, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites **premature completion**.
-2. **In-skill reference** — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._
-3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully **external reference** that lives outside the skill system and any skill can point at.)
-
-A demanding completion criterion drives thorough **legwork** — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.
-
-Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
-
-**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material.
-
-Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it.
-
-## When to split
-
-**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts:
-
-- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to be worth it.
-- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view encourages the agent to do more **legwork** on the current task.
-
-## Pruning
-
-Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit.
-
-Check every line for **relevance**: does it still bear on what the skill does?
-
-Then hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten.
-
-## Leading words
-
-A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.
-
-It serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word appears. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably.
-
-Hunt for opportunities to refactor skills to use leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. Examples include:
-
-- "fast, deterministic, low-overhead" -> _tight_ — one quality restated across a phase — into a single pretrained word (a _tight_ loop).
-- "a loop you believe in" -> _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).
-
-You win twice over: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.
-
-## Failure modes
-
-Use these to diagnose issues the user may be having with the skill.
-
-- **Premature completion** — ending a step before it's genuinely done, attention slipping to _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut).
-- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.
-- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.
-- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs.
-- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.
-- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.

.agents/skills/writing-great-skills/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Writing Great Skills"
-  short_description: "Principles for predictable skills"
-policy:
-  allow_implicit_invocation: false

.agents/skills/zoom-out/SKILL.md

@@ -1,7 +0,0 @@
----
-name: zoom-out
-description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
-disable-model-invocation: true
----
-
-I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary.

.claude/settings.json

@@ -1,5 +0,0 @@
-{
-  "enabledPlugins": {
-    "ralph-loop@claude-plugins-official": true
-  }  
-}

.claude/skills/api-routing/SKILL.md

@@ -1,151 +0,0 @@
----
-name: api-routing
-description: API 路由注册规范。注册新 API 路由、添加新 Handler 时使用。包含 Register() 函数用法、RouteSpec 必填项、文档生成器更新等规范。
----
-
-# API 路由注册规范
-
-**所有 HTTP 接口必须使用统一的 `Register()` 函数注册，以自动加入 OpenAPI 文档生成。**
-
-## 触发条件
-
-在以下情况下必须遵守本规范：
-- 注册新的 API 路由
-- 修改现有路由配置
-- **添加新的 Handler（必须同步更新文档生成器！）**
-
-## 新增 Handler 检查清单（⚠️ 最容易遗漏）
-
-新增 Handler 时，必须完成以下 **4 个步骤**，否则接口不会出现在 OpenAPI 文档中：
-
-| 步骤 | 文件 | 操作 |
-|------|------|------|
-| 1️⃣ | `internal/bootstrap/types.go` | 添加 Handler 字段 |
-| 2️⃣ | `internal/bootstrap/handlers.go` | 实例化 Handler |
-| 3️⃣ | `internal/routes/admin.go` | 调用路由注册函数 |
-| 4️⃣ | `cmd/api/docs.go` + `cmd/gendocs/main.go` | **添加到文档生成器** |
-
-### 步骤 4 详解（最常遗漏！）
-
-```go
-// cmd/api/docs.go 和 cmd/gendocs/main.go 都要改！
-handlers := &bootstrap.Handlers{
-    // ... 现有 Handler
-    IotCard:       admin.NewIotCardHandler(nil),       // 添加
-    IotCardImport: admin.NewIotCardImportHandler(nil), // 添加
-}
-```
-
-## 核心规则
-
-### 必须使用 Register() 函数
-
-```go
-// ✅ 正确
-Register(router, doc, basePath, "POST", "/shops", handler.Create, RouteSpec{
-    Summary: "创建店铺",
-    Tags:    []string{"店铺管理"},
-    Input:   new(model.CreateShopRequest),
-    Output:  new(model.ShopResponse),
-    Auth:    true,
-})
-
-// ❌ 错误：直接注册不会生成文档
-router.Post("/shops", handler.Create)
-```
-
-## RouteSpec 必填项
-
-| 字段 | 类型 | 说明 | 示例 |
-|------|------|------|------|
-| `Summary` | string | 操作说明（中文，简短） | `"创建店铺"` |
-| `Tags` | []string | 分类标签（用于文档分组） | `[]string{"店铺管理"}` |
-| `Input` | interface{} | 请求 DTO（`nil` 表示无参数） | `new(model.CreateShopRequest)` |
-| `Output` | interface{} | 响应 DTO（`nil` 表示无返回） | `new(model.ShopResponse)` |
-| `Auth` | bool | 是否需要认证 | `true` |
-
-## 常见路由模式
-
-### CRUD 路由组
-
-```go
-// 列表查询
-Register(router, doc, basePath, "GET", "/shops", handler.List, RouteSpec{
-    Summary: "获取店铺列表",
-    Tags:    []string{"店铺管理"},
-    Input:   new(model.ListShopRequest),
-    Output:  new(model.ShopListResponse),
-    Auth:    true,
-})
-
-// 详情查询
-Register(router, doc, basePath, "GET", "/shops/:id", handler.Get, RouteSpec{
-    Summary: "获取店铺详情",
-    Tags:    []string{"店铺管理"},
-    Input:   new(model.IDReq),
-    Output:  new(model.ShopResponse),
-    Auth:    true,
-})
-
-// 创建
-Register(router, doc, basePath, "POST", "/shops", handler.Create, RouteSpec{
-    Summary: "创建店铺",
-    Tags:    []string{"店铺管理"},
-    Input:   new(model.CreateShopRequest),
-    Output:  new(model.ShopResponse),
-    Auth:    true,
-})
-
-// 更新
-Register(router, doc, basePath, "PUT", "/shops/:id", handler.Update, RouteSpec{
-    Summary: "更新店铺",
-    Tags:    []string{"店铺管理"},
-    Input:   new(model.UpdateShopRequest),
-    Output:  new(model.ShopResponse),
-    Auth:    true,
-})
-
-// 删除
-Register(router, doc, basePath, "DELETE", "/shops/:id", handler.Delete, RouteSpec{
-    Summary: "删除店铺",
-    Tags:    []string{"店铺管理"},
-    Input:   new(model.IDReq),
-    Output:  nil,
-    Auth:    true,
-})
-```
-
-### 无认证路由
-
-```go
-// 公开接口（如健康检查）
-Register(router, doc, basePath, "GET", "/health", handler.Health, RouteSpec{
-    Summary: "健康检查",
-    Tags:    []string{"系统"},
-    Input:   nil,
-    Output:  new(model.HealthResponse),
-    Auth:    false,
-})
-```
-
-## AI 助手检查清单
-
-### 注册路由时
-
-1. ✅ 是否使用 `Register()` 函数而非直接注册
-2. ✅ `Summary` 是否使用中文简短描述
-3. ✅ `Tags` 是否正确分组
-4. ✅ `Input` 和 `Output` 是否指向正确的 DTO
-5. ✅ `Auth` 是否根据业务需求正确设置
-
-### 新增 Handler 时（⚠️ 必查）
-
-1. ✅ `internal/bootstrap/types.go` 添加了 Handler 字段
-2. ✅ `internal/bootstrap/handlers.go` 实例化了 Handler
-3. ✅ `internal/routes/admin.go` 调用了路由注册函数
-4. ✅ **`cmd/api/docs.go` 添加了 Handler**
-5. ✅ **`cmd/gendocs/main.go` 添加了 Handler**
-6. ✅ 运行 `go run cmd/gendocs/main.go` 验证文档生成
-7. ✅ 运行 `grep "接口路径" docs/admin-openapi.yaml` 确认接口存在
-
-**完整指南**: 参见 [`docs/api-documentation-guide.md`](docs/api-documentation-guide.md)

.claude/skills/caveman

@@ -1 +0,0 @@
-../../.agents/skills/caveman

.claude/skills/comment-standards/SKILL.md

@@ -1,139 +0,0 @@
----
-name: comment-standards
-description: Go 注释规范。编写 Go 代码注释、文档注释时使用。包含包注释、结构体注释、接口注释、函数注释、内联注释的完整规范与示例。
----
-
-# Go 注释规范
-
-**基本原则**：
-- **所有注释使用中文**
-- **导出符号必须有文档注释**（包、函数、方法、类型、接口、常量、变量）
-- **复杂逻辑必须有实现注释**（解释"为什么"，而不是"做了什么"）
-- **禁止废话注释**（不要用注释复述代码本身）
-- **修改代码时必须同步更新注释**
-
----
-
-## 包注释
-
-每个包的入口文件（通常是主文件或 `doc.go`）必须有包注释：
-
-```go
-// Package account 提供账号管理的业务逻辑服务
-// 包含账号创建、修改、删除、权限分配等功能
-package account
-```
-
-## 结构体注释
-
-所有导出结构体必须有文档注释，说明该结构体代表什么：
-
-```go
-// Service 账号业务服务
-// 负责账号的 CRUD、角色分配、密码管理等业务逻辑
-type Service struct {
-    store        *Store
-    auditService AuditServiceInterface
-}
-```
-
-## 接口注释
-
-导出接口必须注释接口用途，每个方法必须说明契约：
-
-```go
-// PermissionChecker 权限检查器接口
-// 用于查询用户的权限列表
-type PermissionChecker interface {
-    // CheckPermission 检查用户是否拥有指定权限
-    // userID: 用户ID
-    // permCode: 权限编码（格式: module:action）
-    // platform: 端口类型 (all/web/h5)
-    CheckPermission(ctx context.Context, userID uint, permCode string, platform string) (bool, error)
-}
-```
-
-## 函数和方法注释
-
-**导出函数/方法**必须以函数名开头，说明功能：
-
-```go
-// Create 创建账号
-// POST /api/admin/accounts
-func (h *AccountHandler) Create(c *fiber.Ctx) error {
-```
-
-**复杂方法**（超过 30 行或包含复杂业务逻辑）必须额外说明实现思路：
-
-```go
-// ActivateByRealname 首次实名激活套餐
-// 当用户完成实名认证后，自动激活处于"囤货待实名"状态的套餐：
-// 1. 查找该卡所有 status=3（待实名激活）的套餐
-// 2. 按创建时间排序，第一个主套餐立即激活（status=1）
-// 3. 其余主套餐进入排队状态（status=4）
-// 4. 加油包如果绑定了已激活的主套餐则一并激活
-func (s *UsageService) ActivateByRealname(ctx context.Context, cardID uint) error {
-```
-
-**未导出函数/方法**：
-- 简单逻辑（< 15 行）：可以不加注释
-- 复杂逻辑（≥ 15 行）或非显而易见的算法：必须加注释
-
-```go
-// buildPermissionTree 递归构建权限树
-// 采用 map 索引 + 单次遍历算法，时间复杂度 O(n)
-func (s *Service) buildPermissionTree(permissions []*model.Permission) []*dto.PermissionTreeNode {
-```
-
-## 常量和枚举注释
-
-分组常量必须有组注释，每个值必须有行内注释：
-
-```go
-// 用户类型常量
-const (
-    UserTypeSuperAdmin = 1 // 超级管理员
-    UserTypePlatform   = 2 // 平台用户
-    UserTypeAgent      = 3 // 代理账号
-    UserTypeEnterprise = 4 // 企业账号
-)
-```
-
-## 内联注释规范
-
-**必须添加内联注释的场景**：
-
-| 场景 | 要求 |
-|------|------|
-| 复杂条件判断 | 解释判断的业务含义 |
-| 多步骤业务流程 | 用编号注释标明每一步 |
-| 非显而易见的设计决策 | 解释"为什么这样做"而不是"做了什么" |
-| 缓存/事务/并发处理 | 说明策略和原因 |
-| 临时方案/兼容逻辑 | 标注 TODO 或说明背景 |
-
-**✅ 好的内联注释（解释为什么）**：
-
-```go
-// 使用 Redis 分布式锁防止并发重复创建，锁超时 10 秒
-if !s.acquireLock(ctx, lockKey, 10*time.Second) {
-    return errors.New(errors.CodeTooManyRequests, "操作过于频繁，请稍后重试")
-}
-
-// 先冻结佣金再扣款，保证资金安全（失败时佣金自动解冻）
-if err := s.freezeCommission(ctx, tx, orderID); err != nil {
-    return err
-}
-```
-
-**❌ 废话注释（禁止）**：
-
-```go
-// 获取用户ID          ← 禁止：代码本身已经很清楚
-userID := middleware.GetUserIDFromContext(ctx)
-
-// 创建账号            ← 禁止：变量名已说明意图
-account := &model.Account{}
-
-// 返回错误            ← 禁止：return err 不需要注释
-return err
-```

.claude/skills/db-migration/SKILL.md

@@ -1,212 +0,0 @@
----
-name: db-migration
-description: 数据库迁移规范。创建迁移、修改数据库结构、执行 migrate 命令时使用。包含迁移工具、文件规范、执行流程、失败处理等完整指南。
----
-
-# 数据库迁移规范
-
-**项目使用 golang-migrate 进行数据库迁移管理。**
-
-## 触发条件
-
-在以下情况下必须遵守本规范：
-- 创建新的数据库迁移
-- 修改数据库表结构
-- 执行 `make migrate-*` 命令
-- 处理迁移失败问题
-
-## 基本命令
-
-```bash
-# 查看当前迁移版本
-make migrate-version
-
-# 执行所有待迁移
-make migrate-up
-
-# 回滚上一次迁移
-make migrate-down
-
-# 创建新迁移文件
-make migrate-create
-# 然后输入迁移名称，例如: add_user_email
-```
-
-## 迁移文件规范
-
-### 文件位置和命名
-
-迁移文件位于 `migrations/` 目录：
-
-```
-migrations/
-├── 000001_initial_schema.up.sql
-├── 000001_initial_schema.down.sql
-├── 000002_add_user_email.up.sql
-├── 000002_add_user_email.down.sql
-```
-
-**命名规范**:
-- 格式: `{序号}_{描述}.{up|down}.sql`
-- 序号: 6位数字，从 000001 开始
-- 描述: 小写英文，用下划线分隔
-- up: 应用迁移（向前）
-- down: 回滚迁移（向后）
-
-### 编写规范
-
-```sql
--- up.sql 示例
--- 添加字段时必须考虑向后兼容
-ALTER TABLE tb_users 
-ADD COLUMN email VARCHAR(100);
-
--- 添加注释
-COMMENT ON COLUMN tb_users.email IS '用户邮箱';
-
--- 为现有数据设置默认值（如果需要）
-UPDATE tb_users SET email = '' WHERE email IS NULL;
-
--- down.sql 示例
-ALTER TABLE tb_users 
-DROP COLUMN IF EXISTS email;
-```
-
-## 迁移执行流程（必须遵守）
-
-当你创建迁移文件后，**必须**执行以下验证步骤：
-
-### 1. 执行迁移
-
-```bash
-make migrate-up
-```
-
-### 2. 验证迁移状态
-
-```bash
-make migrate-version
-# 确认版本号已更新且 dirty=false
-```
-
-### 3. 验证数据库结构
-
-使用 PostgreSQL MCP 工具检查：
-- 字段是否正确创建
-- 类型是否符合预期
-- 默认值是否正确
-- 注释是否存在
-
-```
-PostgresGetObjectDetails:
-- schema_name: "public"
-- object_name: "tb_users"
-- object_type: "table"
-```
-
-### 4. 验证查询功能
-
-编写临时脚本测试新字段的查询功能
-
-### 5. 更新 Model
-
-在 `internal/model/` 中添加对应字段
-
-### 6. 清理测试数据
-
-如果插入了测试数据，记得清理
-
-## 迁移失败处理
-
-如果迁移执行失败，数据库会被标记为 dirty 状态：
-
-```bash
-# 1. 检查错误原因
-make migrate-version
-# 如果显示 dirty=true，说明迁移失败
-
-# 2. 手动修复数据库状态
-# 使用 PostgreSQL MCP 连接数据库
-# 检查失败的迁移是否部分执行
-# 手动清理或完成迁移
-
-# 3. 清除 dirty 标记
-UPDATE schema_migrations SET dirty = false WHERE version = {失败的版本号};
-
-# 4. 修复迁移文件中的错误
-
-# 5. 重新执行迁移
-make migrate-up
-```
-
-## 迁移最佳实践
-
-### 1. 向后兼容
-
-- 添加字段时使用 `DEFAULT` 或允许 NULL
-- 删除字段前确保代码已不再使用
-- 修改字段类型要考虑数据转换
-
-### 2. 原子性
-
-- 每个迁移文件只做一件事
-- 复杂变更拆分成多个迁移
-
-### 3. 可回滚
-
-- down.sql 必须能完整回滚 up.sql 的所有变更
-- 测试回滚功能: `make migrate-down && make migrate-up`
-
-### 4. 注释完整
-
-- 迁移文件顶部说明变更原因
-- 关键 SQL 添加行内注释
-- 数据库字段使用 COMMENT 添加说明
-
-### 5. 测试数据
-
-- 不要在迁移文件中插入业务数据
-- 可以插入配置数据或枚举值
-- 测试数据用临时脚本处理
-
-## PostgreSQL MCP 工具使用
-
-### 查看表结构
-
-```
-PostgresGetObjectDetails: 
-- schema_name: "public"
-- object_name: "tb_permission"
-- object_type: "table"
-```
-
-### 列出所有表
-
-```
-PostgresListObjects:
-- schema_name: "public"
-- object_type: "table"
-```
-
-### 执行查询
-
-```
-PostgresExecuteSql:
-- sql: "SELECT * FROM tb_permission LIMIT 5"
-```
-
-## 注意事项
-
-- ⚠️ MCP 工具只支持只读查询（SELECT）
-- ⚠️ 不要直接修改数据，修改必须通过迁移文件
-- ⚠️ 测试数据可以通过临时 Go 脚本插入
-
-## AI 助手检查清单
-
-创建迁移后必须：
-
-1. ✅ 执行 `make migrate-up`
-2. ✅ 执行 `make migrate-version` 确认成功
-3. ✅ 使用 PostgresGetObjectDetails 验证表结构
-4. ✅ 在 `internal/model/` 中更新对应 Model
-5. ✅ 测试回滚：`make migrate-down && make migrate-up`

.claude/skills/db-validation/SKILL.md

@@ -1,151 +0,0 @@
----
-name: db-validation
-description: 数据库验证规范。测试 API 接口、验证业务逻辑、调试数据问题时使用。包含 PostgreSQL MCP 工具使用方法和验证示例。
----
-
-# 数据库验证规范
-
-**AI 在测试接口或验证业务逻辑时，必须使用 PostgreSQL MCP 工具直接查询数据库验证数据的正确性。**
-
-## 触发条件
-
-在以下情况下必须遵守本规范：
-- 测试 API 接口后验证数据
-- 检查数据库表结构
-- 验证数据库迁移结果
-- 调试业务逻辑
-- 验证事务处理
-- 检查数据权限过滤
-
-## 何时使用 PostgreSQL MCP
-
-### ✅ 必须使用的场景
-
-- 测试 API 接口后验证数据是否正确写入数据库
-- 检查数据库表结构是否符合 Model 定义
-- 验证数据库迁移是否成功执行
-- 调试业务逻辑时查看实际数据状态
-- 验证事务是否正确提交或回滚
-- 检查数据权限过滤是否生效
-
-### ❌ 不要
-
-- 仅依赖 API 响应判断数据是否正确（响应可能只是内存中的临时数据）
-- 通过日志推测数据库状态
-- 假设代码逻辑正确就认为数据正确
-
-## 可用的 PostgreSQL MCP 工具
-
-```
-1. PostgresListSchemas - 列出所有数据库模式
-2. PostgresListObjects - 列出指定模式下的表/视图/序列
-3. PostgresGetObjectDetails - 查看表结构详情（字段、类型、约束、注释）
-4. PostgresExecuteSql - 执行只读 SQL 查询（SELECT）
-```
-
-## 验证示例
-
-### 场景 1：测试创建用户接口
-
-```
-1. 调用 POST /api/v1/accounts 创建用户
-   → 响应：{"code":0, "data":{"id":123, "username":"testuser"}}
-
-2. ✅ 使用 PostgreSQL MCP 验证数据库
-   PostgresExecuteSql:
-   - sql: "SELECT id, username, user_type, status, created_at FROM tb_account WHERE id = 123"
-   
-3. 检查查询结果：
-   ✅ 用户确实已创建
-   ✅ 字段值与请求参数一致
-   ✅ status = 1（启用）
-   ✅ created_at 有值
-```
-
-### 场景 2：测试数据权限过滤
-
-```
-1. 以代理用户登录，查询店铺列表
-   → 响应：返回 5 个店铺
-
-2. ✅ 使用 PostgreSQL MCP 验证过滤逻辑
-   PostgresExecuteSql:
-   - sql: "SELECT id, shop_name, parent_id FROM tb_shop WHERE deleted_at IS NULL"
-   
-3. 检查：
-   ✅ 数据库实际有 10 个店铺
-   ✅ API 只返回了当前用户及下级的 5 个店铺
-   ✅ 数据权限过滤生效
-```
-
-### 场景 3：验证迁移执行
-
-```
-1. 执行迁移：make migrate-up
-
-2. ✅ 验证表结构
-   PostgresGetObjectDetails:
-   - schema_name: "public"
-   - object_name: "tb_account"
-   - object_type: "table"
-   
-3. 检查：
-   ✅ 新字段 enterprise_id 已添加
-   ✅ 类型为 bigint
-   ✅ 允许 NULL
-   ✅ 注释为"企业ID"
-```
-
-## 工具使用方法
-
-### 查看表结构
-
-```
-PostgresGetObjectDetails: 
-- schema_name: "public"
-- object_name: "tb_permission"
-- object_type: "table"
-```
-
-### 列出所有表
-
-```
-PostgresListObjects:
-- schema_name: "public"
-- object_type: "table"
-```
-
-### 执行查询
-
-```
-PostgresExecuteSql:
-- sql: "SELECT * FROM tb_permission LIMIT 5"
-```
-
-## 注意事项
-
-### ⚠️ 限制
-
-- PostgreSQL MCP 只支持只读查询（SELECT），不能执行 INSERT/UPDATE/DELETE
-- 如需插入测试数据，使用 Go 脚本或迁移文件
-
-### ⚠️ 安全
-
-- 避免在查询中暴露敏感数据（如密码哈希）
-- 生产环境使用时需谨慎，避免查询大量数据
-
-### ✅ 最佳实践
-
-- 每次 API 测试后都验证数据库状态
-- 使用 LIMIT 限制查询结果数量（如 `LIMIT 10`）
-- 验证完成后清理测试数据
-
-## AI 助手检查清单
-
-测试接口后必须：
-
-1. ✅ 使用 PostgresExecuteSql 查询相关数据
-2. ✅ 验证数据是否正确写入
-3. ✅ 验证字段值是否符合预期
-4. ✅ 验证关联数据是否正确
-5. ✅ 如有数据权限，验证过滤是否生效

.claude/skills/diagnose

@@ -1 +0,0 @@
-../../.agents/skills/diagnose

.claude/skills/doc-management/SKILL.md

@@ -1,141 +0,0 @@
----
-name: doc-management
-description: 规范文档管理。添加新规范、更新规范文档、维护 AGENTS.md 时使用。包含规范文档流程和维护规则。
----
-
-# 规范文档管理
-
-**当你需要为项目添加新的开发规范时，必须遵循以下流程。**
-
-## 触发条件
-
-在以下情况下必须遵守本规范：
-- 添加新的开发规范
-- 更新现有规范文档
-- 维护 AGENTS.md 文件
-- 创建技术指南文档
-
-## 添加新规范的流程
-
-### 步骤 1：创建详细规范文档
-
-在 `docs/` 目录下创建详细的规范文档（Markdown 格式）：
-
-```
-docs/
-├── api-documentation-guide.md    # API 文档生成规范
-├── code-review-checklist.md      # 代码审查清单
-├── testing-guide.md               # 测试规范
-└── ...
-```
-
-**文档内容要求**：
-- ✅ 包含完整的规范说明、示例代码、常见问题
-- ✅ 使用中文编写，代码示例使用英文
-- ✅ 提供正确示例（✅）和错误示例（❌）的对比
-- ✅ 包含故障排查和调试指南
-
-### 步骤 2：在 AGENTS.md 中添加简短引导
-
-在 `AGENTS.md` 的相关章节中添加**简短**的规范说明 + 引导链接：
-
-```markdown
-## XXX 规范
-
-**核心要求：一句话说明最重要的规则。**
-
-```go
-// ✅ 正确示例（3-5 行）
-...
-
-// ❌ 错误示例（3-5 行）
-...
-```
-
-**关键要点**：
-- 规则 1
-- 规则 2
-- 规则 3
-
-**完整指南**: 参见 [`docs/xxx-guide.md`](docs/xxx-guide.md)
-```
-
-**注意**：
-- ⚠️ AGENTS.md 中的说明不超过 20 行
-- ⚠️ 只保留最核心的规则和示例
-- ⚠️ 必须包含引导链接到详细文档
-
-### 步骤 3：在 README.md 中添加文档链接
-
-在 `README.md` 的"## 文档"章节中添加链接：
-
-```markdown
-## 文档
-
-### 开发规范
-
-- **[API 文档生成规范](docs/api-documentation-guide.md)**：路由注册规范、DTO 规范、OpenAPI 文档生成流程
-- **[XXX 规范](docs/xxx-guide.md)**：简短的一句话说明
-```
-
-**分类规则**：
-- 开发规范：代码规范、API 规范、测试规范
-- 功能指南：功能使用指南、配置指南
-- 架构设计：设计文档、技术选型
-
-## 规范文档的维护
-
-### 更新规范时
-
-1. 优先更新 `docs/` 下的详细文档
-2. 如果核心规则变化，同步更新 AGENTS.md 中的简短说明
-3. 保持 AGENTS.md 简洁，避免冗余
-
-### 删除规范时
-
-1. 删除 `docs/` 下的详细文档
-2. 删除 AGENTS.md 中的相关章节
-3. 删除 README.md 中的链接
-4. 说明删除原因（在 commit message 中）
-
-## Skill 规范管理
-
-### 何时创建 Skill
-
-当规范内容满足以下条件时，应该提取为 Skill：
-- 内容超过 50 行
-- 只在特定任务场景需要
-- 包含详细的步骤和示例
-
-### Skill 文件结构
-
-```
-.claude/skills/{skill-name}/
-└── SKILL.md
-```
-
-### Skill 命名规范
-
-- 使用小写字母和连字符
-- 名称应描述规范主题
-- 示例：`dto-standards`、`db-migration`、`api-routing`
-
-### Skill Frontmatter
-
-```yaml
----
-name: skill-name
-description: 简短描述（1-2 句话），说明何时使用此 skill
----
-```
-
-## AI 助手检查清单
-
-添加/更新规范后必须：
-
-1. ✅ 详细文档在 `docs/` 目录
-2. ✅ AGENTS.md 中有简短引导（≤20 行）
-3. ✅ README.md 中有文档链接
-4. ✅ 如果内容 >50 行，考虑提取为 Skill
-5. ✅ Skill 的 name 与目录名一致
-6. ✅ Skill 的 description 清晰描述触发条件

.claude/skills/dto-standards/SKILL.md

@@ -1,246 +0,0 @@
----
-name: dto-standards
-description: DTO 数据传输对象规范。创建或修改 DTO 文件、请求/响应结构时使用。包含 description 标签、枚举字段、验证标签等规范。
----
-
-# DTO 规范
-
-**所有 DTO 文件必须遵循以下规范，这是 API 文档生成的基础。**
-
-## 触发条件
-
-在以下情况下必须遵守本规范：
-- 创建或修改 `internal/model/` 下的请求/响应 DTO
-- 创建 `XXXRequest`、`XXXResponse`、`XXXReq`、`XXXResp` 结构体
-- 添加或修改 API 接口的输入输出参数
-
----
-
-## 必须项（MUST）
-
-### 1. Description 标签规范
-
-**所有字段必须使用 `description` 标签，禁止使用行内注释**
-
-❌ **错误**：
-```go
-type CreateUserRequest struct {
-    Username string `json:"username"` // 用户名
-    Status   int    `json:"status"`   // 状态
-}
-```
-
-✅ **正确**：
-```go
-type CreateUserRequest struct {
-    Username string `json:"username" description:"用户名"`
-    Status   int    `json:"status" description:"状态 (0:禁用, 1:启用)"`
-}
-```
-
-### 2. 枚举字段：int vs string 选择
-
-**必须按以下规则选择类型，禁止混用：**
-
-| 场景 | 类型 | 示例 |
-|------|------|------|
-| 状态类（生命周期阶段） | `int` | 待支付→已完成→已关闭 |
-| 布尔状态（启用/禁用） | `int` | `0=禁用, 1=启用` |
-| 类型/方式类（种类） | `string` | `"wechat"`, `"single_card"` |
-| 平台/标识符类 | `string` | `"web"`, `"h5"`, `"all"` |
-
-```go
-// ✅ 状态 → int
-Status        int    `json:"status"`
-PaymentStatus int    `json:"payment_status"`
-
-// ✅ 类型/方式 → string
-PaymentMethod string `json:"payment_method" validate:"required,oneof=wechat offline"`
-OrderType     string `json:"order_type"     validate:"required,oneof=single_card device"`
-```
-
-### 3. Int 状态值约定
-
-#### 3.1 通用禁用/启用
-
-**必须用全局常量，禁止自定义（尤其禁止 1=启用 2=禁用 这种反向写法）**：
-
-```go
-// pkg/constants/constants.go 已定义，直接使用
-StatusDisabled = 0 // 禁用
-StatusEnabled  = 1 // 启用
-```
-
-✅ 正确：`description:"状态 (0:禁用, 1:启用)"`
-❌ 禁止：`description:"状态 (1:启用, 2:禁用)"`
-
-#### 3.2 生命周期状态
-
-从 **1** 开始递增，0 不使用（避免与 Go 零值混淆）：
-
-```go
-const (
-    RechargeStatusPending   = 1 // 待支付
-    RechargeStatusPaid      = 2 // 已支付
-    RechargeStatusCompleted = 3 // 已完成
-    RechargeStatusClosed    = 4 // 已关闭
-)
-```
-
-### 4. 枚举列表必须从 constants 原文抄写
-
-**DTO description 的枚举列表必须与 `pkg/constants/` 定义完全一致，不可凭记忆填写。**
-
-操作步骤：
-1. 先查/定义 `pkg/constants/` 中的枚举常量
-2. 将常量注释**原文抄写**到 description
-
-```go
-// constants.go 中：
-RechargeStatusPending   = 1 // 待支付
-RechargeStatusPaid      = 2 // 已支付
-RechargeStatusCompleted = 3 // 已完成
-RechargeStatusClosed    = 4 // 已关闭
-RechargeStatusRefunded  = 5 // 已退款
-
-// DTO description 从上面抄：
-Status int `json:"status" description:"状态 (1:待支付, 2:已支付, 3:已完成, 4:已关闭, 5:已退款)"`
-```
-
-❌ 禁止（description 与 constants 不一致，是历史 bug 的根因）：
-```go
-// constants 说 3=已完成，description 却写 3:已取消
-Status int `json:"status" description:"状态 (1:待支付, 2:已完成, 3:已取消)"`
-```
-
-### 5. description 格式标准
-
-**统一格式**：`字段含义 (值1:中文含义1, 值2:中文含义2)`
-
-- 值与含义之间用**冒号** `:`（禁止用等号 `=`）
-- 多个值之间用**逗号加空格** `, `
-- 含义必须是**中文**
-
-```go
-// ✅ 统一格式
-Status       int    `description:"状态 (1:待支付, 2:已支付, 3:已完成)"`
-Platform     string `description:"适用端口 (all:全部, web:Web后台, h5:H5端)"`
-
-// ❌ 格式混乱
-Status int `description:"状态 (0=禁用, 1=启用)"`     // 用等号
-Status int `description:"0=禁用 1=启用"`             // 无括号无逗号
-```
-
-### 6. Response DTO 的状态字段必须同时返回 int 和 text
-
-**所有 Response DTO 中的 int 状态字段，必须同时提供对应的 `_name` 文字字段。**
-
-原因：防止前端维护映射表出错（历史上已有因此产生 bug 的案例）。
-
-```go
-// ✅ Response DTO 标准写法
-type XxxResponse struct {
-    Status     int    `json:"status"      description:"状态 (1:待支付, 2:已支付, 3:已完成, 4:已关闭, 5:已退款)"`
-    StatusName string `json:"status_name" description:"状态名称（中文）"`
-}
-
-// toResponse 函数中赋值
-func rechargeStatusName(status int) string {
-    switch status {
-    case constants.RechargeStatusPending:
-        return "待支付"
-    case constants.RechargeStatusCompleted:
-        return "已完成"
-    // ...
-    default:
-        return "未知"
-    }
-}
-```
-
-字段命名约定：`status` → `status_name`，`payment_status` → `payment_status_name`
-
-**例外**：Request DTO（查询过滤、创建请求）不需要 `_name` 字段。
-
-### 7. 验证标签与 OpenAPI 标签一致
-
-```go
-Username string `json:"username" validate:"required,min=3,max=50" required:"true" minLength:"3" maxLength:"50" description:"用户名"`
-```
-
-| validate 标签 | OpenAPI 标签 |
-|--------------|--------------|
-| `required` | `required:"true"` |
-| `min=N,max=M`（数值） | `minimum:"N" maximum:"M"` |
-| `min=N,max=M`（字符串） | `minLength:"N" maxLength:"M"` |
-| `oneof=A B C` | description 中说明枚举值 |
-
-### 8. 请求参数类型标签
-
-```go
-// Query 参数
-type ListRequest struct {
-    Page   int  `json:"page"  query:"page"  validate:"omitempty,min=1" minimum:"1" description:"页码"`
-    Status *int `json:"status" query:"status" validate:"omitempty,min=1,max=4" minimum:"1" maximum:"4" description:"状态 (1:待支付, 2:已支付, 3:已完成, 4:已关闭)"`
-}
-
-// Path 参数
-type IDReq struct {
-    ID uint `path:"id" description:"ID" required:"true"`
-}
-```
-
-### 9. 响应 DTO 完整性
-
-```go
-type AccountResponse struct {
-    ID         uint   `json:"id"          description:"账号ID"`
-    Username   string `json:"username"    description:"用户名"`
-    UserType   int    `json:"user_type"   description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"`
-    Status     int    `json:"status"      description:"状态 (0:禁用, 1:启用)"`
-    StatusName string `json:"status_name" description:"状态名称（中文）"`
-    CreatedAt  string `json:"created_at"  description:"创建时间"`
-    UpdatedAt  string `json:"updated_at"  description:"更新时间"`
-}
-```
-
----
-
-## AI 助手必须执行的检查
-
-**在创建或修改任何 DTO 文件后，必须执行以下检查：**
-
-1. ✅ 所有字段有 `description` 标签（无行内注释）
-2. ✅ 枚举类型选择正确（状态用 int，类型/方式用 string）
-3. ✅ 禁用/启用使用 `0=禁用, 1=启用`（禁止 1=启用 2=禁用）
-4. ✅ description 枚举列表已从 `pkg/constants/` 原文抄写，无遗漏
-5. ✅ description 格式统一（冒号 `:`，括号，逗号）
-6. ✅ Response DTO 有 `_name` 伴生字段
-7. ✅ validate 标签与 OpenAPI 标签一致
-8. ✅ 重新生成 OpenAPI 文档验证：`go run cmd/gendocs/main.go`
-
-**完整枚举规范**: 参见 [`docs/enum-status-standards.md`](../../docs/enum-status-standards.md)
-
----
-
-## 常见枚举字段标准值
-
-```go
-// 用户类型（从 constants.UserType* 抄）
-description:"用户类型 (1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号)"
-
-// 通用启用/禁用（从 constants.StatusEnabled/Disabled 抄）
-description:"状态 (0:禁用, 1:启用)"
-
-// 充值状态（从 constants.RechargeStatus* 抄）
-description:"状态 (1:待支付, 2:已支付, 3:已完成, 4:已关闭, 5:已退款)"
-
-// 权限类型
-description:"权限类型 (1:菜单, 2:按钮)"
-
-// 适用端口
-description:"适用端口 (all:全部, web:Web后台, h5:H5端)"
-
-// 店铺层级
-description:"店铺层级 (1-7级)"
-```

.claude/skills/hurl-test/SKILL.md

@@ -1,777 +0,0 @@
----
-name: hurl-test
-description: Hurl 接口测试生成器。用户描述要测试的接口或业务流程，自动探索代码、确认需求、生成完整的 .hurl 测试文件（含 DTO 驱动的字段完整性断言）。触发词：测试、hurl、写测试、接口测试。
----
-
-# Hurl 接口测试生成器
-
-**用户描述要测试什么，你来读代码、问确认、生成 .hurl 文件。**
-
-适用于任何后端项目（Go / Python / Node / Java 等），不预设框架和目录结构。
-
----
-
-## 触发条件
-
-以下情况必须使用本 Skill：
-- 用户说"测试 XX 接口"、"写 hurl 测试"、"给 XX 加测试"
-- 用户说"测试 XX 流程"、"测试 XX 的业务逻辑"
-- 用户说"验证 XX 接口的字段"、"测试接口契约"
-- 用户提到 hurl、.hurl、接口测试、集成测试、冒烟测试
-
----
-
-## 四阶段工作流（必须按顺序执行）
-
-```
-Phase 1: 探索  →  Phase 2: 确认  →  Phase 3: 生成  →  Phase 4: 验证
-读代码搞清楚      展示给用户确认      输出 .hurl 文件     语法检查 + 试跑
-```
-
----
-
-### Phase 1: 探索（Explore）
-
-**目标：读代码，搞清楚项目约定 + 涉及的接口 + 字段 + 依赖。**
-
-#### 1.1 项目画像（首次使用时必须执行，后续复用）
-
-首次为项目生成 Hurl 测试时，先回答以下问题（通过读代码，不要猜）：
-
-| 问题 | 怎么找 |
-|------|--------|
-| **语言/框架** | 看 go.mod / package.json / requirements.txt / pom.xml |
-| **路由注册在哪** | 搜索 `router`、`app.Get`、`@GetMapping`、`@app.route` 等关键词 |
-| **请求/响应 schema 定义在哪** | 搜索 DTO / schema / serializer / model 目录，看 json tag 或装饰器 |
-| **统一响应格式是什么** | 找 response helper 文件（如 `response.go`、`response.py`），记录 JSON 结构 |
-| **认证方式是什么** | 找 auth middleware，确定是 Bearer Token / Cookie / API Key / Basic Auth |
-| **登录接口是什么** | 找登录 handler，记录路径、请求体、响应中 token 的位置 |
-| **分页格式是什么** | 找列表接口的响应结构，记录 items/total/page 等字段名 |
-| **已有 hurl 测试吗** | 搜索 `*.hurl` 文件，复用已有的约定 |
-
-将画像结果**写入 `tests/hurl/.project-profile.md` 文件持久化保存**。
-
-#### 画像持久化（关键机制）
-
-**首次使用时**：完成 1.1 探索后，将画像写入 `tests/hurl/.project-profile.md`，格式如下：
-
-```markdown
-# 项目画像（Hurl 测试自动生成用）
-<!-- 由 hurl-test skill 自动生成，请勿手动修改 -->
-<!-- 如需刷新，删除此文件后重新运行 skill -->
-
-## 技术栈
-- 语言: Go 1.25
-- 框架: Fiber v2
-- ORM: GORM
-
-## 路由定义位置
-- 路由注册入口: internal/routes/routes.go
-- 按模块拆分: internal/routes/{module}.go
-- 路由注册函数: Register(router, doc, basePath, method, path, handler, spec)
-
-## Schema 定义位置
-- DTO 目录: internal/model/dto/
-- 命名规则: {module}_dto.go
-- 字段标签: json / validate / description
-
-## 统一响应格式
-{code: int, msg: string, data: any, timestamp: string(RFC3339)}
-- 成功: code=0, msg="success"
-- 错误: code!=0
-
-## 分页格式
-{items: [], total: int, page: int, size: int}
-- 包裹在 data 字段内: $.data.items / $.data.total
-
-## 认证方式
-- 后台: POST /api/auth/admin-login → $.data.access_token → Authorization: Bearer {token}
-- C端: JWT → Authorization: Bearer {token}
-
-## 默认测试账号
-- 用户名: admin
-- 密码: Admin@123456
-
-## 服务端口
-- 默认: 3000
-```
-
-**后续使用时**：检查 `tests/hurl/.project-profile.md` 是否存在：
-- **存在** → 直接读取，跳过 1.1 的探索步骤，节省时间
-- **不存在** → 执行 1.1 完整探索，然后生成此文件
-- **用户说"刷新画像"** → 删除旧文件，重新执行 1.1
-
-#### 1.2 找接口定义
-
-根据用户要测的模块，定位路由注册代码，提取：
-
-- **HTTP 方法**（GET / POST / PUT / DELETE / PATCH）
-- **路由路径**（含路径参数格式，如 `/users/:id` 或 `/users/{id}`）
-- **接口说明**（注释、Summary、装饰器描述）
-- **是否需要认证**
-- **请求 schema 类型名**（Input / Request DTO）
-- **响应 schema 类型名**（Output / Response DTO）
-
-#### 1.3 读 schema 定义（DTO / struct / class / type）
-
-定位请求和响应的 schema 定义文件，提取每个字段的：
-
-- **字段名**：JSON 序列化后的名称（json tag / @JsonProperty / serializer field）
-- **语言类型**：string / int / bool / 数组 / 嵌套对象 / 可空等
-- **是否必填**：validate tag / required 装饰器 / 非空标注
-- **是否可空**：指针类型 / Optional / nullable
-- **是否参与序列化**：`json:"-"` / @JsonIgnore / exclude
-- **是否 omitempty**：`json:",omitempty"` / 条件序列化
-- **字段描述**：description tag / docstring / 注释
-
-#### 1.4 识别业务依赖
-
-读 service / business logic 层，识别：
-
-- 创建操作需要哪些前置数据（如创建订单需要先有商品和用户）
-- 是否有唯一性约束（如用户名不能重复）
-- 是否依赖外部服务（支付网关、短信、OAuth 等）
-- 业务流转逻辑（状态机、级联操作）
-
----
-
-### Phase 2: 确认（Clarify）
-
-**目标：向用户展示发现的内容，确认模糊点。不要闷头生成。**
-
-#### 2.1 必须展示的内容
-
-```
-我梳理了相关代码，发现以下信息：
-
-📋 涉及接口：
-  - [方法] [路径] - [说明]（认证: 是/否）
-  - ...
-
-📦 响应字段（基于 {SchemaName}）：
-  - [字段名]: [类型] - [说明]
-  - ...（共 N 个字段，将全部生成断言）
-
-🔗 依赖关系：
-  - [创建 X 需要先创建 Y]
-  - ...
-
-⚠️ 特殊情况：
-  - [涉及外部服务 / 文件上传 / 特殊认证等]
-```
-
-#### 2.2 按需确认（只问有歧义的）
-
-| 场景 | 要问的 |
-|------|--------|
-| 流程范围不明确 | "要测到哪一步？" |
-| 多种用户角色 | "用哪种身份测？" |
-| 是否测异常 | "需要包含异常 case 吗？（参数校验失败、权限不足等）" |
-| 是否测数据隔离 | "需要验证不同用户间数据不可见吗？" |
-| 涉及第三方 | "XX 部分怎么处理？绕过 / 模拟回调 / 跳过？" |
-| 前置数据来源 | "XX 依赖数据是通过 API 创建还是假设已存在？" |
-
-**如果用户说"越完整越好"或"都要"→ 默认全部包含，不再追问。**
-
----
-
-### Phase 3: 生成（Generate）
-
-**目标：生成完整的 .hurl 文件，字段断言基于 schema 代码，不能编造。**
-
-#### 3.1 文件头注释
-
-```hurl
-# ============================================================
-# 测试：{测试名称}
-# 生成时间：{日期}
-# 涉及模块：{module1, module2, ...}
-# 涉及接口：{N} 个
-# 断言数量：{N} 条
-# 前置条件：{服务运行 + 必要的前置条件}
-# ============================================================
-# 流程：
-#   1. {步骤描述}
-#   2. {步骤描述}
-#   ...
-# ============================================================
-```
-
-#### 3.2 请求生成规则
-
-**认证**：
-
-- 根据 Phase 1 画像中的登录接口和 token 位置生成
-- token 必须通过 `[Captures]` 捕获，后续请求引用
-- 如果是 Cookie 认证，用 `[Cookies]` 或 cookie capture
-
-**CRUD 标准模式**：
-
-| 操作 | 生成要求 |
-|------|---------|
-| **创建（POST）** | capture 返回的 ID；唯一字段用 `{{newUuid}}` 防冲突 |
-| **查询详情（GET）** | **逐字段断言**（类型 + 值，见 3.3） |
-| **查询列表（GET）** | 分页结构断言 + items[0] 逐字段断言 |
-| **修改（PUT/PATCH）** | 修改后**紧跟一个 GET 验证修改生效** |
-| **删除（DELETE）** | 删除后**紧跟一个 GET 验证已删除** |
-
-**业务流程模式**：
-
-- 按用户描述的流程顺序编排请求
-- 上一步的输出（ID、状态等）通过 `[Captures]` 传给下一步
-- 关键步骤加中间状态验证（如创建订单后验证状态为"待支付"）
-
-#### 3.3 schema 到断言的映射
-
-读到 schema 字段后，按以下规则生成 jsonpath 断言：
-
-**通用类型映射（所有语言）**：
-
-| Schema 类型特征 | Hurl 断言 |
-|----------------|-----------|
-| 字符串（string / str / String） | `isString` |
-| 整数（int / integer / long / Int） | `isInteger` |
-| 浮点（float / double / decimal / Float） | `isNumber` |
-| 布尔（bool / boolean / Boolean） | `isBoolean` |
-| 数组 / 列表（[] / List / Array） | `isList` |
-| 嵌套对象（struct / class / dict / object） | `isObject`，并递归检查子字段 |
-| 可空类型（指针 / Optional / nullable） | `exists`（不强制类型，因为可能是 null） |
-| 不参与序列化（json:"-" / @JsonIgnore / exclude=True） | **跳过，不生成断言** |
-| 条件序列化（omitempty / if not None） | `exists` 或不生成（取决于场景） |
-
-**Go 特定映射**：
-
-| Go 类型 | Hurl 断言 |
-|---------|-----------|
-| `string` | `isString` |
-| `int`, `int8/16/32/64`, `uint`, `uint8/16/32/64` | `isInteger` |
-| `float32`, `float64` | `isNumber` |
-| `bool` | `isBoolean` |
-| `[]T` | `isList` |
-| `*string`, `*int`, `*uint` 等指针 | `exists` |
-| `time.Time` | `isString`（通常序列化为字符串） |
-| `map[string]any` | `isObject` |
-
-**Python 特定映射（Pydantic / Django / FastAPI）**：
-
-| Python 类型 | Hurl 断言 |
-|------------|-----------|
-| `str` | `isString` |
-| `int` | `isInteger` |
-| `float`, `Decimal` | `isNumber` |
-| `bool` | `isBoolean` |
-| `list[T]`, `List[T]` | `isList` |
-| `Optional[T]`, `T | None` | `exists` |
-| `dict`, `Dict` | `isObject` |
-| `datetime`, `date` | `isString` |
-
-**TypeScript/JavaScript 特定映射**：
-
-| TS/JS 类型 | Hurl 断言 |
-|-----------|-----------|
-| `string` | `isString` |
-| `number`（整数上下文） | `isInteger` |
-| `number`（通用） | `isNumber` |
-| `boolean` | `isBoolean` |
-| `T[]`, `Array<T>` | `isList` |
-| `T \| null`, `T \| undefined` | `exists` |
-| `object`, `Record<>` | `isObject` |
-| `Date` | `isString` |
-
-**Java 特定映射**：
-
-| Java 类型 | Hurl 断言 |
-|----------|-----------|
-| `String` | `isString` |
-| `Integer`, `Long`, `int`, `long` | `isInteger` |
-| `Double`, `Float`, `BigDecimal` | `isNumber` |
-| `Boolean`, `boolean` | `isBoolean` |
-| `List<T>` | `isList` |
-| `@Nullable`, `Optional<T>` | `exists` |
-| `Map<K,V>` | `isObject` |
-| `LocalDateTime`, `Instant` | `isString` |
-
-#### 3.4 统一响应格式断言
-
-根据 Phase 1 画像中发现的统一响应格式，为**每个成功响应**添加格式断言。
-
-示例：如果项目的统一格式是 `{code, msg, data, timestamp}`：
-
-```hurl
-[Asserts]
-jsonpath "$.code" == 0
-jsonpath "$.msg" == "success"
-jsonpath "$.timestamp" isIsoDate
-```
-
-示例：如果项目的格式是 `{status, message, result}`：
-
-```hurl
-[Asserts]
-jsonpath "$.status" == "ok"
-jsonpath "$.message" isString
-```
-
-示例：如果项目无统一包装，直接返回数据：
-
-```hurl
-[Asserts]
-# 直接断言业务字段
-jsonpath "$.id" isInteger
-jsonpath "$.name" isString
-```
-
-**不要假设响应格式，必须从代码中确认。**
-
-#### 3.5 分页断言
-
-根据 Phase 1 画像中发现的分页结构生成。
-
-示例：如果是 `{items, total, page, size}` 格式：
-
-```hurl
-jsonpath "$.data.items" isList
-jsonpath "$.data.total" isInteger
-jsonpath "$.data.total" >= 1
-jsonpath "$.data.page" isInteger
-jsonpath "$.data.size" isInteger
-# items 内元素逐字段断言
-jsonpath "$.data.items[0].{field}" {type_assert}
-```
-
-示例：如果是 `{results, count, next, previous}` 格式（Django 风格）：
-
-```hurl
-jsonpath "$.results" isList
-jsonpath "$.count" isInteger
-jsonpath "$.count" >= 1
-# results 内元素逐字段断言
-jsonpath "$.results[0].{field}" {type_assert}
-```
-
-**根据实际代码调整字段名，不硬编码。**
-
-#### 3.6 异常 Case 模板
-
-**参数校验失败**：
-
-```hurl
-# ── 异常：参数校验失败 ──
-POST {{base_url}}/{path}
-Authorization: Bearer {{token}}
-Content-Type: application/json
-{
-    "required_field": ""
-}
-HTTP {expected_error_status}
-[Asserts]
-# 断言错误响应格式（根据项目约定调整）
-```
-
-> HTTP 状态码根据项目实际返回确定：有的项目错误也返回 200 + 业务错误码，有的返回 400/422。
-
-**未认证访问**：
-
-```hurl
-# ── 异常：未认证访问 ──
-GET {{base_url}}/{protected_path}
-HTTP {expected_unauth_status}
-```
-
-**越权访问**（如果用户要求）：
-
-```hurl
-# ── 异常：用户 B 不能访问用户 A 的资源 ──
-GET {{base_url}}/{path}/{{user_a_resource_id}}
-Authorization: Bearer {{user_b_token}}
-HTTP {expected_forbidden_status}
-```
-
-#### 3.7 特殊场景处理
-
-| 场景 | 处理策略 |
-|------|---------|
-| **短信/邮件验证码** | 建议服务端加 test_mode 开关，固定验证码写入 env 文件；注释提醒用户 |
-| **第三方支付** | 优先用项目内部支付方式（如钱包支付）；如需测回调，直接 POST 回调接口模拟 |
-| **OAuth 登录（微信/Google/GitHub）** | 建议服务端加 test_mode 支持直接传 openid/email；注释提醒用户 |
-| **文件上传** | 用 Hurl 的 `[Multipart]` 语法 + testdata 目录下的样本文件 |
-| **外部 API 依赖** | 只测参数校验和错误响应格式，不断言业务结果；注释说明依赖 |
-| **WebSocket** | Hurl 不支持，注释说明跳过 |
-| **异步任务结果** | 用 Hurl 的 `retry` + `retry-interval` 轮询直到状态变更 |
-
-异步轮询示例：
-
-```hurl
-# 等待异步任务完成（最多重试 10 次，间隔 500ms）
-GET {{base_url}}/{path}/{{task_id}}
-Authorization: Bearer {{token}}
-[Options]
-retry: 10
-retry-interval: 500ms
-HTTP 200
-[Asserts]
-jsonpath "$.data.status" == "completed"
-```
-
-#### 3.8 文件输出
-
-**目录结构**（首次使用时创建，如不存在）：
-
-```
-tests/hurl/
-├── env/
-│   └── dev.env              # 环境变量
-├── testdata/                 # 测试用的样本文件
-├── flows/                    # 业务流程测试
-├── modules/                  # 按模块的接口测试
-│   └── {module}/
-│       └── 01-crud.hurl
-├── negative/                 # 异常/边界测试
-├── contract/                 # 接口契约验证
-└── Makefile                  # 快捷命令
-```
-
-文件放置规则：
-
-| 用户描述 | 输出路径 |
-|---------|---------|
-| 测试 XX 流程 / 业务流程 | `tests/hurl/flows/{flow-name}.hurl` |
-| 测试 XX 模块的 CRUD / 接口 | `tests/hurl/modules/{module}/01-crud.hurl` |
-| 测试异常/边界/权限 | `tests/hurl/negative/{name}.hurl` |
-| 测试接口契约/字段对齐 | `tests/hurl/contract/{name}.hurl` |
-
-**如果项目已有 hurl 测试目录结构，沿用已有约定，不要另起炉灶。**
-
-#### 3.9 env 和 Makefile
-
-**env/dev.env**（首次创建时生成，内容基于 Phase 1 画像）：
-
-```properties
-# 服务地址
-base_url=http://localhost:{port}
-
-# 认证信息（根据项目实际填写）
-admin_username={默认用户名}
-admin_password={默认密码}
-
-# 测试模式变量（如果有特殊场景）
-# test_sms_code=888888
-# test_openid=test_openid_001
-```
-
-**Makefile**（首次创建时生成）：
-
-```makefile
-SHELL := /bin/bash
-ENV ?= dev
-HURL_OPTS := --variables-file env/$(ENV).env --test
-
-.PHONY: test test-flows test-modules test-negative report
-
-test:            ## 运行所有测试
-	hurl $(HURL_OPTS) .
-
-test-flows:      ## 运行业务流程测试
-	hurl $(HURL_OPTS) flows/
-
-test-modules:    ## 运行模块接口测试
-	hurl $(HURL_OPTS) modules/
-
-test-negative:   ## 运行异常测试
-	hurl $(HURL_OPTS) negative/
-
-report:          ## 生成 HTML 报告
-	hurl $(HURL_OPTS) --report-html build/report/ .
-```
-
----
-
-### Phase 4: 验证（Verify）
-
-**目标：确保生成的 .hurl 文件语法正确、可运行。**
-
-#### 4.1 语法自检
-
-- [ ] 每个请求之间有空行分隔
-- [ ] `[Captures]` 和 `[Asserts]` 拼写正确（大小写敏感）
-- [ ] 所有 `{{变量}}` 引用都有来源（env 文件定义 或 上游 `[Captures]`）
-- [ ] JSON body 无尾逗号、格式正确
-- [ ] `HTTP {status}` 在请求之后、`[Captures]` / `[Asserts]` 之前
-- [ ] 请求和断言之间没有多余空行（`HTTP` 行必须紧跟请求）
-- [ ] 文件上传路径相对于 hurl 文件位置正确
-
-#### 4.2 运行测试
-
-```bash
-hurl --variables-file tests/hurl/env/dev.env --test tests/hurl/{生成的文件}
-```
-
-- 服务在跑 → 执行，如有失败分析修正
-- 服务没跑 → 跳过，告知用户手动验证命令
-
----
-
-## 红线规则
-
-| 规则 | 说明 |
-|------|------|
-| **不跳过 Phase 1** | 必须读代码确认接口路径和字段，不能凭记忆或猜测 |
-| **不跳过 Phase 2** | 必须向用户展示发现的接口和字段，确认后再生成 |
-| **不编造字段** | 所有断言的字段名必须来自实际 schema 代码 |
-| **不编造路径** | 所有接口路径必须来自实际路由代码 |
-| **不遗漏字段** | schema 中每个参与序列化的字段都必须有对应断言 |
-| **不硬编码 ID** | 所有依赖的 ID 通过 `[Captures]` 从上游请求获取 |
-| **不假设响应格式** | 统一响应结构必须从代码中确认，不同项目格式不同 |
-| **唯一值防冲突** | 创建类请求的唯一字段使用 `{{newUuid}}` 或 `{{newDate}}` |
-| **自给自足** | 每个 .hurl 文件自己创建测试数据，不依赖外部数据准备 |
-
----
-
-## AI 助手检查清单
-
-生成 .hurl 文件后自检：
-
-1. ✅ 文件头注释包含流程描述和前置条件
-2. ✅ 认证步骤正确 capture 了 token / cookie
-3. ✅ 所有依赖数据通过 API 链式创建（自给自足）
-4. ✅ 每个成功响应断言了项目的统一响应格式
-5. ✅ 查询详情接口**逐字段断言**（类型 + 值，基于 schema）
-6. ✅ 分页接口断言了分页结构 + 第一条记录的字段
-7. ✅ 修改操作后紧跟 GET 验证修改生效
-8. ✅ 删除操作后紧跟 GET 验证已删除
-9. ✅ 唯一字段使用了 `{{newUuid}}`
-10. ✅ `{{变量}}` 引用无悬空（都有 env 或 capture 来源）
-11. ✅ 文件放在了正确的目录位置
-12. ✅ 特殊场景有明确的处理策略和注释提醒
-
----
-
-## 附录：Hurl 语法速查
-
-**生成 .hurl 文件时必须参照本速查，不可凭记忆编造语法。**
-
-### 文件结构
-
-一个 .hurl 文件由多个 entry 组成，每个 entry = 请求 + 可选响应：
-
-```
-请求1
-响应1（可选）
-
-请求2
-响应2（可选）
-```
-
-entry 之间用空行分隔。
-
-### 请求格式
-
-```hurl
-METHOD URL
-Header1: value1
-Header2: value2
-[Options]
-key: value
-[Query]
-param1: value1
-[Form]
-field1: value1
-[Multipart]
-file1: file,path/to/file;
-[BasicAuth]
-username: password
-[Cookies]
-name: value
-BODY（JSON / XML / multiline string / file）
-```
-
-**规则**：
-- Method + URL 是第一行，必须
-- Headers 紧跟 URL 之后（无 section 标记）
-- Sections（`[Query]`、`[Form]`、`[Options]` 等）顺序任意
-- Body 必须在最后
-- JSON body 直接写 `{ }` 即可，自动设置 Content-Type: application/json
-
-### 响应格式
-
-```hurl
-HTTP {status_code}
-Header1: expected_value1
-[Captures]
-var_name: jsonpath "$.path"
-[Asserts]
-jsonpath "$.field" == "value"
-```
-
-**规则**：
-- `HTTP {status}` 紧跟请求之后（中间不能有空行）
-- `HTTP *` 表示不检查状态码
-- Headers 检查紧跟 HTTP 行之后
-- `[Captures]` 和 `[Asserts]` 顺序任意
-
-### 变量和模板
-
-```hurl
-# 引用变量（从 env 文件、命令行或上游 capture 获取）
-GET {{base_url}}/api/users/{{user_id}}
-
-# 内置函数
-POST {{base_url}}/api/users
-{
-    "email": "{{newUuid}}@test.com",
-    "created_at": "{{newDate}}"
-}
-```
-
-可用函数：
-- `{{newUuid}}` — 生成 UUID v4
-- `{{newDate}}` — 生成 RFC 3339 UTC 时间戳
-
-### Capture 语法
-
-```hurl
-[Captures]
-# JSONPath
-token: jsonpath "$.data.access_token"
-user_id: jsonpath "$.data.id"
-first_item: jsonpath "$.items[0].name"
-
-# Header
-location: header "Location"
-
-# Cookie
-session: cookie "SESSIONID"
-
-# Body（整个响应体作为字符串）
-full_body: body
-
-# Status code
-code: status
-
-# 正则表达式
-csrf: regex "name=\"csrf\" value=\"([^\"]+)\""
-
-# 响应时间（毫秒）
-response_time: duration
-```
-
-### Assert 语法
-
-```hurl
-[Asserts]
-# ── 状态码 ──
-status == 200
-status >= 200
-status < 300
-
-# ── JSONPath 断言 ──
-jsonpath "$.name" == "Alice"           # 等于
-jsonpath "$.name" != "Bob"             # 不等于
-jsonpath "$.age" > 18                  # 大于
-jsonpath "$.age" >= 18                 # 大于等于
-jsonpath "$.count" < 100               # 小于
-jsonpath "$.items" count == 5          # 集合长度
-jsonpath "$.name" startsWith "Al"      # 前缀
-jsonpath "$.name" endsWith "ce"        # 后缀
-jsonpath "$.name" contains "lic"       # 包含
-jsonpath "$.date" matches /\\d{4}-\\d{2}-\\d{2}/  # 正则
-
-# ── 类型断言 ──
-jsonpath "$.name" isString
-jsonpath "$.age" isInteger
-jsonpath "$.score" isFloat
-jsonpath "$.count" isNumber            # 整数或浮点
-jsonpath "$.active" isBoolean
-jsonpath "$.items" isList
-jsonpath "$.meta" isObject
-jsonpath "$.id" isUuid
-jsonpath "$.created_at" isIsoDate      # RFC 3339 格式
-jsonpath "$.field" isEmpty             # 空集合
-
-# ── 存在性 ──
-jsonpath "$.field" exists
-jsonpath "$.field" not exists
-
-# ── 否定 ──
-jsonpath "$.name" not contains "Bob"
-jsonpath "$.status" not == "deleted"
-
-# ── Header 断言 ──
-header "Content-Type" contains "application/json"
-header "X-Request-Id" exists
-
-# ── 性能 ──
-duration < 1000                        # 响应时间（毫秒）
-
-# ── Body 断言 ──
-body contains "Hello"
-bytes count == 1024
-```
-
-### Options（逐请求配置）
-
-```hurl
-GET {{base_url}}/api/task/{{task_id}}
-[Options]
-retry: 10              # 最大重试次数（-1 = 无限）
-retry-interval: 500ms  # 重试间隔
-delay: 2s              # 请求前等待
-location: true         # 跟随重定向
-insecure: true         # 允许不安全 SSL
-verbose: true          # 输出详细日志
-very-verbose: true     # 输出更详细日志
-skip: true             # 跳过此请求
-variable: key=value    # 定义变量
-HTTP 200
-```
-
-### Multipart 文件上传
-
-```hurl
-POST {{base_url}}/api/upload
-[Multipart]
-file: file,testdata/sample.xlsx;
-field1: value1
-# 指定 Content-Type
-file2: file,testdata/data.bin; application/octet-stream
-```
-
-### 运行命令
-
-```bash
-# 运行单个文件
-hurl --test file.hurl
-
-# 带变量文件
-hurl --variables-file env/dev.env --test file.hurl
-
-# 运行目录下所有 .hurl
-hurl --test tests/hurl/
-
-# 生成 HTML 报告
-hurl --test --report-html build/report/ tests/hurl/
-
-# 生成 JUnit 报告（CI 用）
-hurl --test --report-junit build/report.xml tests/hurl/
-
-# 并行执行（--test 默认并行，同文件内串行）
-hurl --test --jobs 4 tests/hurl/
-
-# 指定单个变量
-hurl --variable base_url=http://localhost:3000 --test file.hurl
-
-# 失败后继续执行
-hurl --test --continue-on-error tests/hurl/
-```
-
-### 常见错误
-
-| 错误 | 原因 | 修正 |
-|------|------|------|
-| `HTTP 200` 和请求之间有空行 | 空行会被当作 entry 分隔符 | 删除空行，HTTP 行紧跟请求 |
-| JSON body 有尾逗号 | Hurl 严格解析 JSON | 删除最后一个逗号 |
-| `jsonpath` 写成 `json_path` 或 `JsonPath` | 关键字大小写敏感 | 必须小写 `jsonpath` |
-| `[Captures]` 写成 `[Capture]` | 必须是复数 | `[Captures]`、`[Asserts]`、`[Options]` |
-| 变量 `{{ var }}` 有空格 | 允许，但建议统一 | `{{var}}` 或 `{{ var }}` 都可以 |
-| `isIsoDate` 用在非 RFC 3339 格式 | 只认 `YYYY-MM-DDTHH:mm:ss` 格式 | 如果是其他格式用 `matches` |
-| `file,path;` 路径含 `..` | Hurl 禁止相对父目录 | 用 `--file-root` 或调整路径 |

.claude/skills/model-standards/SKILL.md

@@ -1,93 +0,0 @@
----
-name: model-standards
-description: GORM Model 模型规范。创建或修改数据库模型时使用。包含模型结构、字段标签、TableName 实现等规范。
----
-
-# Model 模型规范
-
-**创建或修改 `internal/model/` 下的数据库模型时必须遵守本规范。**
-
-## 触发条件
-
-在以下情况下必须遵守本规范：
-- 创建新的数据库模型
-- 修改现有模型的字段
-- 添加新的数据库表
-
-## 必须遵守的模型结构
-
-```go
-// ModelName 模型名称模型
-// 详细的业务说明（2-3行）
-// 特殊说明（如果有）
-type ModelName struct {
-	gorm.Model              // 包含 ID、CreatedAt、UpdatedAt、DeletedAt
-	BaseModel `gorm:"embedded"` // 包含 Creator、Updater
-	Field1    string `gorm:"column:field1;type:varchar(50);not null;comment:字段1说明" json:"field1"`
-	// ... 其他字段
-}
-
-// TableName 指定表名
-func (ModelName) TableName() string {
-	return "tb_model_name"
-}
-```
-
-## 关键要点
-
-### 必须嵌入基础模型
-
-- ✅ **必须**嵌入 `gorm.Model` 和 `BaseModel`
-- ❌ **禁止**手动定义 ID、CreatedAt、UpdatedAt、DeletedAt、Creator、Updater
-
-### 必须添加中文注释
-
-- ✅ **必须**为模型添加中文注释，说明业务用途（参考 `internal/model/iot_card.go`）
-- ✅ **必须**在每个字段的 `comment` 标签中添加中文说明
-- ✅ **必须**为导出的类型编写 godoc 格式的文档注释
-
-### 必须实现 TableName
-
-- ✅ **必须**实现 `TableName()` 方法
-- ✅ 表名使用 `tb_` 前缀
-
-### 字段标签规范
-
-- ✅ 所有字段必须显式指定 `gorm:"column:field_name"` 标签
-- ✅ 金额字段使用 `int64` 类型，单位为分
-- ✅ 时间字段使用 `*time.Time`（可空）或 `time.Time`（必填）
-- ✅ JSONB 字段需要实现 `driver.Valuer` 和 `sql.Scanner` 接口
-
-## 完整示例
-
-```go
-// IotCard 物联网卡模型
-// 记录物联网卡的基础信息、状态和套餐关联
-// 支持单卡和设备绑定两种使用模式
-type IotCard struct {
-	gorm.Model
-	BaseModel   `gorm:"embedded"`
-	ICCID       string     `gorm:"column:iccid;type:varchar(20);uniqueIndex;not null;comment:ICCID卡号" json:"iccid"`
-	IMSI        string     `gorm:"column:imsi;type:varchar(20);comment:IMSI号" json:"imsi"`
-	Status      int        `gorm:"column:status;type:smallint;default:0;comment:状态(0:未激活,1:已激活,2:已停机)" json:"status"`
-	ActivatedAt *time.Time `gorm:"column:activated_at;comment:激活时间" json:"activated_at"`
-	ShopID      uint       `gorm:"column:shop_id;index;comment:所属店铺ID" json:"shop_id"`
-}
-
-// TableName 指定表名
-func (IotCard) TableName() string {
-	return "tb_iot_card"
-}
-```
-
-## AI 助手检查清单
-
-修改模型后必须检查：
-
-1. ✅ 是否嵌入了 `gorm.Model` 和 `BaseModel`
-2. ✅ 是否有 godoc 格式的模型注释
-3. ✅ 所有字段是否有 `gorm:"column:xxx"` 标签
-4. ✅ 所有字段是否有 `comment:xxx` 说明
-5. ✅ 是否实现了 `TableName()` 方法
-6. ✅ 表名是否使用 `tb_` 前缀
-7. ✅ 金额字段是否使用 `int64`（单位：分）

.claude/skills/openspec-api-contract/SKILL.md

@@ -1,97 +0,0 @@
----
-name: openspec-api-contract
-description: OpenSpec API 契约规范。创建涉及接口的 OpenSpec 提案时使用。探索阶段提供业务与契约引导清单，提案文档要求 API 契约设计、错误码与完成标准等必填章节。
----
-
-# OpenSpec API 契约规范
-
-**适用场景**：创建涉及 API/接口的 OpenSpec 提案时，探索和提案两个阶段均须遵守本规范。
-
----
-
-## 一、探索阶段引导清单
-
-在 `openspec-explore` 阶段，当内容涉及接口时，讨论必须覆盖以下所有维度。
-
-### 业务与契约确认
-
-**输入与输出**
-- 请求方是谁？用户类型（SuperAdmin/Platform/Agent/Enterprise/Personal）？
-- 输入参数：必填/选填字段、格式约束、参数来源（路径/查询/Body）？
-- 输出结构：哪些字段必须返回？是否需要分页？
-
-**业务规则**
-- 核心业务规则与边界条件？
-- 是否涉及状态流转？状态机的完整定义？
-- 依赖外部服务时，外部异常的降级行为？
-
-**权限与资源所有权**
-- 哪些用户类型可以访问？
-- 是否涉及跨用户/跨店铺/跨企业的资源访问？（需三层越权防护）
-- 资源所有权校验方式：`CanManageShop` / `CanManageEnterprise` / 自有资源？
-
-**幂等性**
-- 操作类型：查询（天然幂等）/ 创建 / 更新 / 删除？
-- 写操作幂等策略：状态条件更新 / Redis 业务键防重 + 分布式锁 / 乐观锁（version）？
-- 异步任务是否需要任务锁？
-
-**数据模型变更**
-- 是否需要新建表、修改现有表或数据回填？
-- 迁移策略：上线顺序、兼容旧数据的方式？
-- 是否影响 GORM Callback 自动数据权限过滤？
-
-**错误码与异常语义**
-- 预期错误场景及对应错误码？
-- 错误响应是否泄露敏感信息？（参数校验失败统一返回 `CodeInvalidParam`）
-
----
-
-## 二、提案文档必填章节
-
-在 `openspec-propose` 生成的提案（`proposal.md` / `design.md`）中，涉及接口时以下内容**不可缺失**。
-
-### API 契约设计
-
-**接口定义**
-
-| 项 | 内容 |
-|---|---|
-| Endpoint | `METHOD /api/{scope}/{resource}[/:id]` |
-| 请求参数 | 字段名、类型、必填/选填、说明 |
-| 响应结构 | `data` 字段的完整结构定义 |
-| 鉴权要求 | 允许的用户类型 |
-| 资源所有权 | 所有权校验方式 |
-
-**列表接口额外要求**
-- 分页：`page` + `page_size`（默认 20，最大 100）
-- 排序：默认排序字段与方向
-- 过滤：支持的过滤条件列表
-
-**错误码清单**
-
-| 场景 | 错误码 | 说明 |
-|---|---|---|
-| 参数校验失败 | `CodeInvalidParam` | 统一返回，不泄露细节 |
-| 资源不存在/越权 | `CodeForbidden` | 不区分两者，防止信息泄露 |
-| （业务错误场景...） | （对应错误码） | （说明） |
-
-### 完成标准
-
-**最小验证步骤**（按顺序列出可操作的验证步骤）
-
-1. （例：调用创建接口，验证返回 `code=0`）
-2. （例：查询接口确认数据存在且字段正确）
-3. （例：PostgreSQL MCP 查询确认数据库记录符合预期）
-
-**影响范围说明**
-- 新增/修改的表：
-- 影响的现有接口：
-- 影响的权限与数据过滤范围：
-
----
-
-## 约束（必须遵守）
-
-- **优先复用现有架构与库**：不引入新依赖，错误码优先复用已有定义
-- **不做顺手重构**：提案范围严格限定在目标功能；发现可优化点，记录到 backlog 但不执行
-- **数据库设计**：禁止外键约束，禁止 GORM 关联标签，关联通过 ID 字段手动维护

.claude/skills/openspec-lock-consensus/SKILL.md

@@ -1,281 +0,0 @@
----
-name: openspec-lock-consensus
-description: 锁定共识 - 在探索讨论后，将讨论结果锁定为正式共识文档。防止后续提案偏离讨论内容。
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: junhong
-  version: "1.1"
----
-
-# 共识锁定 Skill
-
-在 `/opsx:explore` 讨论后，使用此 skill 将讨论结果锁定为正式共识。共识文档是后续所有 artifact 的基础约束。
-
-## 触发方式
-
-```
-/opsx:lock <change-name>
-```
-
-或在探索结束后，AI 主动提议：
-> "讨论已经比较清晰了，要锁定共识吗？"
-
----
-
-## 工作流程
-
-### Step 1: 整理讨论要点
-
-从对话中提取以下四个维度的共识：
-
-| 维度 | 说明 | 示例 |
-|------|------|------|
-| **要做什么** | 明确的功能范围 | "支持批量导入 IoT 卡" |
-| **不做什么** | 明确排除的内容 | "不支持实时同步，仅定时批量" |
-| **关键约束** | 技术/业务限制 | "必须使用 Asynq 异步任务" |
-| **验收标准** | 如何判断完成 | "导入 1000 张卡 < 30s" |
-
-### Step 2: 使用 Question_tool 逐维度确认
-
-**必须使用 Question_tool 进行结构化确认**，每个维度一个问题：
-
-```typescript
-// 示例：确认"要做什么"
-Question_tool({
-  questions: [{
-    header: "确认：要做什么",
-    question: "以下是整理的功能范围，请确认：\n\n" +
-              "1. 功能点 A\n" +
-              "2. 功能点 B\n" +
-              "3. 功能点 C\n\n" +
-              "是否准确完整？",
-    options: [
-      { label: "确认无误", description: "以上内容准确完整" },
-      { label: "需要补充", description: "有遗漏的功能点" },
-      { label: "需要删减", description: "有不应该包含的内容" }
-    ],
-    multiple: false
-  }]
-})
-```
-
-**如果用户选择"需要补充"或"需要删减"**：
-- 用户会通过自定义输入提供修改意见
-- 根据反馈更新列表，再次使用 Question_tool 确认
-
-**确认流程**：
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  Question_tool: 确认"要做什么"                                      │
-│  ├── 用户选择"确认无误" → 进入下一维度                              │
-│  └── 用户选择其他/自定义 → 修改后重新确认                           │
-├─────────────────────────────────────────────────────────────────────┤
-│  Question_tool: 确认"不做什么"                                      │
-│  ├── 用户选择"确认无误" → 进入下一维度                              │
-│  └── 用户选择其他/自定义 → 修改后重新确认                           │
-├─────────────────────────────────────────────────────────────────────┤
-│  Question_tool: 确认"关键约束"                                      │
-│  ├── 用户选择"确认无误" → 进入下一维度                              │
-│  └── 用户选择其他/自定义 → 修改后重新确认                           │
-├─────────────────────────────────────────────────────────────────────┤
-│  Question_tool: 确认"验收标准"                                      │
-│  ├── 用户选择"确认无误" → 生成 consensus.md                         │
-│  └── 用户选择其他/自定义 → 修改后重新确认                           │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-### Step 3: 生成 consensus.md
-
-所有维度确认后，创建文件：
-
-```bash
-# 检查 change 是否存在
-openspec list --json
-
-# 如果 change 不存在，先创建
-# openspec new <change-name>
-
-# 写入 consensus.md
-```
-
-**文件路径**: `openspec/changes/<change-name>/consensus.md`
-
----
-
-## Question_tool 使用规范
-
-### 每个维度的问题模板
-
-**1. 要做什么**
-```typescript
-{
-  header: "确认：要做什么",
-  question: "以下是整理的【功能范围】：\n\n" +
-            items.map((item, i) => `${i+1}. ${item}`).join('\n') +
-            "\n\n请确认是否准确完整？",
-  options: [
-    { label: "确认无误", description: "功能范围准确完整" },
-    { label: "需要补充", description: "有遗漏的功能点" },
-    { label: "需要删减", description: "有不应该包含的内容" }
-  ]
-}
-```
-
-**2. 不做什么**
-```typescript
-{
-  header: "确认：不做什么",
-  question: "以下是明确【排除的内容】：\n\n" +
-            items.map((item, i) => `${i+1}. ${item}`).join('\n') +
-            "\n\n请确认是否正确？",
-  options: [
-    { label: "确认无误", description: "排除范围正确" },
-    { label: "需要补充", description: "还有其他需要排除的" },
-    { label: "需要删减", description: "有些不应该排除" }
-  ]
-}
-```
-
-**3. 关键约束**
-```typescript
-{
-  header: "确认：关键约束",
-  question: "以下是【关键约束】：\n\n" +
-            items.map((item, i) => `${i+1}. ${item}`).join('\n') +
-            "\n\n请确认是否正确？",
-  options: [
-    { label: "确认无误", description: "约束条件正确" },
-    { label: "需要补充", description: "还有其他约束" },
-    { label: "需要修改", description: "约束描述不准确" }
-  ]
-}
-```
-
-**4. 验收标准**
-```typescript
-{
-  header: "确认：验收标准",
-  question: "以下是【验收标准】（必须可测量）：\n\n" +
-            items.map((item, i) => `${i+1}. ${item}`).join('\n') +
-            "\n\n请确认是否正确？",
-  options: [
-    { label: "确认无误", description: "验收标准清晰可测量" },
-    { label: "需要补充", description: "还有其他验收标准" },
-    { label: "需要修改", description: "标准不够清晰或无法测量" }
-  ]
-}
-```
-
-### 处理用户反馈
-
-当用户选择非"确认无误"选项或提供自定义输入时：
-
-1. 解析用户的修改意见
-2. 更新对应维度的内容
-3. 再次使用 Question_tool 确认更新后的内容
-4. 重复直到用户选择"确认无误"
-
----
-
-## consensus.md 模板
-
-```markdown
-# 共识文档
-
-**Change**: <change-name>
-**确认时间**: <timestamp>
-**确认人**: 用户
-
----
-
-## 1. 要做什么
-
-- [x] 功能点 A（已确认）
-- [x] 功能点 B（已确认）
-- [x] 功能点 C（已确认）
-
-## 2. 不做什么
-
-- [x] 排除项 A（已确认）
-- [x] 排除项 B（已确认）
-
-## 3. 关键约束
-
-- [x] 技术约束 A（已确认）
-- [x] 业务约束 B（已确认）
-
-## 4. 验收标准
-
-- [x] 验收标准 A（已确认）
-- [x] 验收标准 B（已确认）
-
----
-
-## 讨论背景
-
-<简要总结讨论的核心问题和解决方向>
-
-## 关键决策记录
-
-| 决策点 | 选择 | 原因 |
-|--------|------|------|
-| 决策 1 | 选项 A | 理由... |
-| 决策 2 | 选项 B | 理由... |
-
----
-
-**签字确认**: 用户已通过 Question_tool 逐条确认以上内容
-```
-
----
-
-## 后续流程绑定
-
-### Proposal 生成时
-
-`/opsx:continue` 生成 proposal 时，**必须**：
-
-1. 读取 `consensus.md`
-2. 确保 proposal 的 Capabilities 覆盖"要做什么"中的每一项
-3. 确保 proposal 不包含"不做什么"中的内容
-4. 确保 proposal 遵守"关键约束"
-
-### 验证机制
-
-如果 proposal 与 consensus 不一致，输出警告：
-
-```
-⚠️ Proposal 验证警告：
-
-共识中"要做什么"但 Proposal 未提及：
-- 功能点 C
-
-共识中"不做什么"但 Proposal 包含：
-- 排除项 A
-
-建议修正 Proposal 或更新共识。
-```
-
----
-
-## Guardrails
-
-- **必须使用 Question_tool** - 不要用纯文本确认
-- **逐维度确认** - 四个维度分开确认，不要合并
-- **不要跳过确认** - 每个维度都必须让用户明确确认
-- **不要自作主张** - 只整理讨论中明确提到的内容
-- **避免模糊表述** - "尽量"、"可能"、"考虑"等词汇需要明确化
-- **验收标准必须可测量** - 避免"性能要好"这类无法验证的标准
-
----
-
-## 与其他 Skills 的关系
-
-| Skill | 关系 |
-|-------|------|
-| `openspec-explore` | 探索结束后触发 lock |
-| `openspec-new-change` | lock 后触发 new（如果 change 不存在）|
-| `openspec-continue-change` | 生成 proposal 时读取 consensus 验证 |
-| `openspec-generate-acceptance-tests` | 从 consensus 的验收标准生成测试骨架 |

.claude/skills/to-issues

@@ -1 +0,0 @@
-../../.agents/skills/to-issues

.claude/skills/to-prd

@@ -1 +0,0 @@
-../../.agents/skills/to-prd

.claude/skills/to-questionnaire

@@ -0,0 +1 @@
+../../.agents/skills/to-questionnaire

.claude/skills/wait-what

@@ -0,0 +1 @@
+../../.agents/skills/wait-what

.claude/skills/wizard

@@ -0,0 +1 @@
+../../.agents/skills/wizard

.claude/skills/write-a-skill

@@ -1 +0,0 @@
-../../.agents/skills/write-a-skill

.claude/skills/writing-for-agents

@@ -0,0 +1 @@
+../../.agents/skills/writing-for-agents

.claude/skills/writing-great-skills

@@ -1 +0,0 @@
-../../.agents/skills/writing-great-skills

.claude/skills/zoom-out

@@ -1 +0,0 @@
-../../.agents/skills/zoom-out

.codex/prompts/opsx-apply.md

@@ -1,150 +0,0 @@
----
-description: Implement tasks from an OpenSpec change (Experimental)
-argument-hint: command arguments
----
-
-Implement tasks from an OpenSpec change.
-
-**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **Select the change**
-
-   If a name is provided, use it. Otherwise:
-   - Infer from conversation context if the user mentioned a change
-   - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
-
-   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
-
-2. **Check status to understand the schema**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used (e.g., "spec-driven")
-   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
-
-3. **Get apply instructions**
-
-   ```bash
-   openspec instructions apply --change "<name>" --json
-   ```
-
-   This returns:
-   - Context file paths (varies by schema)
-   - Progress (total, complete, remaining)
-   - Task list with status
-   - Dynamic instruction based on current state
-
-   **Handle states:**
-   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
-   - If `state: "all_done"`: congratulate, suggest archive
-   - Otherwise: proceed to implementation
-
-4. **Read context files**
-
-   Read the files listed in `contextFiles` from the apply instructions output.
-   The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
-   - Other schemas: follow the contextFiles from CLI output
-
-5. **Show current progress**
-
-   Display:
-   - Schema being used
-   - Progress: "N/M tasks complete"
-   - Remaining tasks overview
-   - Dynamic instruction from CLI
-
-6. **Implement tasks (loop until done or blocked)**
-
-   For each pending task:
-   - Show which task is being worked on
-   - Make the code changes required
-   - Keep changes minimal and focused
-   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
-   - Continue to next task
-
-   **Pause if:**
-   - Task is unclear → ask for clarification
-   - Implementation reveals a design issue → suggest updating artifacts
-   - Error or blocker encountered → report and wait for guidance
-   - User interrupts
-
-7. **On completion or pause, show status**
-
-   Display:
-   - Tasks completed this session
-   - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
-   - If paused: explain why and wait for guidance
-
-**Output During Implementation**
-
-```
-## Implementing: <change-name> (schema: <schema-name>)
-
-Working on task 3/7: <task description>
-[...implementation happening...]
-✓ Task complete
-
-Working on task 4/7: <task description>
-[...implementation happening...]
-✓ Task complete
-```
-
-**Output On Completion**
-
-```
-## Implementation Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 7/7 tasks complete ✓
-
-### Completed This Session
-- [x] Task 1
-- [x] Task 2
-...
-
-All tasks complete! Ready to archive this change.
-```
-
-**Output On Pause (Issue Encountered)**
-
-```
-## Implementation Paused
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 4/7 tasks complete
-
-### Issue Encountered
-<description of the issue>
-
-**Options:**
-1. <option 1>
-2. <option 2>
-3. Other approach
-
-What would you like to do?
-```
-
-**Guardrails**
-- Keep going through tasks until done or blocked
-- Always read context files before starting (from the apply instructions output)
-- If task is ambiguous, pause and ask before implementing
-- If implementation reveals issues, pause and suggest artifact updates
-- Keep code changes minimal and scoped to each task
-- Update task checkbox immediately after completing each task
-- Pause on errors, blockers, or unclear requirements - don't guess
-- Use contextFiles from CLI output, don't assume specific file names
-
-**Fluid Workflow Integration**
-
-This skill supports the "actions on a change" model:
-
-- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
-- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.codex/prompts/opsx-archive.md

@@ -1,155 +0,0 @@
----
-description: Archive a completed change in the experimental workflow
-argument-hint: command arguments
----
-
-Archive a completed change in the experimental workflow.
-
-**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show only active changes (not already archived).
-   Include the schema used for each change if available.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check artifact completion status**
-
-   Run `openspec status --change "<name>" --json` to check artifact completion.
-
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used
-   - `artifacts`: List of artifacts with their status (`done` or other)
-
-   **If any artifacts are not `done`:**
-   - Display warning listing incomplete artifacts
-   - Prompt user for confirmation to continue
-   - Proceed if user confirms
-
-3. **Check task completion status**
-
-   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
-
-   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
-
-   **If incomplete tasks found:**
-   - Display warning showing count of incomplete tasks
-   - Prompt user for confirmation to continue
-   - Proceed if user confirms
-
-   **If no tasks file exists:** Proceed without task-related warning.
-
-4. **Assess delta spec sync state**
-
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
-
-   **If delta specs exist:**
-   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
-   - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
-
-   **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
-
-   If user chooses sync, execute `/opsx:sync` logic. Proceed to archive regardless of choice.
-
-5. **Perform the archive**
-
-   Create the archive directory if it doesn't exist:
-   ```bash
-   mkdir -p openspec/changes/archive
-   ```
-
-   Generate target name using current date: `YYYY-MM-DD-<change-name>`
-
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
-
-   ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
-   ```
-
-6. **Display summary**
-
-   Show archive completion summary including:
-   - Change name
-   - Schema that was used
-   - Archive location
-   - Spec sync status (synced / sync skipped / no delta specs)
-   - Note about any warnings (incomplete artifacts/tasks)
-
-**Output On Success**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
-**Specs:** ✓ Synced to main specs
-
-All artifacts complete. All tasks complete.
-```
-
-**Output On Success (No Delta Specs)**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
-**Specs:** No delta specs
-
-All artifacts complete. All tasks complete.
-```
-
-**Output On Success With Warnings**
-
-```
-## Archive Complete (with warnings)
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
-**Specs:** Sync skipped (user chose to skip)
-
-**Warnings:**
-- Archived with 2 incomplete artifacts
-- Archived with 3 incomplete tasks
-- Delta spec sync was skipped (user chose to skip)
-
-Review the archive if this was not intentional.
-```
-
-**Output On Error (Archive Exists)**
-
-```
-## Archive Failed
-
-**Change:** <change-name>
-**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
-
-Target archive directory already exists.
-
-**Options:**
-1. Rename the existing archive
-2. Delete the existing archive if it's a duplicate
-3. Wait until a different date to archive
-```
-
-**Guardrails**
-- Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
-- Don't block archive on warnings - just inform and confirm
-- Preserve .openspec.yaml when moving to archive (it moves with the directory)
-- Show clear summary of what happened
-- If sync is requested, use /opsx:sync approach (agent-driven)
-- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.codex/prompts/opsx-bulk-archive.md

@@ -1,240 +0,0 @@
----
-description: Archive multiple completed changes at once
-argument-hint: command arguments
----
-
-Archive multiple completed changes in a single operation.
-
-This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
-
-**Input**: None required (prompts for selection)
-
-**Steps**
-
-1. **Get active changes**
-
-   Run `openspec list --json` to get all active changes.
-
-   If no active changes exist, inform user and stop.
-
-2. **Prompt for change selection**
-
-   Use **AskUserQuestion tool** with multi-select to let user choose changes:
-   - Show each change with its schema
-   - Include an option for "All changes"
-   - Allow any number of selections (1+ works, 2+ is the typical use case)
-
-   **IMPORTANT**: Do NOT auto-select. Always let the user choose.
-
-3. **Batch validation - gather status for all selected changes**
-
-   For each selected change, collect:
-
-   a. **Artifact status** - Run `openspec status --change "<name>" --json`
-      - Parse `schemaName` and `artifacts` list
-      - Note which artifacts are `done` vs other states
-
-   b. **Task completion** - Read `openspec/changes/<name>/tasks.md`
-      - Count `- [ ]` (incomplete) vs `- [x]` (complete)
-      - If no tasks file exists, note as "No tasks"
-
-   c. **Delta specs** - Check `openspec/changes/<name>/specs/` directory
-      - List which capability specs exist
-      - For each, extract requirement names (lines matching `### Requirement: <name>`)
-
-4. **Detect spec conflicts**
-
-   Build a map of `capability -> [changes that touch it]`:
-
-   ```
-   auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
-   api  -> [change-c]            <- OK (only 1 change)
-   ```
-
-   A conflict exists when 2+ selected changes have delta specs for the same capability.
-
-5. **Resolve conflicts agentically**
-
-   **For each conflict**, investigate the codebase:
-
-   a. **Read the delta specs** from each conflicting change to understand what each claims to add/modify
-
-   b. **Search the codebase** for implementation evidence:
-      - Look for code implementing requirements from each delta spec
-      - Check for related files, functions, or tests
-
-   c. **Determine resolution**:
-      - If only one change is actually implemented -> sync that one's specs
-      - If both implemented -> apply in chronological order (older first, newer overwrites)
-      - If neither implemented -> skip spec sync, warn user
-
-   d. **Record resolution** for each conflict:
-      - Which change's specs to apply
-      - In what order (if both)
-      - Rationale (what was found in codebase)
-
-6. **Show consolidated status table**
-
-   Display a table summarizing all changes:
-
-   ```
-   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
-   |---------------------|-----------|-------|---------|-----------|--------|
-   | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
-   | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
-   | add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
-   | add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |
-   ```
-
-   For conflicts, show the resolution:
-   ```
-   * Conflict resolution:
-     - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)
-   ```
-
-   For incomplete changes, show warnings:
-   ```
-   Warnings:
-   - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks
-   ```
-
-7. **Confirm batch operation**
-
-   Use **AskUserQuestion tool** with a single confirmation:
-
-   - "Archive N changes?" with options based on status
-   - Options might include:
-     - "Archive all N changes"
-     - "Archive only N ready changes (skip incomplete)"
-     - "Cancel"
-
-   If there are incomplete changes, make clear they'll be archived with warnings.
-
-8. **Execute archive for each confirmed change**
-
-   Process changes in the determined order (respecting conflict resolution):
-
-   a. **Sync specs** if delta specs exist:
-      - Use the openspec-sync-specs approach (agent-driven intelligent merge)
-      - For conflicts, apply in resolved order
-      - Track if sync was done
-
-   b. **Perform the archive**:
-      ```bash
-      mkdir -p openspec/changes/archive
-      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
-      ```
-
-   c. **Track outcome** for each change:
-      - Success: archived successfully
-      - Failed: error during archive (record error)
-      - Skipped: user chose not to archive (if applicable)
-
-9. **Display summary**
-
-   Show final results:
-
-   ```
-   ## Bulk Archive Complete
-
-   Archived 3 changes:
-   - schema-management-cli -> archive/2026-01-19-schema-management-cli/
-   - project-config -> archive/2026-01-19-project-config/
-   - add-oauth -> archive/2026-01-19-add-oauth/
-
-   Skipped 1 change:
-   - add-verify-skill (user chose not to archive incomplete)
-
-   Spec sync summary:
-   - 4 delta specs synced to main specs
-   - 1 conflict resolved (auth: applied both in chronological order)
-   ```
-
-   If any failures:
-   ```
-   Failed 1 change:
-   - some-change: Archive directory already exists
-   ```
-
-**Conflict Resolution Examples**
-
-Example 1: Only one implemented
-```
-Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
-
-Checking add-oauth:
-- Delta adds "OAuth Provider Integration" requirement
-- Searching codebase... found src/auth/oauth.ts implementing OAuth flow
-
-Checking add-jwt:
-- Delta adds "JWT Token Handling" requirement
-- Searching codebase... no JWT implementation found
-
-Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.
-```
-
-Example 2: Both implemented
-```
-Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
-
-Checking add-rest-api (created 2026-01-10):
-- Delta adds "REST Endpoints" requirement
-- Searching codebase... found src/api/rest.ts
-
-Checking add-graphql (created 2026-01-15):
-- Delta adds "GraphQL Schema" requirement
-- Searching codebase... found src/api/graphql.ts
-
-Resolution: Both implemented. Will apply add-rest-api specs first,
-then add-graphql specs (chronological order, newer takes precedence).
-```
-
-**Output On Success**
-
-```
-## Bulk Archive Complete
-
-Archived N changes:
-- <change-1> -> archive/YYYY-MM-DD-<change-1>/
-- <change-2> -> archive/YYYY-MM-DD-<change-2>/
-
-Spec sync summary:
-- N delta specs synced to main specs
-- No conflicts (or: M conflicts resolved)
-```
-
-**Output On Partial Success**
-
-```
-## Bulk Archive Complete (partial)
-
-Archived N changes:
-- <change-1> -> archive/YYYY-MM-DD-<change-1>/
-
-Skipped M changes:
-- <change-2> (user chose not to archive incomplete)
-
-Failed K changes:
-- <change-3>: Archive directory already exists
-```
-
-**Output When No Changes**
-
-```
-## No Changes to Archive
-
-No active changes found. Use `/opsx:new` to create a new change.
-```
-
-**Guardrails**
-- Allow any number of changes (1+ is fine, 2+ is the typical use case)
-- Always prompt for selection, never auto-select
-- Detect spec conflicts early and resolve by checking codebase
-- When both changes are implemented, apply specs in chronological order
-- Skip spec sync only when implementation is missing (warn user)
-- Show clear per-change status before confirming
-- Use single confirmation for entire batch
-- Track and report all outcomes (success/skip/fail)
-- Preserve .openspec.yaml when moving to archive
-- Archive directory target uses current date: YYYY-MM-DD-<name>
-- If archive target exists, fail that change but continue with others

.codex/prompts/opsx-continue.md

@@ -1,112 +0,0 @@
----
-description: Continue working on a change - create the next artifact (Experimental)
-argument-hint: command arguments
----
-
-Continue working on a change by creating the next artifact.
-
-**Input**: Optionally specify a change name after `/opsx:continue` (e.g., `/opsx:continue add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
-
-   Present the top 3-4 most recently modified changes as options, showing:
-   - Change name
-   - Schema (from `schema` field if present, otherwise "spec-driven")
-   - Status (e.g., "0/5 tasks", "complete", "no tasks")
-   - How recently it was modified (from `lastModified` field)
-
-   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check current status**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to understand current state. The response includes:
-   - `schemaName`: The workflow schema being used (e.g., "spec-driven")
-   - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked")
-   - `isComplete`: Boolean indicating if all artifacts are complete
-
-3. **Act based on status**:
-
-   ---
-
-   **If all artifacts are complete (`isComplete: true`)**:
-   - Congratulate the user
-   - Show final status including the schema used
-   - Suggest: "All artifacts created! You can now implement this change or archive it."
-   - STOP
-
-   ---
-
-   **If artifacts are ready to create** (status shows artifacts with `status: "ready"`):
-   - Pick the FIRST artifact with `status: "ready"` from the status output
-   - Get its instructions:
-     ```bash
-     openspec instructions <artifact-id> --change "<name>" --json
-     ```
-   - Parse the JSON. The key fields are:
-     - `context`: Project background (constraints for you - do NOT include in output)
-     - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
-     - `template`: The structure to use for your output file
-     - `instruction`: Schema-specific guidance
-     - `outputPath`: Where to write the artifact
-     - `dependencies`: Completed artifacts to read for context
-   - **Create the artifact file**:
-     - Read any completed dependency files for context
-     - Use `template` as the structure - fill in its sections
-     - Apply `context` and `rules` as constraints when writing - but do NOT copy them into the file
-     - Write to the output path specified in instructions
-   - Show what was created and what's now unlocked
-   - STOP after creating ONE artifact
-
-   ---
-
-   **If no artifacts are ready (all blocked)**:
-   - This shouldn't happen with a valid schema
-   - Show status and suggest checking for issues
-
-4. **After creating an artifact, show progress**
-   ```bash
-   openspec status --change "<name>"
-   ```
-
-**Output**
-
-After each invocation, show:
-- Which artifact was created
-- Schema workflow being used
-- Current progress (N/M complete)
-- What artifacts are now unlocked
-- Prompt: "Run `/opsx:continue` to create the next artifact"
-
-**Artifact Creation Guidelines**
-
-The artifact types and their purpose depend on the schema. Use the `instruction` field from the instructions output to understand what to create.
-
-Common artifact patterns:
-
-**spec-driven schema** (proposal → specs → design → tasks):
-- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
-  - The Capabilities section is critical - each capability listed will need a spec file.
-- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
-- **design.md**: Document technical decisions, architecture, and implementation approach.
-- **tasks.md**: Break down implementation into checkboxed tasks.
-
-For other schemas, follow the `instruction` field from the CLI output.
-
-**Guardrails**
-- Create ONE artifact per invocation
-- Always read dependency artifacts before creating a new one
-- Never skip artifacts or create out of order
-- If context is unclear, ask the user before creating
-- Verify the artifact file exists after writing before marking progress
-- Use the schema's artifact sequence, don't assume specific artifact names
-- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
-  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
-  - These guide what you write, but should never appear in the output

.codex/prompts/opsx-explore.md

@@ -1,172 +0,0 @@
----
-description: Enter explore mode - think through ideas, investigate problems, clarify requirements
-argument-hint: command arguments
----
-
-Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
-
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
-
-**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
-
-**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
-- A vague idea: "real-time collaboration"
-- A specific problem: "the auth system is getting unwieldy"
-- A change name: "add-dark-mode" (to explore in context of that change)
-- A comparison: "postgres vs sqlite for this"
-- Nothing (just enter explore mode)
-
----
-
-## The Stance
-
-- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
-- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
-- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
-- **Adaptive** - Follow interesting threads, pivot when new information emerges
-- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
-- **Grounded** - Explore the actual codebase when relevant, don't just theorize
-
----
-
-## What You Might Do
-
-Depending on what the user brings, you might:
-
-**Explore the problem space**
-- Ask clarifying questions that emerge from what they said
-- Challenge assumptions
-- Reframe the problem
-- Find analogies
-
-**Investigate the codebase**
-- Map existing architecture relevant to the discussion
-- Find integration points
-- Identify patterns already in use
-- Surface hidden complexity
-
-**Compare options**
-- Brainstorm multiple approaches
-- Build comparison tables
-- Sketch tradeoffs
-- Recommend a path (if asked)
-
-**Visualize**
-```
-┌─────────────────────────────────────────┐
-│     Use ASCII diagrams liberally        │
-├─────────────────────────────────────────┤
-│                                         │
-│   ┌────────┐         ┌────────┐        │
-│   │ State  │────────▶│ State  │        │
-│   │   A    │         │   B    │        │
-│   └────────┘         └────────┘        │
-│                                         │
-│   System diagrams, state machines,      │
-│   data flows, architecture sketches,    │
-│   dependency graphs, comparison tables  │
-│                                         │
-└─────────────────────────────────────────┘
-```
-
-**Surface risks and unknowns**
-- Identify what could go wrong
-- Find gaps in understanding
-- Suggest spikes or investigations
-
----
-
-## OpenSpec Awareness
-
-You have full context of the OpenSpec system. Use it naturally, don't force it.
-
-### Check for context
-
-At the start, quickly check what exists:
-```bash
-openspec list --json
-```
-
-This tells you:
-- If there are active changes
-- Their names, schemas, and status
-- What the user might be working on
-
-If the user mentioned a specific change name, read its artifacts for context.
-
-### When no change exists
-
-Think freely. When insights crystallize, you might offer:
-
-- "This feels solid enough to start a change. Want me to create one?"
-  → Can transition to `/opsx:new` or `/opsx:ff`
-- Or keep exploring - no pressure to formalize
-
-### When a change exists
-
-If the user mentions a change or you detect one is relevant:
-
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
-
-2. **Reference them naturally in conversation**
-   - "Your design mentions using Redis, but we just realized SQLite fits better..."
-   - "The proposal scopes this to premium users, but we're now thinking everyone..."
-
-3. **Offer to capture when decisions are made**
-
-   | Insight Type | Where to Capture |
-   |--------------|------------------|
-   | New requirement discovered | `specs/<capability>/spec.md` |
-   | Requirement changed | `specs/<capability>/spec.md` |
-   | Design decision made | `design.md` |
-   | Scope changed | `proposal.md` |
-   | New work identified | `tasks.md` |
-   | Assumption invalidated | Relevant artifact |
-
-   Example offers:
-   - "That's a design decision. Capture it in design.md?"
-   - "This is a new requirement. Add it to specs?"
-   - "This changes scope. Update the proposal?"
-
-4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
-
----
-
-## What You Don't Have To Do
-
-- Follow a script
-- Ask the same questions every time
-- Produce a specific artifact
-- Reach a conclusion
-- Stay on topic if a tangent is valuable
-- Be brief (this is thinking time)
-
----
-
-## Ending Discovery
-
-There's no required ending. Discovery might:
-
-- **Flow into action**: "Ready to start? `/opsx:new` or `/opsx:ff`"
-- **Result in artifact updates**: "Updated design.md with these decisions"
-- **Just provide clarity**: User has what they need, moves on
-- **Continue later**: "We can pick this up anytime"
-
-When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
-
----
-
-## Guardrails
-
-- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
-- **Don't fake understanding** - If something is unclear, dig deeper
-- **Don't rush** - Discovery is thinking time, not task time
-- **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it
-- **Do visualize** - A good diagram is worth many paragraphs
-- **Do explore the codebase** - Ground discussions in reality
-- **Do question assumptions** - Including the user's and your own

.codex/prompts/opsx-ff.md

@@ -1,92 +0,0 @@
----
-description: Create a change and generate all artifacts needed for implementation in one go
-argument-hint: command arguments
----
-
-Fast-forward through artifact creation - generate everything needed to start implementation.
-
-**Input**: The argument after `/opsx:ff` is the change name (kebab-case), OR a description of what the user wants to build.
-
-**Steps**
-
-1. **If no input provided, ask what they want to build**
-
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
-   > "What change do you want to work on? Describe what you want to build or fix."
-
-   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
-
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
-
-2. **Create the change directory**
-   ```bash
-   openspec new change "<name>"
-   ```
-   This creates a scaffolded change at `openspec/changes/<name>/`.
-
-3. **Get the artifact build order**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to get:
-   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
-   - `artifacts`: list of all artifacts with their status and dependencies
-
-4. **Create artifacts in sequence until apply-ready**
-
-   Use the **TodoWrite tool** to track progress through the artifacts.
-
-   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
-
-   a. **For each artifact that is `ready` (dependencies satisfied)**:
-      - Get instructions:
-        ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
-        ```
-      - The instructions JSON includes:
-        - `context`: Project background (constraints for you - do NOT include in output)
-        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
-        - `template`: The structure to use for your output file
-        - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
-        - `dependencies`: Completed artifacts to read for context
-      - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
-      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
-      - Show brief progress: "✓ Created <artifact-id>"
-
-   b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
-      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
-      - Stop when all `applyRequires` artifacts are done
-
-   c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
-      - Then continue with creation
-
-5. **Show final status**
-   ```bash
-   openspec status --change "<name>"
-   ```
-
-**Output**
-
-After completing all artifacts, summarize:
-- Change name and location
-- List of artifacts created with brief descriptions
-- What's ready: "All artifacts created! Ready for implementation."
-- Prompt: "Run `/opsx:apply` to start implementing."
-
-**Artifact Creation Guidelines**
-
-- Follow the `instruction` field from `openspec instructions` for each artifact type
-- The schema defines what each artifact should contain - follow it
-- Read dependency artifacts for context before creating new ones
-- Use the `template` as a starting point, filling in based on context
-
-**Guardrails**
-- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
-- Always read dependency artifacts before creating a new one
-- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
-- If a change with that name already exists, ask if user wants to continue it or create a new one
-- Verify each artifact file exists after writing before proceeding to next

.codex/prompts/opsx-new.md

@@ -1,67 +0,0 @@
----
-description: Start a new change using the experimental artifact workflow (OPSX)
-argument-hint: command arguments
----
-
-Start a new change using the experimental artifact-driven approach.
-
-**Input**: The argument after `/opsx:new` is the change name (kebab-case), OR a description of what the user wants to build.
-
-**Steps**
-
-1. **If no input provided, ask what they want to build**
-
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
-   > "What change do you want to work on? Describe what you want to build or fix."
-
-   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
-
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
-
-2. **Determine the workflow schema**
-
-   Use the default schema (omit `--schema`) unless the user explicitly requests a different workflow.
-
-   **Use a different schema only if the user mentions:**
-   - A specific schema name → use `--schema <name>`
-   - "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
-
-   **Otherwise**: Omit `--schema` to use the default.
-
-3. **Create the change directory**
-   ```bash
-   openspec new change "<name>"
-   ```
-   Add `--schema <name>` only if the user requested a specific workflow.
-   This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
-
-4. **Show the artifact status**
-   ```bash
-   openspec status --change "<name>"
-   ```
-   This shows which artifacts need to be created and which are ready (dependencies satisfied).
-
-5. **Get instructions for the first artifact**
-   The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".
-   ```bash
-   openspec instructions <first-artifact-id> --change "<name>"
-   ```
-   This outputs the template and context for creating the first artifact.
-
-6. **STOP and wait for user direction**
-
-**Output**
-
-After completing the steps, summarize:
-- Change name and location
-- Schema/workflow being used and its artifact sequence
-- Current status (0/N artifacts complete)
-- The template for the first artifact
-- Prompt: "Ready to create the first artifact? Run `/opsx:continue` or just describe what this change is about and I'll draft it."
-
-**Guardrails**
-- Do NOT create any artifacts yet - just show the instructions
-- Do NOT advance beyond showing the first artifact template
-- If the name is invalid (not kebab-case), ask for a valid name
-- If a change with that name already exists, suggest using `/opsx:continue` instead
-- Pass --schema if using a non-default workflow

.codex/prompts/opsx-onboard.md

@@ -1,523 +0,0 @@
----
-description: Guided onboarding - walk through a complete OpenSpec workflow cycle with narration
-argument-hint: command arguments
----
-
-Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
-
----
-
-## Preflight
-
-Before starting, check if OpenSpec is initialized:
-
-```bash
-openspec status --json 2>&1 || echo "NOT_INITIALIZED"
-```
-
-**If not initialized:**
-> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`.
-
-Stop here if not initialized.
-
----
-
-## Phase 1: Welcome
-
-Display:
-
-```
-## Welcome to OpenSpec!
-
-I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
-
-**What we'll do:**
-1. Pick a small, real task in your codebase
-2. Explore the problem briefly
-3. Create a change (the container for our work)
-4. Build the artifacts: proposal → specs → design → tasks
-5. Implement the tasks
-6. Archive the completed change
-
-**Time:** ~15-20 minutes
-
-Let's start by finding something to work on.
-```
-
----
-
-## Phase 2: Task Selection
-
-### Codebase Analysis
-
-Scan the codebase for small improvement opportunities. Look for:
-
-1. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files
-2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch
-3. **Functions without tests** - Cross-reference `src/` with test directories
-4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)
-5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code
-6. **Missing validation** - User input handlers without validation
-
-Also check recent git activity:
-```bash
-git log --oneline -10 2>/dev/null || echo "No git history"
-```
-
-### Present Suggestions
-
-From your analysis, present 3-4 specific suggestions:
-
-```
-## Task Suggestions
-
-Based on scanning your codebase, here are some good starter tasks:
-
-**1. [Most promising task]**
-   Location: `src/path/to/file.ts:42`
-   Scope: ~1-2 files, ~20-30 lines
-   Why it's good: [brief reason]
-
-**2. [Second task]**
-   Location: `src/another/file.ts`
-   Scope: ~1 file, ~15 lines
-   Why it's good: [brief reason]
-
-**3. [Third task]**
-   Location: [location]
-   Scope: [estimate]
-   Why it's good: [brief reason]
-
-**4. Something else?**
-   Tell me what you'd like to work on.
-
-Which task interests you? (Pick a number or describe your own)
-```
-
-**If nothing found:** Fall back to asking what the user wants to build:
-> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
-
-### Scope Guardrail
-
-If the user picks or describes something too large (major feature, multi-day work):
-
-```
-That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.
-
-For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
-
-**Options:**
-1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
-2. **Pick something else** - One of the other suggestions, or a different small task?
-3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
-
-What would you prefer?
-```
-
-Let the user override if they insist—this is a soft guardrail.
-
----
-
-## Phase 3: Explore Demo
-
-Once a task is selected, briefly demonstrate explore mode:
-
-```
-Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
-```
-
-Spend 1-2 minutes investigating the relevant code:
-- Read the file(s) involved
-- Draw a quick ASCII diagram if it helps
-- Note any considerations
-
-```
-## Quick Exploration
-
-[Your brief analysis—what you found, any considerations]
-
-┌─────────────────────────────────────────┐
-│   [Optional: ASCII diagram if helpful]  │
-└─────────────────────────────────────────┘
-
-Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
-
-Now let's create a change to hold our work.
-```
-
-**PAUSE** - Wait for user acknowledgment before proceeding.
-
----
-
-## Phase 4: Create the Change
-
-**EXPLAIN:**
-```
-## Creating a Change
-
-A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
-
-Let me create one for our task.
-```
-
-**DO:** Create the change with a derived kebab-case name:
-```bash
-openspec new change "<derived-name>"
-```
-
-**SHOW:**
-```
-Created: `openspec/changes/<name>/`
-
-The folder structure:
-```
-openspec/changes/<name>/
-├── proposal.md    ← Why we're doing this (empty, we'll fill it)
-├── design.md      ← How we'll build it (empty)
-├── specs/         ← Detailed requirements (empty)
-└── tasks.md       ← Implementation checklist (empty)
-```
-
-Now let's fill in the first artifact—the proposal.
-```
-
----
-
-## Phase 5: Proposal
-
-**EXPLAIN:**
-```
-## The Proposal
-
-The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
-
-I'll draft one based on our task.
-```
-
-**DO:** Draft the proposal content (don't save yet):
-
-```
-Here's a draft proposal:
-
----
-
-## Why
-
-[1-2 sentences explaining the problem/opportunity]
-
-## What Changes
-
-[Bullet points of what will be different]
-
-## Capabilities
-
-### New Capabilities
-- `<capability-name>`: [brief description]
-
-### Modified Capabilities
-<!-- If modifying existing behavior -->
-
-## Impact
-
-- `src/path/to/file.ts`: [what changes]
-- [other files if applicable]
-
----
-
-Does this capture the intent? I can adjust before we save it.
-```
-
-**PAUSE** - Wait for user approval/feedback.
-
-After approval, save the proposal:
-```bash
-openspec instructions proposal --change "<name>" --json
-```
-Then write the content to `openspec/changes/<name>/proposal.md`.
-
-```
-Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
-
-Next up: specs.
-```
-
----
-
-## Phase 6: Specs
-
-**EXPLAIN:**
-```
-## Specs
-
-Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.
-
-For a small task like this, we might only need one spec file.
-```
-
-**DO:** Create the spec file:
-```bash
-mkdir -p openspec/changes/<name>/specs/<capability-name>
-```
-
-Draft the spec content:
-
-```
-Here's the spec:
-
----
-
-## ADDED Requirements
-
-### Requirement: <Name>
-
-<Description of what the system should do>
-
-#### Scenario: <Scenario name>
-
-- **WHEN** <trigger condition>
-- **THEN** <expected outcome>
-- **AND** <additional outcome if needed>
-
----
-
-This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
-```
-
-Save to `openspec/changes/<name>/specs/<capability>/spec.md`.
-
----
-
-## Phase 7: Design
-
-**EXPLAIN:**
-```
-## Design
-
-The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
-
-For small changes, this might be brief. That's fine—not every change needs deep design discussion.
-```
-
-**DO:** Draft design.md:
-
-```
-Here's the design:
-
----
-
-## Context
-
-[Brief context about the current state]
-
-## Goals / Non-Goals
-
-**Goals:**
-- [What we're trying to achieve]
-
-**Non-Goals:**
-- [What's explicitly out of scope]
-
-## Decisions
-
-### Decision 1: [Key decision]
-
-[Explanation of approach and rationale]
-
----
-
-For a small task, this captures the key decisions without over-engineering.
-```
-
-Save to `openspec/changes/<name>/design.md`.
-
----
-
-## Phase 8: Tasks
-
-**EXPLAIN:**
-```
-## Tasks
-
-Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
-
-These should be small, clear, and in logical order.
-```
-
-**DO:** Generate tasks based on specs and design:
-
-```
-Here are the implementation tasks:
-
----
-
-## 1. [Category or file]
-
-- [ ] 1.1 [Specific task]
-- [ ] 1.2 [Specific task]
-
-## 2. Verify
-
-- [ ] 2.1 [Verification step]
-
----
-
-Each checkbox becomes a unit of work in the apply phase. Ready to implement?
-```
-
-**PAUSE** - Wait for user to confirm they're ready to implement.
-
-Save to `openspec/changes/<name>/tasks.md`.
-
----
-
-## Phase 9: Apply (Implementation)
-
-**EXPLAIN:**
-```
-## Implementation
-
-Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
-```
-
-**DO:** For each task:
-
-1. Announce: "Working on task N: [description]"
-2. Implement the change in the codebase
-3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
-4. Mark complete in tasks.md: `- [ ]` → `- [x]`
-5. Brief status: "✓ Task N complete"
-
-Keep narration light—don't over-explain every line of code.
-
-After all tasks:
-
-```
-## Implementation Complete
-
-All tasks done:
-- [x] Task 1
-- [x] Task 2
-- [x] ...
-
-The change is implemented! One more step—let's archive it.
-```
-
----
-
-## Phase 10: Archive
-
-**EXPLAIN:**
-```
-## Archiving
-
-When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
-
-Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
-```
-
-**DO:**
-```bash
-openspec archive "<name>"
-```
-
-**SHOW:**
-```
-Archived to: `openspec/changes/archive/YYYY-MM-DD-<name>/`
-
-The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
-```
-
----
-
-## Phase 11: Recap & Next Steps
-
-```
-## Congratulations!
-
-You just completed a full OpenSpec cycle:
-
-1. **Explore** - Thought through the problem
-2. **New** - Created a change container
-3. **Proposal** - Captured WHY
-4. **Specs** - Defined WHAT in detail
-5. **Design** - Decided HOW
-6. **Tasks** - Broke it into steps
-7. **Apply** - Implemented the work
-8. **Archive** - Preserved the record
-
-This same rhythm works for any size change—a small fix or a major feature.
-
----
-
-## Command Reference
-
-| Command | What it does |
-|---------|--------------|
-| `/opsx:explore` | Think through problems before/during work |
-| `/opsx:new` | Start a new change, step through artifacts |
-| `/opsx:ff` | Fast-forward: create all artifacts at once |
-| `/opsx:continue` | Continue working on an existing change |
-| `/opsx:apply` | Implement tasks from a change |
-| `/opsx:verify` | Verify implementation matches artifacts |
-| `/opsx:archive` | Archive a completed change |
-
----
-
-## What's Next?
-
-Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now!
-```
-
----
-
-## Graceful Exit Handling
-
-### User wants to stop mid-way
-
-If the user says they need to stop, want to pause, or seem disengaged:
-
-```
-No problem! Your change is saved at `openspec/changes/<name>/`.
-
-To pick up where we left off later:
-- `/opsx:continue <name>` - Resume artifact creation
-- `/opsx:apply <name>` - Jump to implementation (if tasks exist)
-
-The work won't be lost. Come back whenever you're ready.
-```
-
-Exit gracefully without pressure.
-
-### User just wants command reference
-
-If the user says they just want to see the commands or skip the tutorial:
-
-```
-## OpenSpec Quick Reference
-
-| Command | What it does |
-|---------|--------------|
-| `/opsx:explore` | Think through problems (no code changes) |
-| `/opsx:new <name>` | Start a new change, step by step |
-| `/opsx:ff <name>` | Fast-forward: all artifacts at once |
-| `/opsx:continue <name>` | Continue an existing change |
-| `/opsx:apply <name>` | Implement tasks |
-| `/opsx:verify <name>` | Verify implementation |
-| `/opsx:archive <name>` | Archive when done |
-
-Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast.
-```
-
-Exit gracefully.
-
----
-
-## Guardrails
-
-- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
-- **Keep narration light** during implementation—teach without lecturing
-- **Don't skip phases** even if the change is small—the goal is teaching the workflow
-- **Pause for acknowledgment** at marked points, but don't over-pause
-- **Handle exits gracefully**—never pressure the user to continue
-- **Use real codebase tasks**—don't simulate or use fake examples
-- **Adjust scope gently**—guide toward smaller tasks but respect user choice

.codex/prompts/opsx-sync.md

@@ -1,132 +0,0 @@
----
-description: Sync delta specs from a change to main specs
-argument-hint: command arguments
----
-
-Sync delta specs from a change to main specs.
-
-This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
-
-**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show changes that have delta specs (under `specs/` directory).
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Find delta specs**
-
-   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
-
-   Each delta spec file contains sections like:
-   - `## ADDED Requirements` - New requirements to add
-   - `## MODIFIED Requirements` - Changes to existing requirements
-   - `## REMOVED Requirements` - Requirements to remove
-   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
-
-   If no delta specs found, inform user and stop.
-
-3. **For each delta spec, apply changes to main specs**
-
-   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
-
-   a. **Read the delta spec** to understand the intended changes
-
-   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
-
-   c. **Apply changes intelligently**:
-
-      **ADDED Requirements:**
-      - If requirement doesn't exist in main spec → add it
-      - If requirement already exists → update it to match (treat as implicit MODIFIED)
-
-      **MODIFIED Requirements:**
-      - Find the requirement in main spec
-      - Apply the changes - this can be:
-        - Adding new scenarios (don't need to copy existing ones)
-        - Modifying existing scenarios
-        - Changing the requirement description
-      - Preserve scenarios/content not mentioned in the delta
-
-      **REMOVED Requirements:**
-      - Remove the entire requirement block from main spec
-
-      **RENAMED Requirements:**
-      - Find the FROM requirement, rename to TO
-
-   d. **Create new main spec** if capability doesn't exist yet:
-      - Create `openspec/specs/<capability>/spec.md`
-      - Add Purpose section (can be brief, mark as TBD)
-      - Add Requirements section with the ADDED requirements
-
-4. **Show summary**
-
-   After applying all changes, summarize:
-   - Which capabilities were updated
-   - What changes were made (requirements added/modified/removed/renamed)
-
-**Delta Spec Format Reference**
-
-```markdown
-## ADDED Requirements
-
-### Requirement: New Feature
-The system SHALL do something new.
-
-#### Scenario: Basic case
-- **WHEN** user does X
-- **THEN** system does Y
-
-## MODIFIED Requirements
-
-### Requirement: Existing Feature
-#### Scenario: New scenario to add
-- **WHEN** user does A
-- **THEN** system does B
-
-## REMOVED Requirements
-
-### Requirement: Deprecated Feature
-
-## RENAMED Requirements
-
-- FROM: `### Requirement: Old Name`
-- TO: `### Requirement: New Name`
-```
-
-**Key Principle: Intelligent Merging**
-
-Unlike programmatic merging, you can apply **partial updates**:
-- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
-- The delta represents *intent*, not a wholesale replacement
-- Use your judgment to merge changes sensibly
-
-**Output On Success**
-
-```
-## Specs Synced: <change-name>
-
-Updated main specs:
-
-**<capability-1>**:
-- Added requirement: "New Feature"
-- Modified requirement: "Existing Feature" (added 1 scenario)
-
-**<capability-2>**:
-- Created new spec file
-- Added requirement: "Another Feature"
-
-Main specs are now updated. The change remains active - archive when implementation is complete.
-```
-
-**Guardrails**
-- Read both delta and main specs before making changes
-- Preserve existing content not mentioned in delta
-- If something is unclear, ask for clarification
-- Show what you're changing as you go
-- The operation should be idempotent - running twice should give same result

.codex/prompts/opsx-verify.md

@@ -1,162 +0,0 @@
----
-description: Verify implementation matches change artifacts before archiving
-argument-hint: command arguments
----
-
-Verify that an implementation matches the change artifacts (specs, tasks, design).
-
-**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show changes that have implementation tasks (tasks artifact exists).
-   Include the schema used for each change if available.
-   Mark changes with incomplete tasks as "(In Progress)".
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check status to understand the schema**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used (e.g., "spec-driven")
-   - Which artifacts exist for this change
-
-3. **Get the change directory and load artifacts**
-
-   ```bash
-   openspec instructions apply --change "<name>" --json
-   ```
-
-   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
-
-4. **Initialize verification report structure**
-
-   Create a report structure with three dimensions:
-   - **Completeness**: Track tasks and spec coverage
-   - **Correctness**: Track requirement implementation and scenario coverage
-   - **Coherence**: Track design adherence and pattern consistency
-
-   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
-
-5. **Verify Completeness**
-
-   **Task Completion**:
-   - If tasks.md exists in contextFiles, read it
-   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
-   - Count complete vs total tasks
-   - If incomplete tasks exist:
-     - Add CRITICAL issue for each incomplete task
-     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
-
-   **Spec Coverage**:
-   - If delta specs exist in `openspec/changes/<name>/specs/`:
-     - Extract all requirements (marked with "### Requirement:")
-     - For each requirement:
-       - Search codebase for keywords related to the requirement
-       - Assess if implementation likely exists
-     - If requirements appear unimplemented:
-       - Add CRITICAL issue: "Requirement not found: <requirement name>"
-       - Recommendation: "Implement requirement X: <description>"
-
-6. **Verify Correctness**
-
-   **Requirement Implementation Mapping**:
-   - For each requirement from delta specs:
-     - Search codebase for implementation evidence
-     - If found, note file paths and line ranges
-     - Assess if implementation matches requirement intent
-     - If divergence detected:
-       - Add WARNING: "Implementation may diverge from spec: <details>"
-       - Recommendation: "Review <file>:<lines> against requirement X"
-
-   **Scenario Coverage**:
-   - For each scenario in delta specs (marked with "#### Scenario:"):
-     - Check if conditions are handled in code
-     - Check if tests exist covering the scenario
-     - If scenario appears uncovered:
-       - Add WARNING: "Scenario not covered: <scenario name>"
-       - Recommendation: "Add test or implementation for scenario: <description>"
-
-7. **Verify Coherence**
-
-   **Design Adherence**:
-   - If design.md exists in contextFiles:
-     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
-     - Verify implementation follows those decisions
-     - If contradiction detected:
-       - Add WARNING: "Design decision not followed: <decision>"
-       - Recommendation: "Update implementation or revise design.md to match reality"
-   - If no design.md: Skip design adherence check, note "No design.md to verify against"
-
-   **Code Pattern Consistency**:
-   - Review new code for consistency with project patterns
-   - Check file naming, directory structure, coding style
-   - If significant deviations found:
-     - Add SUGGESTION: "Code pattern deviation: <details>"
-     - Recommendation: "Consider following project pattern: <example>"
-
-8. **Generate Verification Report**
-
-   **Summary Scorecard**:
-   ```
-   ## Verification Report: <change-name>
-
-   ### Summary
-   | Dimension    | Status           |
-   |--------------|------------------|
-   | Completeness | X/Y tasks, N reqs|
-   | Correctness  | M/N reqs covered |
-   | Coherence    | Followed/Issues  |
-   ```
-
-   **Issues by Priority**:
-
-   1. **CRITICAL** (Must fix before archive):
-      - Incomplete tasks
-      - Missing requirement implementations
-      - Each with specific, actionable recommendation
-
-   2. **WARNING** (Should fix):
-      - Spec/design divergences
-      - Missing scenario coverage
-      - Each with specific recommendation
-
-   3. **SUGGESTION** (Nice to fix):
-      - Pattern inconsistencies
-      - Minor improvements
-      - Each with specific recommendation
-
-   **Final Assessment**:
-   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
-   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
-   - If all clear: "All checks passed. Ready for archive."
-
-**Verification Heuristics**
-
-- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
-- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
-- **Coherence**: Look for glaring inconsistencies, don't nitpick style
-- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
-- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
-
-**Graceful Degradation**
-
-- If only tasks.md exists: verify task completion only, skip spec/design checks
-- If tasks + specs exist: verify completeness and correctness, skip design
-- If full artifacts: verify all three dimensions
-- Always note which checks were skipped and why
-
-**Output Format**
-
-Use clear markdown with:
-- Table for summary scorecard
-- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
-- Code references in format: `file.ts:123`
-- Specific, actionable recommendations
-- No vague suggestions like "consider reviewing"

.codex/skills/export-datasource/SKILL.md

@@ -1,198 +0,0 @@
----
-name: export-datasource
-description: Project-specific guide for implementing, modifying, or reviewing export data sources in junhong_cmp_fiber. Use when Codex needs to add a new export scene, extend filters or dynamic columns, register an export scene, change export task query behavior, or explain/debug the DataSource-based export system.
----
-
-# Export Datasource
-
-Use this skill to work on this project's DataSource-based export system. It covers developer-facing export scene implementation, not one-off manual export operations.
-
-## First Reads
-
-Before editing export code, read the relevant current files:
-
-- `internal/exporter/datasource.go`
-- `internal/exporter/query_params.go`
-- `internal/exporter/filter_helpers.go`
-- `internal/exporter/registry.go`
-- Existing scene closest to the new scene:
-  - `internal/exporter/device_scene.go`
-  - `internal/exporter/iot_card_scene.go`
-- For request/scene validation:
-  - `internal/model/dto/export_task_dto.go`
-  - `pkg/constants/constants.go`
-- For behavior across worker stages:
-  - `internal/task/export_dispatch.go`
-  - `internal/task/export_shard.go`
-  - `internal/task/export_finalize.go`
-
-Read `references/export-scene-template.md` when adding a new scene or when a concrete code skeleton is useful.
-
-## Mental Model
-
-The framework owns async execution, sharding, file generation, OSS upload, and download URLs. A scene implementation owns only data semantics:
-
-```go
-type DataSource interface {
-    Scene() string
-    Count(ctx context.Context, params ExportParams) (int, error)
-    Headers(ctx context.Context, params ExportParams) ([]string, error)
-    Fetch(ctx context.Context, params ExportParams, offset, limit int) ([][]string, error)
-}
-```
-
-Execution flow:
-
-1. Admin API creates `tb_export_task` and enqueues `export:dispatch`.
-2. Dispatch parses `query_json.filters` plus permission snapshot into `ExportParams`.
-3. Dispatch calls `Headers` once and stores `query_json.resolved_headers`.
-4. Dispatch calls `Count` and creates `tb_export_shard_task` rows with `shard_offset` and `shard_limit`.
-5. Shard calls `Fetch`, writes headerless CSV shard files, and uploads them.
-6. Finalize downloads shard CSV files in shard order, writes one header row, uploads final CSV or converts CSV to XLSX.
-
-Do not reintroduce keyset cursor logic. New scenes must use offset/limit through `Fetch`.
-
-## Implementation Workflow
-
-1. Add a scene constant in `pkg/constants/constants.go`.
-2. Update `internal/model/dto/export_task_dto.go` validation and descriptions for `scene`.
-3. Implement `internal/exporter/<scene>_scene.go` with `DataSource`.
-4. Register the source in `NewDefaultRegistry`.
-5. Update `IsSupportedScene` if it is used by the current code path.
-6. Add or update migrations only if the exported domain needs schema/index changes. Do not change export task tables unless the framework contract changes.
-7. Build and manually verify. This repository forbids automated tests unless the user explicitly requests them.
-
-## DataSource Rules
-
-- `Scene` must return the constant, not a string literal.
-- `Count` and `Fetch` must apply the same filters and permission scope.
-- `Headers` defines the exact column contract for the whole task. Dispatch stores it once; shards and finalize reuse it.
-- `Fetch` must return rows aligned to `Headers`; the framework pads/truncates as a fallback, but the source should be correct.
-- `Fetch` must use stable ordering, normally `ORDER BY id ASC`.
-- Return string values only. Format time as `2006-01-02 15:04:05` unless the surrounding scene establishes another convention.
-- Use GORM only. Do not use `database/sql`.
-- Keep SQL parameters bound through GORM placeholders. Do not concatenate user-controlled values into SQL.
-- Keep comments, logs, errors, and documentation in Chinese per project rules.
-
-## Filters And Permissions
-
-Incoming task query shape:
-
-```json
-{
-  "filters": {
-    "status": 1,
-    "shop_id": 1
-  }
-}
-```
-
-`ParseExportParams` exposes:
-
-- `Filters`: `query_json.filters`
-- `ScopeShopIDs`: shop permission snapshot captured at task creation
-- `UserType`: creator user type snapshot
-
-Apply permission scope inside each DataSource:
-
-```go
-query = applyExportShopScope(query, params, "shop_id")
-```
-
-For aliased queries:
-
-```go
-query = applyExportShopScope(query, params, "o.shop_id")
-```
-
-Use helpers from `filter_helpers.go`:
-
-- `filterInt`
-- `filterUint`
-- `filterString`
-- `filterBool`
-- `filterTime`
-- `formatOptionalUint`
-- `formatOptionalTime`
-
-Do not read live permissions from context inside a DataSource. Export tasks must use the permission snapshot stored at creation time.
-
-## Dynamic Columns
-
-Use dynamic headers only when the task parameters or data require it. If `Headers` changes based on filters, `Fetch` must produce the same shape for every shard under the same `ExportParams`.
-
-Example pattern:
-
-```go
-headers := []string{"ID", "ICCID", "状态"}
-if filterBool(params.Filters, "with_package") {
-    headers = append(headers, "套餐名称", "套餐状态")
-}
-return headers, nil
-```
-
-## Join Queries
-
-JOIN-based exports are allowed. Keep these constraints:
-
-- Preserve one output row per intended exported entity unless the scene explicitly exports detail rows.
-- If a JOIN can multiply rows, make `Count` match the exported row semantics exactly.
-- Use table aliases consistently in filters and scope columns.
-- Prefer explicit `Select` into a local row struct for multi-table exports.
-- Keep `Order`, `Limit`, and `Offset` on the final query used by `Fetch`.
-
-## User-Facing API Notes
-
-Current API group:
-
-- `POST /api/admin/export-tasks`
-- `GET /api/admin/export-tasks`
-- `GET /api/admin/export-tasks/:id`
-- `POST /api/admin/export-tasks/:id/cancel`
-
-Creation request:
-
-```json
-{
-  "scene": "iot_card",
-  "format": "csv",
-  "query": {
-    "filters": {
-      "shop_id": 1,
-      "with_package": true
-    }
-  }
-}
-```
-
-Formats are `csv` and `xlsx`. Final download URLs are returned from task detail after completion.
-
-## Verification
-
-This project forbids automated tests and `_test.go` files unless the user explicitly asks for tests. Use manual verification:
-
-```bash
-go build ./internal/exporter/...
-go build ./internal/task/...
-go build ./...
-```
-
-Then create an export task through the API and inspect:
-
-- `tb_export_task.query_json` contains original `filters` and generated `resolved_headers`.
-- `tb_export_task.total_rows` matches the filtered query.
-- `tb_export_shard_task.shard_offset` and `shard_limit` are filled.
-- Shards reach success and final task reaches completed status.
-- Downloaded file has one header row, expected row count, correct filtering, and valid CSV/XLSX format.
-
-Use PostgreSQL MCP/manual SQL for data validation when needed.
-
-## Common Mistakes
-
-- Updating only `Fetch` and forgetting `Count`, causing wrong shard planning.
-- Returning dynamic rows whose column count does not match `Headers`.
-- Filtering by requested `shop_id` without also applying `ScopeShopIDs`.
-- Using context/user middleware inside worker DataSource logic.
-- Registering the source but forgetting DTO `oneof`, so API rejects the new scene.
-- Writing XLSX shard files. Shards should be CSV; finalize handles final format.
-- Adding automated tests despite the repository ban.

.codex/skills/export-datasource/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "导出数据源开发"
-  short_description: "指导新增和维护项目导出数据源场景"
-  default_prompt: "Use $export-datasource to add a new export scene for this project."

.codex/skills/export-datasource/references/export-scene-template.md

@@ -1,222 +0,0 @@
-# Export Scene Template
-
-Use this reference when adding a new export scene.
-
-## Minimal Checklist
-
-- Add `ExportTaskSceneXxx` in `pkg/constants/constants.go`.
-- Add the scene to `CreateExportTaskRequest.Scene` and `ListExportTaskRequest.Scene` validation/description.
-- Create `internal/exporter/<scene>_scene.go`.
-- Register `NewXxxDataSource(db)` in `internal/exporter/registry.go`.
-- Update `IsSupportedScene`.
-- Run `gofmt` on changed Go files.
-- Run `go build ./internal/exporter/...`, `go build ./internal/task/...`, and `go build ./...`.
-- Manually create a task and validate database rows plus downloaded file.
-
-## Skeleton
-
-```go
-package exporter
-
-import (
-    "context"
-    "strconv"
-
-    "gorm.io/gorm"
-
-    "github.com/break/junhong_cmp_fiber/internal/model"
-    "github.com/break/junhong_cmp_fiber/pkg/constants"
-)
-
-// XxxDataSource Xxx 导出数据源。
-type XxxDataSource struct {
-    db *gorm.DB
-}
-
-// NewXxxDataSource 创建 Xxx 导出数据源。
-func NewXxxDataSource(db *gorm.DB) *XxxDataSource {
-    return &XxxDataSource{db: db}
-}
-
-// Scene 返回导出场景编码。
-func (s *XxxDataSource) Scene() string {
-    return constants.ExportTaskSceneXxx
-}
-
-// Count 统计 Xxx 导出行数。
-func (s *XxxDataSource) Count(ctx context.Context, params ExportParams) (int, error) {
-    var total int64
-    query := s.applyFilters(s.db.WithContext(ctx).Model(&model.Xxx{}), params)
-    if err := query.Count(&total).Error; err != nil {
-        return 0, err
-    }
-    return int(total), nil
-}
-
-// Headers 返回 Xxx 导出表头。
-func (s *XxxDataSource) Headers(ctx context.Context, params ExportParams) ([]string, error) {
-    return []string{"ID", "名称", "状态", "店铺ID", "创建时间"}, nil
-}
-
-// Fetch 按 offset/limit 查询 Xxx 导出数据。
-func (s *XxxDataSource) Fetch(ctx context.Context, params ExportParams, offset, limit int) ([][]string, error) {
-    if limit <= 0 {
-        return [][]string{}, nil
-    }
-
-    var items []model.Xxx
-    query := s.applyFilters(s.db.WithContext(ctx).Model(&model.Xxx{}), params).
-        Order("id ASC").
-        Limit(limit).
-        Offset(offset)
-    if err := query.Find(&items).Error; err != nil {
-        return nil, err
-    }
-
-    rows := make([][]string, 0, len(items))
-    for _, item := range items {
-        rows = append(rows, []string{
-            strconv.FormatUint(uint64(item.ID), 10),
-            item.Name,
-            strconv.Itoa(item.Status),
-            formatOptionalUint(item.ShopID),
-            item.CreatedAt.Format(exportTimeLayout),
-        })
-    }
-    return rows, nil
-}
-
-func (s *XxxDataSource) applyFilters(query *gorm.DB, params ExportParams) *gorm.DB {
-    query = applyExportShopScope(query, params, "shop_id")
-
-    if status, ok := filterInt(params.Filters, "status"); ok {
-        query = query.Where("status = ?", status)
-    }
-    if shopID, ok := filterUint(params.Filters, "shop_id"); ok {
-        query = query.Where("shop_id = ?", shopID)
-    }
-    if start, ok := filterTime(params.Filters, "created_at_start"); ok {
-        query = query.Where("created_at >= ?", start)
-    }
-    if end, ok := filterTime(params.Filters, "created_at_end"); ok {
-        query = query.Where("created_at <= ?", end)
-    }
-    return query
-}
-```
-
-## JOIN Skeleton
-
-Use this shape for multi-table exports:
-
-```go
-type xxxExportRow struct {
-    ID        uint
-    Name      string
-    Status    int
-    ShopID    *uint
-    ExtraName string
-    CreatedAt time.Time
-}
-
-func (s *XxxDataSource) Fetch(ctx context.Context, params ExportParams, offset, limit int) ([][]string, error) {
-    if limit <= 0 {
-        return [][]string{}, nil
-    }
-
-    var items []xxxExportRow
-    query := s.applyFilters(s.db.WithContext(ctx).Table("tb_xxx AS x"), params, "x.").
-        Select(`
-            x.id,
-            x.name,
-            x.status,
-            x.shop_id,
-            COALESCE(e.name, '') AS extra_name,
-            x.created_at
-        `).
-        Joins("LEFT JOIN tb_extra AS e ON e.xxx_id = x.id AND e.deleted_at IS NULL").
-        Where("x.deleted_at IS NULL").
-        Order("x.id ASC").
-        Limit(limit).
-        Offset(offset)
-    if err := query.Scan(&items).Error; err != nil {
-        return nil, err
-    }
-
-    rows := make([][]string, 0, len(items))
-    for _, item := range items {
-        rows = append(rows, []string{
-            strconv.FormatUint(uint64(item.ID), 10),
-            item.Name,
-            strconv.Itoa(item.Status),
-            formatOptionalUint(item.ShopID),
-            item.ExtraName,
-            item.CreatedAt.Format(exportTimeLayout),
-        })
-    }
-    return rows, nil
-}
-
-func (s *XxxDataSource) applyFilters(query *gorm.DB, params ExportParams, prefix string) *gorm.DB {
-    query = applyExportShopScope(query, params, prefix+"shop_id")
-    if status, ok := filterInt(params.Filters, "status"); ok {
-        query = query.Where(prefix+"status = ?", status)
-    }
-    return query
-}
-```
-
-If the JOIN multiplies rows, update `Count` to count the same exported row set. Do not count only the base table unless `Fetch` also returns one row per base record.
-
-## Registry Patch
-
-```go
-func NewDefaultRegistry(db *gorm.DB) *Registry {
-    return NewRegistry(
-        NewDeviceDataSource(db),
-        NewIotCardDataSource(db),
-        NewXxxDataSource(db),
-    )
-}
-
-func IsSupportedScene(scene string) bool {
-    switch scene {
-    case constants.ExportTaskSceneDevice,
-        constants.ExportTaskSceneIotCard,
-        constants.ExportTaskSceneXxx:
-        return true
-    default:
-        return false
-    }
-}
-```
-
-## Manual API Smoke
-
-```bash
-curl -X POST 'http://localhost:端口/api/admin/export-tasks' \
-  -H 'Authorization: Bearer <token>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "scene": "xxx",
-    "format": "csv",
-    "query": {
-      "filters": {
-        "status": 1
-      }
-    }
-  }'
-```
-
-Check database:
-
-```sql
-SELECT id, scene, format, status, total_rows, total_shards, query_json
-FROM tb_export_task
-WHERE id = <task_id>;
-
-SELECT shard_no, status, shard_offset, shard_limit, row_count, file_key
-FROM tb_export_shard_task
-WHERE task_id = <task_id>
-ORDER BY shard_no;
-```

.codex/skills/openspec-apply-change/SKILL.md

@@ -1,160 +0,0 @@
----
-name: openspec-apply-change
-description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
-allowed-tools: Bash(openspec:*)
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.6.0"
----
-
-Implement tasks from an OpenSpec change.
-
-**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **Select the change**
-
-   If a name is provided, use it. Otherwise:
-   - Infer from conversation context if the user mentioned a change
-   - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
-
-   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
-
-2. **Check status to understand the schema**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used (e.g., "spec-driven")
-   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
-   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
-
-3. **Get apply instructions**
-
-   ```bash
-   openspec instructions apply --change "<name>" --json
-   ```
-
-   This returns:
-   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
-   - Progress (total, complete, remaining)
-   - Task list with status
-   - Dynamic instruction based on current state
-
-   **Handle states:**
-   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
-   - If `state: "all_done"`: congratulate, suggest archive
-   - Otherwise: proceed to implementation
-
-4. **Read context files**
-
-   Read every file path listed under `contextFiles` from the apply instructions output.
-   The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
-   - Other schemas: follow the contextFiles from CLI output
-
-5. **Show current progress**
-
-   Display:
-   - Schema being used
-   - Progress: "N/M tasks complete"
-   - Remaining tasks overview
-   - Dynamic instruction from CLI
-
-6. **Implement tasks (loop until done or blocked)**
-
-   For each pending task:
-   - Show which task is being worked on
-   - Make the code changes required
-   - Keep changes minimal and focused
-   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
-   - Continue to next task
-
-   **Pause if:**
-   - Task is unclear → ask for clarification
-   - Implementation reveals a design issue → suggest updating artifacts
-   - Error or blocker encountered → report and wait for guidance
-   - User interrupts
-
-7. **On completion or pause, show status**
-
-   Display:
-   - Tasks completed this session
-   - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
-   - If paused: explain why and wait for guidance
-
-**Output During Implementation**
-
-```
-## Implementing: <change-name> (schema: <schema-name>)
-
-Working on task 3/7: <task description>
-[...implementation happening...]
-✓ Task complete
-
-Working on task 4/7: <task description>
-[...implementation happening...]
-✓ Task complete
-```
-
-**Output On Completion**
-
-```
-## Implementation Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 7/7 tasks complete ✓
-
-### Completed This Session
-- [x] Task 1
-- [x] Task 2
-...
-
-All tasks complete! Ready to archive this change.
-```
-
-**Output On Pause (Issue Encountered)**
-
-```
-## Implementation Paused
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 4/7 tasks complete
-
-### Issue Encountered
-<description of the issue>
-
-**Options:**
-1. <option 1>
-2. <option 2>
-3. Other approach
-
-What would you like to do?
-```
-
-**Guardrails**
-- Keep going through tasks until done or blocked
-- Always read context files before starting (from the apply instructions output)
-- If task is ambiguous, pause and ask before implementing
-- If implementation reveals issues, pause and suggest artifact updates
-- Keep code changes minimal and scoped to each task
-- Update task checkbox immediately after completing each task
-- Pause on errors, blockers, or unclear requirements - don't guess
-- Use contextFiles from CLI output, don't assume specific file names
-
-**Fluid Workflow Integration**
-
-This skill supports the "actions on a change" model:
-
-- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
-- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

.codex/skills/openspec-archive-change/SKILL.md

@@ -1,118 +0,0 @@
----
-name: openspec-archive-change
-description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
-allowed-tools: Bash(openspec:*)
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.6.0"
----
-
-Archive a completed change in the experimental workflow.
-
-**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show only active changes (not already archived).
-   Include the schema used for each change if available.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check artifact completion status**
-
-   Run `openspec status --change "<name>" --json` to check artifact completion.
-
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used
-   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
-   - `artifacts`: List of artifacts with their status (`done` or other)
-
-   **If any artifacts are not `done`:**
-   - Display warning listing incomplete artifacts
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
-   - Proceed if user confirms
-
-3. **Check task completion status**
-
-   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
-
-   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
-
-   **If incomplete tasks found:**
-   - Display warning showing count of incomplete tasks
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
-   - Proceed if user confirms
-
-   **If no tasks file exists:** Proceed without task-related warning.
-
-4. **Assess delta spec sync state**
-
-   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
-
-   **If delta specs exist:**
-   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
-   - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
-
-   **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
-
-   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
-
-5. **Perform the archive**
-
-   Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
-   ```bash
-   mkdir -p "<planningHome.changesDir>/archive"
-   ```
-
-   Generate target name using current date: `YYYY-MM-DD-<change-name>`
-
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move `changeRoot` to the archive directory
-
-   ```bash
-   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
-   ```
-
-6. **Display summary**
-
-   Show archive completion summary including:
-   - Change name
-   - Schema that was used
-   - Archive location
-   - Whether specs were synced (if applicable)
-   - Note about any warnings (incomplete artifacts/tasks)
-
-**Output On Success**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
-**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
-
-All artifacts complete. All tasks complete.
-```
-
-**Guardrails**
-- Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
-- Don't block archive on warnings - just inform and confirm
-- Preserve .openspec.yaml when moving to archive (it moves with the directory)
-- Show clear summary of what happened
-- If sync is requested, use openspec-sync-specs approach (agent-driven)
-- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.codex/skills/openspec-explore/SKILL.md

@@ -1,290 +0,0 @@
----
-name: openspec-explore
-description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
-allowed-tools: Bash(openspec:*)
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.6.0"
----
-
-Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
-
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
-
-**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
-
-**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
-
----
-
-## The Stance
-
-- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
-- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
-- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
-- **Adaptive** - Follow interesting threads, pivot when new information emerges
-- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
-- **Grounded** - Explore the actual codebase when relevant, don't just theorize
-
----
-
-## What You Might Do
-
-Depending on what the user brings, you might:
-
-**Explore the problem space**
-- Ask clarifying questions that emerge from what they said
-- Challenge assumptions
-- Reframe the problem
-- Find analogies
-
-**Investigate the codebase**
-- Map existing architecture relevant to the discussion
-- Find integration points
-- Identify patterns already in use
-- Surface hidden complexity
-
-**Compare options**
-- Brainstorm multiple approaches
-- Build comparison tables
-- Sketch tradeoffs
-- Recommend a path (if asked)
-
-**Visualize**
-```
-┌─────────────────────────────────────────┐
-│     Use ASCII diagrams liberally        │
-├─────────────────────────────────────────┤
-│                                         │
-│      ┌────────┐         ┌────────┐      │
-│      │ State  │────────▶│ State  │      │
-│      │   A    │         │   B    │      │
-│      └────────┘         └────────┘      │
-│                                         │
-│   System diagrams, state machines,      │
-│   data flows, architecture sketches,    │
-│   dependency graphs, comparison tables  │
-│                                         │
-└─────────────────────────────────────────┘
-```
-
-**Surface risks and unknowns**
-- Identify what could go wrong
-- Find gaps in understanding
-- Suggest spikes or investigations
-
----
-
-## OpenSpec Awareness
-
-You have full context of the OpenSpec system. Use it naturally, don't force it.
-
-### Check for context
-
-At the start, quickly check what exists:
-```bash
-openspec list --json
-```
-
-This tells you:
-- If there are active changes
-- Their names, schemas, and status
-- What the user might be working on
-
-### When no change exists
-
-Think freely. When insights crystallize, you might offer:
-
-- "This feels solid enough to start a change. Want me to create a proposal?"
-- Or keep exploring - no pressure to formalize
-
-### When a change exists
-
-If the user mentions a change or you detect one is relevant:
-
-1. **Resolve and read existing artifacts for context**
-   - Run `openspec status --change "<name>" --json`.
-   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
-   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
-
-2. **Reference them naturally in conversation**
-   - "Your design mentions using Redis, but we just realized SQLite fits better..."
-   - "The proposal scopes this to premium users, but we're now thinking everyone..."
-
-3. **Offer to capture when decisions are made**
-
-    | Insight Type               | Where to Capture               |
-    |----------------------------|--------------------------------|
-    | New requirement discovered | `specs/<capability>/spec.md` |
-    | Requirement changed        | `specs/<capability>/spec.md` |
-    | Design decision made       | `design.md`                  |
-    | Scope changed              | `proposal.md`                |
-    | New work identified        | `tasks.md`                   |
-    | Assumption invalidated     | Relevant artifact              |
-
-   Example offers:
-   - "That's a design decision. Capture it in design.md?"
-   - "This is a new requirement. Add it to specs?"
-   - "This changes scope. Update the proposal?"
-
-4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
-
----
-
-## What You Don't Have To Do
-
-- Follow a script
-- Ask the same questions every time
-- Produce a specific artifact
-- Reach a conclusion
-- Stay on topic if a tangent is valuable
-- Be brief (this is thinking time)
-
----
-
-## Handling Different Entry Points
-
-**User brings a vague idea:**
-```
-User: I'm thinking about adding real-time collaboration
-
-You: Real-time collab is a big space. Let me think about this...
-
-      COLLABORATION SPECTRUM
-      ════════════════════════════════════════════
-
-      Awareness          Coordination         Sync
-          │                   │                 │
-          ▼                   ▼                 ▼
-      ┌────────┐         ┌────────┐        ┌────────┐
-      │Presence│         │Cursors │        │  CRDT  │
-      │  "3    │         │ Multi  │        │Conflict│
-      │online" │         │ select │        │  free  │
-      └────────┘         └────────┘        └────────┘
-          │                   │                 │
-       trivial            moderate           complex
-
-      Where's your head at?
-```
-
-**User brings a specific problem:**
-```
-User: The auth system is a mess
-
-You: [reads codebase]
-
-     ┌─────────────────────────────────────────────┐
-     │              CURRENT AUTH FLOW              │
-     └─────────────────────────────────────────────┘
-                        │
-          ┌─────────────┼─────────────┐
-          ▼             ▼             ▼
-     ┌─────────┐  ┌─────────┐  ┌─────────┐
-     │ Google  │  │  GitHub │  │  Email  │
-     │  OAuth  │  │  OAuth  │  │  Magic  │
-     └────┬────┘  └────┬────┘  └────┬────┘
-          │             │             │
-          └─────────────┼─────────────┘
-                        ▼
-                  ┌───────────┐
-                  │  Session  │
-                  └─────┬─────┘
-                        │
-                        ▼
-                  ┌───────────┐
-                  │   Perms   │
-                  └───────────┘
-
-     I see three tangles. Which one's burning?
-```
-
-**User is stuck mid-implementation:**
-```
-User: /opsx:explore add-auth-system
-      The OAuth integration is more complex than expected
-
-You: [reads change artifacts]
-
-     You're on task 4: "Implement OAuth flow"
-
-     Let me trace what's involved...
-
-     [draws diagram, explores options, suggests paths]
-
-     Want to update the design to reflect this?
-     Or add a spike task to investigate?
-```
-
-**User wants to compare options:**
-```
-User: Should we use Postgres or SQLite?
-
-You: Generic answer is boring. What's the context?
-
-User: A CLI tool that tracks local dev environments
-
-You: That changes everything.
-
-     ┌─────────────────────────────────────────────────┐
-     │          CLI TOOL DATA STORAGE                  │
-     └─────────────────────────────────────────────────┘
-
-     Key constraints:
-     • No daemon running
-     • Must work offline
-     • Single user
-
-                  SQLite          Postgres
-     Deployment   embedded ✓      needs server ✗
-     Offline      yes ✓           no ✗
-     Single file  yes ✓           no ✗
-
-     SQLite. Not even close.
-
-     Unless... is there a sync component?
-```
-
----
-
-## Ending Discovery
-
-There's no required ending. Discovery might:
-
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
-- **Result in artifact updates**: "Updated design.md with these decisions"
-- **Just provide clarity**: User has what they need, moves on
-- **Continue later**: "We can pick this up anytime"
-
-When it feels like things are crystallizing, you might summarize:
-
-```
-## What We Figured Out
-
-**The problem**: [crystallized understanding]
-
-**The approach**: [if one emerged]
-
-**Open questions**: [if any remain]
-
-**Next steps** (if ready):
-- Create a change proposal
-- Keep exploring: just keep talking
-```
-
-But this summary is optional. Sometimes the thinking IS the value.
-
----
-
-## Guardrails
-
-- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
-- **Don't fake understanding** - If something is unclear, dig deeper
-- **Don't rush** - Discovery is thinking time, not task time
-- **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it
-- **Do visualize** - A good diagram is worth many paragraphs
-- **Do explore the codebase** - Ground discussions in reality
-- **Do question assumptions** - Including the user's and your own

.codex/skills/openspec-propose/SKILL.md

@@ -1,114 +0,0 @@
----
-name: openspec-propose
-description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
-allowed-tools: Bash(openspec:*)
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.6.0"
----
-
-Propose a new change - create the change and generate all artifacts in one step.
-
-I'll create a change with artifacts:
-- proposal.md (what & why)
-- design.md (how)
-- tasks.md (implementation steps)
-
-When ready to implement, run /opsx:apply
-
----
-
-**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
-
-**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
-
-**Steps**
-
-1. **If no clear input provided, ask what they want to build**
-
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
-   > "What change do you want to work on? Describe what you want to build or fix."
-
-   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
-
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
-
-2. **Create the change directory**
-   ```bash
-   openspec new change "<name>"
-   ```
-   This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
-
-3. **Get the artifact build order**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to get:
-   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
-   - `artifacts`: list of all artifacts with their status and dependencies
-   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
-
-4. **Create artifacts in sequence until apply-ready**
-
-   Use the **TodoWrite tool** to track progress through the artifacts.
-
-   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
-
-   a. **For each artifact that is `ready` (dependencies satisfied)**:
-      - Get instructions:
-        ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
-        ```
-      - The instructions JSON includes:
-        - `context`: Project background (constraints for you - do NOT include in output)
-        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
-        - `template`: The structure to use for your output file
-        - `instruction`: Schema-specific guidance for this artifact type
-        - `resolvedOutputPath`: Resolved path or pattern to write the artifact
-        - `dependencies`: Completed artifacts to read for context
-      - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure and write it to `resolvedOutputPath`
-      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
-      - Show brief progress: "Created <artifact-id>"
-
-   b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
-      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
-      - Stop when all `applyRequires` artifacts are done
-
-   c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
-      - Then continue with creation
-
-5. **Show final status**
-   ```bash
-   openspec status --change "<name>"
-   ```
-
-**Output**
-
-After completing all artifacts, summarize:
-- Change name and location
-- List of artifacts created with brief descriptions
-- What's ready: "All artifacts created! Ready for implementation."
-- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
-
-**Artifact Creation Guidelines**
-
-- Follow the `instruction` field from `openspec instructions` for each artifact type
-- The schema defines what each artifact should contain - follow it
-- Read dependency artifacts for context before creating new ones
-- Use `template` as the structure for your output file - fill in its sections
-- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
-  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
-  - These guide what you write, but should never appear in the output
-
-**Guardrails**
-- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
-- Always read dependency artifacts before creating a new one
-- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
-- If a change with that name already exists, ask if user wants to continue it or create a new one
-- Verify each artifact file exists after writing before proceeding to next

.codex/skills/openspec-sync-specs/SKILL.md

@@ -1,148 +0,0 @@
----
-name: openspec-sync-specs
-description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
-allowed-tools: Bash(openspec:*)
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.6.0"
----
-
-Sync delta specs from a change to main specs.
-
-This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
-
-**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show changes that have delta specs (under `specs/` directory).
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Resolve change context**
-
-   Run:
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-
-3. **Find delta specs**
-
-   Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.
-
-   Each delta spec file contains sections like:
-   - `## ADDED Requirements` - New requirements to add
-   - `## MODIFIED Requirements` - Changes to existing requirements
-   - `## REMOVED Requirements` - Requirements to remove
-   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
-
-   If no delta specs found, inform user and stop.
-
-4. **For each delta spec, apply changes to main specs**
-
-   For each repo-local capability delta spec path returned by the CLI:
-
-   a. **Read the delta spec** to understand the intended changes
-
-   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
-
-   c. **Apply changes intelligently**:
-
-      **ADDED Requirements:**
-      - If requirement doesn't exist in main spec → add it
-      - If requirement already exists → update it to match (treat as implicit MODIFIED)
-
-      **MODIFIED Requirements:**
-      - Find the requirement in main spec
-      - Apply the changes - this can be:
-        - Adding new scenarios (don't need to copy existing ones)
-        - Modifying existing scenarios
-        - Changing the requirement description
-      - Preserve scenarios/content not mentioned in the delta
-
-      **REMOVED Requirements:**
-      - Remove the entire requirement block from main spec
-
-      **RENAMED Requirements:**
-      - Find the FROM requirement, rename to TO
-
-   d. **Create new main spec** if capability doesn't exist yet:
-      - Create `openspec/specs/<capability>/spec.md`
-      - Add Purpose section (can be brief, mark as TBD)
-      - Add Requirements section with the ADDED requirements
-
-5. **Show summary**
-
-   After applying all changes, summarize:
-   - Which capabilities were updated
-   - What changes were made (requirements added/modified/removed/renamed)
-
-**Delta Spec Format Reference**
-
-```markdown
-## ADDED Requirements
-
-### Requirement: New Feature
-The system SHALL do something new.
-
-#### Scenario: Basic case
-- **WHEN** user does X
-- **THEN** system does Y
-
-## MODIFIED Requirements
-
-### Requirement: Existing Feature
-#### Scenario: New scenario to add
-- **WHEN** user does A
-- **THEN** system does B
-
-## REMOVED Requirements
-
-### Requirement: Deprecated Feature
-
-## RENAMED Requirements
-
-- FROM: `### Requirement: Old Name`
-- TO: `### Requirement: New Name`
-```
-
-**Key Principle: Intelligent Merging**
-
-Unlike programmatic merging, you can apply **partial updates**:
-- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
-- The delta represents *intent*, not a wholesale replacement
-- Use your judgment to merge changes sensibly
-
-**Output On Success**
-
-```
-## Specs Synced: <change-name>
-
-Updated main specs:
-
-**<capability-1>**:
-- Added requirement: "New Feature"
-- Modified requirement: "Existing Feature" (added 1 scenario)
-
-**<capability-2>**:
-- Created new spec file
-- Added requirement: "Another Feature"
-
-Main specs are now updated. The change remains active - archive when implementation is complete.
-```
-
-**Guardrails**
-- Read both delta and main specs before making changes
-- Preserve existing content not mentioned in delta
-- If something is unclear, ask for clarification
-- Show what you're changing as you go
-- The operation should be idempotent - running twice should give same result

.codex/skills/openspec-update-change/SKILL.md

@@ -1,86 +0,0 @@
----
-name: openspec-update-change
-description: Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.
-allowed-tools: Bash(openspec:*)
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.6.0"
----
-
-Revise a change's existing planning artifacts and keep them coherent. Never edit code.
-
-**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
-
-   Present the top 3-4 most recently modified changes as options, showing:
-   - Change name
-   - Schema (from `schema` field if present, otherwise "spec-driven")
-   - Status (e.g., "0/5 tasks", "complete", "no tasks")
-   - How recently it was modified (from `lastModified` field)
-
-   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Get the change's artifacts**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to understand current state. The response includes:
-   - `schemaName`: The workflow schema being used (e.g., "spec-driven")
-   - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked")
-   - `isComplete`: Boolean indicating if all artifacts are complete
-   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
-
-   The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
-
-   The files to edit are `artifactPaths.<id>.existingOutputPaths` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. `specs/**/*.md`). Do NOT write to `resolvedOutputPath`: for a glob artifact it is still the glob pattern, not a real file.
-
-3. **Understand the request**
-   - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
-   - If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
-
-4. **Read and reconcile**
-   - Read the artifact(s) the request touches and the change's other existing artifacts.
-   - Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
-   - Note everything that is now inconsistent, missing, or contradictory.
-   - Revise only files that already exist (`existingOutputPaths`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to `/opsx:continue` to create them.
-   - If the change is already coherent, say so and make no edits.
-
-5. **Confirm and apply, one artifact at a time**
-   - Show each proposed revision and why. Write only after the user confirms.
-   - If the user rejects a revision, do not write it - leave that artifact unchanged.
-   - When a substantial rewrite is needed, get that artifact's rules and template first:
-     ```bash
-     openspec instructions <artifact-id> --change "<name>" --json
-     ```
-
-6. **Point to the next step (guidance only - NEVER act on it)**
-   - Artifacts still missing -> suggest `/opsx:continue` to create them.
-   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest `/opsx:apply` to carry the delta into code.
-   - Everything done and implemented -> suggest `/opsx:archive`.
-
-**Output**
-
-After each invocation, show:
-- Which artifacts were revised (and which proposed revisions were rejected)
-- Anything deferred to `/opsx:continue` (not-yet-created artifacts or files)
-- Where the change stands and the recommended next command
-
-**Guardrails**
-- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `/opsx:apply`.
-- Use the artifact ids and paths reported by `openspec status`; never branch on hardcoded artifact names.
-- Edit only the concrete files in `existingOutputPaths`; never write to a glob `resolvedOutputPath`.
-- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is `/opsx:continue`'s job.
-- Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, recommend starting fresh with `/opsx:new` (the "Update vs. Start Fresh" heuristic).

.config/dbhub.toml

@@ -1,7 +1,20 @@
 [[sources]]
 id = "main"
-description = "当前项目库"
+description = "当前项目库测试环境以及本地环境"
 dsn = "postgresql://erp_pgsql:erp_2025@cxd.whcxd.cn:16159/junhong_cmp_test?sslmode=disable"
+lazy = true
+
+
+[[sources]]
+id = "pro_main"
+description = "当前项目库正式环境"
+dsn = "postgresql://junhong_cmp:CtCom1zBzPQbpVNf3rCNxH@127.0.0.1:5432/junhong_cmp_prod?sslmode=disable"
+ssh_host = "116.162.101.91"
+ssh_port = 22
+ssh_user = "root"
+ssh_key = "~/.ssh/id_ed25519"
+lazy = true
+
 
 [[sources]]
 id = "legacy_mysql"
@@ -22,8 +35,18 @@ source = "main"
 [[tools]]
 name = "execute_sql"
 source = "main"
-readonly = true    # Only allow SELECT, SHOW, DESCRIBE, EXPLAIN
-max_rows = 1000     # Limit query results
+readonly = true      # Only allow SELECT, SHOW, DESCRIBE, EXPLAIN
+max_rows = 1000      # Limit query results
+
+[[tools]]
+name = "search_objects"
+source = "pro_main"
+
+[[tools]]
+name = "execute_sql"
+source = "pro_main"
+readonly = true
+max_rows = 1000
 
 [[tools]]
 name = "search_objects"
@@ -32,5 +55,5 @@ source = "legacy_mysql"
 [[tools]]
 name = "execute_sql"
 source = "legacy_mysql"
-readonly = true    # Only allow SELECT, SHOW, DESCRIBE, EXPLAIN
-max_rows = 5000     # Limit query results for migration exploration
+readonly = true         # Only allow SELECT, SHOW, DESCRIBE, EXPLAIN
+max_rows = 5000         # Limit query results for migration exploration

.env

@@ -5,10 +5,6 @@ DB_USER=erp_pgsql
 DB_PASSWORD=erp_2025
 DB_NAME=junhong_cmp_test
 DB_SSLMODE=disable
-GOOGLE_GEMINI_BASE_URL="http://45.155.220.179:8317"  # 根据实际填写你服务器的ip地址或者域名
-GEMINI_API_KEY="sk-VoNbvr6aGpjvZX64rvhrwowrZrCgtGuX9oxykIy8F1DBg"
-GOOGLE_GENAI_USE_GCA="true"
-GEMINI_MODEL="gemini-3-pro-preview" # 如果你有gemini3权限可以填： gemini-3-pro-preview
 
 # 七月迭代：Worker、企微 Adapter 与旧审批入口切换
 JUNHONG_WORKER_ROLE=all

.env.prod

@@ -240,6 +240,7 @@ export JUNHONG_MIDDLEWARE_CORS_ALLOW_CREDENTIALS=true
 # ----------------------------------------------------------------------------
 export JUNHONG_WORKER_ROLE='all'
 export JUNHONG_WORKER_INSTANCE_NAME='worker-all-1'
+export JUNHONG_WORKER_AUDIT_RETENTION_CLEANUP_ENABLED='false'
 export JUNHONG_WECOM_BASE_URL='https://qyapi.weixin.qq.com'
 export JUNHONG_WECOM_TIMEOUT='10s'
 export JUNHONG_APPROVAL_LEGACY_REFUND_MANUAL_ENABLED='true'

.gitea/workflows/deploy.yaml

@@ -3,9 +3,7 @@ name: 构建并部署到测试环境（无 SSH）
 on:
   push:
     branches:
-      - Iteration/7-11
-      - dev
-      - test
+      - Iteration/8-11
 
 env:
   REGISTRY: registry.boss160.cn
@@ -30,15 +28,7 @@ jobs:
       - name: 设置镜像标签
         id: tag
         run: |
-          if [ "${{ github.ref }}" = "refs/heads/Iteration/7-11" ]; then
-            echo "tag=latest" >> $GITHUB_OUTPUT
-          elif [ "${{ github.ref }}" = "refs/heads/dev" ]; then
-            echo "tag=dev" >> $GITHUB_OUTPUT
-          elif [ "${{ github.ref }}" = "refs/heads/test" ]; then
-            echo "tag=test" >> $GITHUB_OUTPUT
-          else
-            echo "tag=unknown" >> $GITHUB_OUTPUT
-          fi
+          echo "tag=${{ github.sha }}" >> $GITHUB_OUTPUT
 
       - name: 登录 Docker Registry
         run: |
@@ -47,28 +37,25 @@ jobs:
       - name: 构建 API 镜像
         run: |
           docker build -f Dockerfile.api -t ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }} .
-          docker tag ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }} ${{ env.API_IMAGE }}:${{ github.sha }}
 
       - name: 构建 Worker 镜像
         run: |
           docker build -f Dockerfile.worker -t ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }} .
-          docker tag ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }} ${{ env.WORKER_IMAGE }}:${{ github.sha }}
 
       - name: 推送镜像到 Registry
         run: |
           docker push ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }}
-          docker push ${{ env.API_IMAGE }}:${{ github.sha }}
           docker push ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }}
-          docker push ${{ env.WORKER_IMAGE }}:${{ github.sha }}
 
-      - name: 部署到本地（仅 Iteration/7-11 分支）
-        if: github.ref == 'refs/heads/Iteration/7-11'
+      - name: 部署到测试环境（仅八月迭代分支）
+        if: github.ref == 'refs/heads/Iteration/8-11'
         run: |
           # 确保部署目录存在（仅需日志目录，配置已嵌入二进制文件）
           mkdir -p ${{ env.DEPLOY_DIR }}/logs
 
           umask 077
           {
+            printf 'IMAGE_TAG=%s\n' '${{ github.sha }}'
             printf 'JUNHONG_APPROVAL_LEGACY_REFUND_MANUAL_ENABLED=true\n'
             printf 'JUNHONG_APPROVAL_LEGACY_OFFLINE_RECHARGE_PAY_ENABLED=true\n'
             printf 'JUNHONG_WORKER_ROLE=all\n'

.gitignore

@@ -110,3 +110,5 @@ docs/admin-openapi.yaml
 scripts/batch_package_purchase/assets.example_购买结果_20260715_115804.csv
 scripts/batch_package_purchase/assets.example_购买结果_20260715_115814.csv
 scripts/migration/output
+
+.scratch/go-build-cache

.planning/PROJECT.md

@@ -1,187 +0,0 @@
-# 君鸿卡管系统
-
-## What This Is
-
-物联网卡（IoT SIM）+ 号卡 + 设备全生命周期管理平台，支持多级代理商体系和分佣结算。平台以 B 端代理商为核心分销渠道，兼顾 C 端个人客户和企业客户，覆盖从卡/设备采购、分配、激活、套餐购买到佣金结算的完整业务链路。当前处于 MVP 阶段，核心功能模块已完成，目标是修复所有已知业务链路断点、补全缺失功能，将系统调整至可生产上线状态。
-
-## Core Value
-
-**业务链路完整可用**——代理能采购分配卡/设备，C端客户能充值购包激活套餐，佣金能正确计算并可提现。这条主链路必须端到端跑通。
-
-## Requirements
-
-### Validated
-
-*以下功能已在代码库中实现，视为已验证的基础能力：*
-
-**Validated in Phase 03.1: 设备 sync-info 读取链路修复**
-- ✓ 设备管理列表/详情返回 online_status/last_online_time/software_version/switch_mode/last_gateway_sync_at — DEVICE-02/03
-- ✓ 设备绑卡列表（ListBindings）返回 is_current 字段 — DEVICE-03
-- ✓ 资产 Resolve/Refresh BoundCardInfo 包含 is_current（isCurrentMap 模式） — DEVICE-03
-- ✓ admin 资产解析接口（AssetResolveResponse）返回 5 个 DB 缓存字段 — DEVICE-02/03
-- ✓ GetRealtimeStatus device 类型实时调用 Gateway sync-info，返回 DeviceGatewayInfo — DEVICE-04
-- ✓ C 端 GetAssetInfo device_realtime 从真实 Gateway 数据填充（删除 buildMockDeviceRealtime）— DEVICE-04
-- ✓ Gateway 失败降级：IMEI 为空不发起调用，失败只记 Warn，device_realtime 返回 null — DEVICE-04
-
-**Validated in Phase 2: PERM/FIN/REALNAME/POLL 修复**
-- ✓ 企业账号 Resolve 接口移除错误拦截，Refresh 接口新增拦截（只读）— PERM-01/02
-- ✓ 提现审批人字段补全（approved_by/approved_at）— FIN-01
-- ✓ 提现拒绝 remark 必填校验（Reject 补 Validate 调用）— FIN-02
-- ✓ 激活配置并发行锁保护（clause.Locking FOR UPDATE）— FIN-03
-- ✓ enable_realname_activation → expiry_base 全链路重构，三维激活决策（卡类型+购买路径+expiry_base）— REALNAME-01~05
-- ✓ polling:protect 接入调度器（processManualQueue + processTimedQueue）— POLL-01
-- ✓ gatewayClient=nil 时停复机返回业务错误而非 nil — POLL-02
-- ✓ GetPackages 接口支持分页（page/pageSize/total）— POLL-03
-- ✓ PackageSeries 删除前检查关联套餐（CountBySeriesID）— POLL-04
-
-**Validated in Phase 1: P0 紧急修复**
-- ✓ 实名状态常量统一（DB 写入值统一为 constants.RealNameStatusVerified=1）— CRITICAL-01
-- ✓ C 端实名校验修复（依赖常量统一）— CRITICAL-02
-- ✓ 实名激活任务断链修复（PollingHandler 注入 asynqClient，RPush 降级方案删除）— CRITICAL-03
-- ✓ 充值回调触发自动购包（TaskTypeAutoPurchaseAfterRecharge 入队）— CRITICAL-04
-- ✓ 自动购包后佣金链补全（TaskTypeCommission 正确触发）— CRITICAL-05
-- ✓ 代购订单 sellerCostPrice 修正（场景5使用 operatorCostPrice，6处全部审查）— CRITICAL-06
-- ✓ 设备导入补充 IMEI 字段（DeviceRow.IMEI + buildDeviceColumnIndex 多别名）— CRITICAL-07
-- ✓ 提现冻结并发校验（RowsAffected==0 检查，防止重复提现单）— CRITICAL-08
-
-- ✓ IoT 卡全生命周期管理（开卡/激活/停复机/销户）— 已实现
-- ✓ 设备管理（绑卡/解绑/批量导入 Excel）— 已实现
-- ✓ 代理商多级体系（最多 7 层层级，parent_id 维护）— 已实现
-- ✓ RBAC 权限系统（角色/权限/菜单，基于店铺层级数据过滤）— 已实现
-- ✓ B 端认证（Admin JWT + Redis Token，SuperAdmin/Platform/Agent/Enterprise）— 已实现
-- ✓ C 端认证（微信 OAuth + 手机号绑定，JWT 单独中间件）— 已实现
-- ✓ 套餐系统（主套餐/加油包/排队激活/囤货待实名激活/流量计费）— 已实现
-- ✓ 订单系统（五种购买场景，钱包/微信/富友支付）— 已实现
-- ✓ 微信支付（JSAPI + H5，PowerWeChat v3 SDK）— 已实现
-- ✓ 资产钱包（绑定卡/设备，转手后钱包跟着走）— 已实现
-- ✓ 代理佣金钱包（差价佣金 + 一次性佣金，多级分链）— 已实现
-- ✓ 代理佣金提现申请流程（申请/审批/拒绝）— 已实现（待修复）
-- ✓ 轮询系统（实名状态/流量/套餐余额，Asynq + Redis Sorted Set）— 已实现
-- ✓ 标签系统（平台/企业/店铺三级隔离）— 已实现
-- ✓ 对象存储（联通云 OSS，S3 兼容，批量导入/导出）— 已实现
-- ✓ 审计日志（账号操作：create/update/delete/assign_roles）— 已实现
-- ✓ 企业账号管理（B 端大客户，被分配卡/设备，无钱包）— 已实现（待修复权限）
-- ✓ 订单超时自动取消（Asynq Scheduler，30 分钟）— 已实现
-- ✓ 富友支付 SDK（pkg/fuiou/ 完整实现 + 回调已实现）— SDK 已实现，接口留桩待补全
-
-### Active
-
-*当前阶段需要完成的工作，来自修正业务完整方案（.sisyphus/plans/修正业务-完整方案.md）：*
-
-**方案 A — 紧急 Bug 修复（P0）** ✅ *Validated in Phase 1*
-- [x] A-1：实名状态常量统一（DB 写入值 2 vs 常量 1，所有链路断裂）
-- [x] A-2：C 端实名校验修复（依赖 A-1）
-- [x] A-3：实名激活任务断链修复（PollingHandler 缺少 asynqClient，RPush 降级）
-- [x] A-4：充值回调后自动购包触发 + 佣金补全（两个断点：无调用 + 佣金不计算）
-- [x] A-5：代购订单金额修正（场景 5 sellerCostPrice 用错字段，佣金链归零）
-- [x] A-6：设备导入补充 IMEI 字段（DeviceRow 缺 IMEI，导入后 Gateway 无法调用）
-- [x] A-7：提现冻结并发校验（只检查 Error 不检查 RowsAffected，并发创建重复提现单）
-
-**方案 B — 企业端权限完善** ✅ *Validated in Phase 2*
-- [x] B-1：Resolve 接口错误拦截企业账号（应可查，需移除拦截）
-- [x] B-2：Refresh 接口缺少企业账号拦截（应只读）
-
-**方案 C — 提现/佣金流程完善** ✅ *Validated in Phase 2*
-- [x] C-1：审批人字段补全（approved_by/approved_at 永远为空）
-- [x] C-2：提现拒绝 remark 必填校验（Reject 缺少 Validate 调用）
-- [x] C-3：激活配置并发保护（两步 UPDATE 无锁，可出现两条 active=true）
-
-**方案 D — 设备体系完善** ✅ *Validated in Phase 3 + Phase 03.1*
-- [x] D-0：设备模型字段扩展（online_status / last_online_time / software_version 等）
-- [x] D-1：Gateway sync-info 同步接口对接（CurrentIccid 预留结构待填充）
-- [x] D-2：device_sim_binding 新增 is_current 字段（当前使用卡标识）
-- [x] D-3：设备 Refresh + 详情接入 sync-info（在线状态/固件版本/当前卡实时更新）
-- [x] D-读取侧：DTO 字段映射补全（5个DB缓存字段 + 2处IsCurrent）+ GetRealtimeStatus Gateway 实时调用 + C端 mock 替换
-
-**方案 E — 流量体系改革（破坏性，低峰期）**
-- [ ] E-1：流量详单改为日粒度缓冲（新建 tb_card_daily_usage，Redis 增量缓存）
-- [ ] E-2：current_month_usage_mb 改增量累加（不再被上游自然月归零覆盖）
-- [ ] E-3：流量查询层适配（兼容 Redis 今日 + DB 历史两段数据）
-
-**方案 F — 代码质量清理**
-- [ ] F-1：佣金链断裂改为零额待审记录（status=99，不再静默跳过）
-- [ ] F-2：废弃 sim:status:sync 任务代码删除
-- [ ] F-3：错误不应被吞（cards, _ := 改为记日志）
-- [ ] F-4：C 端 Handler 迁移到 Service 层（直接 DB 访问改回分层）
-- [ ] F-5：Handler/Service 权限不一致修复
-- [ ] F-6：StopResumeCallback / ResumeCallback 注入（bootstrap 未调用）
-
-**方案 G — 实名激活架构重构** ✅ *Validated in Phase 2*
-- [x] G：enable_realname_activation 字段拆分为 expiry_base（from_activation/from_purchase）
-
-**方案 H — 轮询系统小修** ✅ *Validated in Phase 2*
-- [x] H-1：polling:protect 接入调度（已注册未调度）
-- [x] H-2：gatewayClient=nil 时停复机应返回错误（而非假装成功）
-- [x] H-3：packages 接口加分页
-- [x] H-4：Series 删除前检查关联套餐
-
-**方案 I — 退款完整功能（新功能）**
-- [ ] I-1：新建 tb_refund_request 数据模型
-- [ ] I-2：7 个退款接口（申请/列表/详情/审批/拒绝/退回/重提）
-- [ ] I-3：审批通过后按比例扣减代理佣金钱包
-
-**方案 J — 其他修复**
-- [ ] J-1：富友支付 JSAPI + 小程序接口实现（替换留桩）
-- [ ] J-2：平台代理钱包代购支持（platform buyerType 绕过代理检查）
-- [ ] J-3：status 3/4 业务触发逻辑（激活→3，最后套餐到期→4）
-- [ ] J-4：payment_status 枚举统一（删除 C 端映射函数，与管理端统一）
-
-### Out of Scope
-
-- SaaS 多租户架构 — 当前阶段不影响，v2+ 规划
-- 自动化测试（unit/integration/e2e） — 项目明确不做，人工验收
-- 设备定期轮询（P1-9） — 确认为伪需求，改为按需实时拉取
-- P1-2 企业认证中间件 — 企业账号复用 AdminAuth，不需要新中间件
-- P1-3 提现"已到账"接口 — 线下打款，系统无法感知
-- P2-6 告警通知渠道 — 无关紧要，暂不做
-- P2-9 asset_type 校验 — Service 层已有兜底，非问题
-- P2-24 Carrier→Series 绑定 — 系列可跨运营商，不需要强绑定
-- P2-30 轮询配置通用化 — 设备轮询取消后此问题不存在
-
-## Context
-
-- **技术栈**：Go + Fiber v2 + GORM + Asynq + PostgreSQL + Redis + sonic JSON + Viper + Zap
-- **架构分层**：Handler → Service → Store → Model，双进程（API + Worker），依赖集中在 bootstrap 装配
-- **路由注册**：统一经过 internal/routes/registry.go 的 Register()，同时驱动 OpenAPI 文档
-- **数据权限**：Store 层显式调用 ApplyShopFilter / ApplyEnterpriseFilter，不依赖 GORM Callback（README 描述已过时）
-- **支付体系**：微信（PowerWeChat v3 JSAPI/H5）+ 富友（自研 SDK，SDK 完整但主调接口留桩）+ 钱包余额
-- **修复文档**：完整规格书位于 .sisyphus/plans/修正业务-完整方案.md，包含每个 Bug 的文件路径和修改代码片段
-- **代码库地图**：.planning/codebase/ 包含 ARCHITECTURE.md / STACK.md / STRUCTURE.md 等
-
-## Constraints
-
-- **Tech Stack**: 严格使用 Fiber v2 + GORM + Asynq + PostgreSQL + Redis，不引入替代框架
-- **No Tests**: 项目不写自动化测试，人工验收（rg + go build + DBHub + 日志）
-- **Language**: 所有注释/日志/错误消息/文档使用中文，变量/函数名使用英文
-- **No Foreign Keys**: 禁止数据库外键约束，关联通过 ID 字段在代码层维护
-- **方案 E 风险**: 流量体系改革涉及 DB 迁移 + Redis 架构，必须低峰期发布，单独规划
-
-## Key Decisions
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| 不新建企业认证中间件 | 企业账号 user_type=4 已可复用 AdminAuth JWT | — Pending |
-| SaaS 方向不影响当前阶段 | 先把 MVP 跑通上线，SaaS 是 v2+ 的事 | — Pending |
-| 修正业务文档为完整范围 | 文档覆盖所有已知断点和缺失功能，无额外遗漏 | — Pending |
-| 设备体系不做定期轮询 | 按需实时拉取（sync-info）取代定期后台轮询 | — Pending |
-| 流量体系改革独立发布 | 破坏性变更（DB 迁移 + Redis 架构），风险隔离 | — Pending |
-
----
-*Last updated: 2026-03-28 after Phase 03.1 (sync-info-phase-3-dto) completion — device reading-side gap fully closed*
-
-## Evolution
-
-This document evolves at phase transitions and milestone boundaries.
-
-**After each phase transition** (via `/gsd-transition`):
-1. Requirements invalidated? → Move to Out of Scope with reason
-2. Requirements validated? → Move to Validated with phase reference
-3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
-5. "What This Is" still accurate? → Update if drifted
-
-**After each milestone** (via `/gsd-complete-milestone`):
-1. Full review of all sections
-2. Core Value check — still the right priority?
-3. Audit Out of Scope — reasons still valid?
-4. Update Context with current state

.planning/REQUIREMENTS.md

@@ -1,168 +0,0 @@
-# Requirements
-
-**Project:** 君鸿卡管系统
-**Milestone:** v1.0 — MVP 上线准备
-**Date:** 2026-03-27
-
----
-
-## v1 Requirements
-
-### CRITICAL — P0 紧急 Bug 修复（方案 A）
-
-- [x] **CRITICAL-01**: 实名状态常量统一 — `parseRealnameStatus` 写入值 2 改为常量 1，Model 注释统一，全链路使用 `constants.RealNameStatusVerified`
-- [x] **CRITICAL-02**: C 端实名校验修复 — `client_order/service.go` 实名判断改用 `constants.RealNameStatusVerified`（依赖 CRITICAL-01）
-- [x] **CRITICAL-03**: 实名激活任务断链修复 — `PollingHandler` 注入 `asynq.Client`，删除 RPush 降级方案，改用 `asynq.Client.EnqueueContext()`
-- [x] **CRITICAL-04**: 充值回调后自动购包触发 — `recharge/service.go` 在 HandlePaymentCallback 成功后入队 `TaskTypeAutoPurchaseAfterRecharge`；注册 `AutoPurchaseHandler`
-- [x] **CRITICAL-05**: 自动购包佣金链补全 — `AutoPurchaseHandler.ProcessTask()` 事务提交成功后入队 `TaskTypeCommission`
-- [x] **CRITICAL-06**: 代购订单金额修正 — 场景 5（代理代购下级）`sellerCostPrice` 全部 6 处逐一审查，确保使用 `operatorCostPrice`（非 `buyerCostPrice`）
-- [x] **CRITICAL-07**: 设备导入补充 IMEI 字段 — `DeviceRow` 新增 IMEI，`ParseDeviceExcel` 列名映射新增 IMEI，`device_import.go` 导入时填充
-- [x] **CRITICAL-08**: 提现冻结并发校验 — `my_commission/service.go` 冻结余额后检查 `RowsAffected == 0`，余额不足并发场景返回错误而非静默继续
-
-### PERM — 企业端权限完善（方案 B）
-
-- [x] **PERM-01**: 移除 Resolve 接口对企业账号的错误拦截 — 企业账号应能查询被授权的资产
-- [x] **PERM-02**: Refresh 接口新增企业账号拦截 — 企业只读，不允许主动触发运营商刷新
-
-### FIN — 财务/提现流程完善（方案 C）
-
-- [x] **FIN-01**: 提现审批人字段补全 — `Approve()` 写入 `approved_by` / `approved_at`（当前永远为空）
-- [x] **FIN-02**: 提现拒绝 remark 必填校验 — `Reject()` 在 BodyParser 后补充 `validator.Validate()`
-- [x] **FIN-03**: 激活配置并发保护 — 提现配置和微信配置激活时，两步 UPDATE 前加 `FOR UPDATE` 行锁
-
-### REALNAME — 实名激活架构重构（方案 G）
-
-- [x] **REALNAME-01**: 移除 `tb_package.enable_realname_activation` 字段，新增 `expiry_base VARCHAR(30)` 字段（`from_activation` / `from_purchase`）
-- [x] **REALNAME-02**: `activateMainPackage` 改写激活决策逻辑 — 按卡类型（industry/normal）+ 购买路径（C端/后台囤货）+ `expiry_base` 三维决策
-- [x] **REALNAME-03**: `client_order/service.go` 实名检查改为按卡类型判断（`card_category == "normal"`），删除 `packagesNeedRealname()` 函数
-- [x] **REALNAME-04**: `ActivateByRealname()` 按 `ExpiryBase` 选择激活时间基准（`from_purchase` 用 CreatedAt，`from_activation` 用当前时刻）
-- [x] **REALNAME-05**: 套餐管理 API DTO 更新 — 移除 `enable_realname_activation`，新增 `expiry_base` 枚举字段
-
-### POLL — 轮询系统小修（方案 H）
-
-- [x] **POLL-01**: `polling:protect` 接入调度 — `scheduler.go` 补充 processManualQueue + processTimedQueue 对 protect 任务的调度
-- [x] **POLL-02**: gatewayClient=nil 时停复机返回错误 — `stopCardWithRetry` 和 `resumeCardWithRetry` 两处改为返回业务错误而非 nil
-- [x] **POLL-03**: packages 接口新增分页 — `GetPackages()` 默认 page=1, pageSize=50，最大 100
-- [x] **POLL-04**: Series 删除前检查关联套餐 — `package_series/service.go:Delete()` 前置 `CountBySeriesID()` 检查
-
-### DEVICE — 设备体系完善（方案 D）
-
-- [x] **DEVICE-01**: 设备模型字段扩展 — DB 迁移新增 `online_status / last_online_time / software_version / switch_mode / last_gateway_sync_at`
-- [x] **DEVICE-02**: Gateway sync-info 同步接口对接 — `internal/gateway/device.go` 新增 `SyncDeviceInfo()` 方法
-- [x] **DEVICE-03**: `tb_device_sim_binding` 新增 `is_current` 字段 — DB 迁移 + Model + 更新逻辑
-- [x] **DEVICE-04**: 设备 Refresh + 详情接入 sync-info — `RefreshDevice()` 在刷新卡数据后调用 `SyncDeviceInfo()`，更新设备在线状态/固件版本/当前卡标识
-
-### REFUND — 退款完整功能（方案 I）
-
-- [ ] **REFUND-01**: 新建 `tb_refund_request` 数据模型 — DB 迁移 + GORM Model
-- [ ] **REFUND-02**: 退款接口实现 — Handler + Service + Store + 路由注册（Create / List / Get / Approve / Reject / Return / Resubmit 共 7 个接口）
-- [ ] **REFUND-03**: 审批通过后按比例扣减代理佣金钱包 — 使用整数算术（`amount * approvedRefund / actualReceived`），禁用 float64，写负向交易流水
-
-### PAY — 支付功能补全（方案 J-1 + J-2）
-
-- [ ] **PAY-01**: 富友支付 JSAPI 接口实现 — 替换留桩，实现预下单 + 返回前端调起支付参数
-- [ ] **PAY-02**: 富友支付小程序接口实现 — 与 JSAPI 相同逻辑，tradeType 改为 `LETPAY`
-- [ ] **PAY-03**: 新增 `FuiouPayJSAPIResponse` DTO，字段与微信官方 `wx.requestPayment()` 参数对齐
-- [ ] **PAY-04**: 平台代理钱包代购 — `CreateLegacy` 支持 `buyerType="" && resourceShopID != nil` 场景，使用资产所属代理的成本价和钱包
-
-### OPS — 运营逻辑修复（方案 J-3 + J-4）
-
-- [ ] **OPS-01**: IoT 卡/设备 status 字段 3/4 业务触发 — 套餐激活成功后更新为 3，最后一个 active 套餐到期后更新为 4
-- [ ] **OPS-02**: payment_status 枚举统一 — 删除 C 端 `orderStatusToClientStatus()` 映射函数，C 端直接输出与管理端一致的 1/2/3/4 枚举
-
-### CLEAN — 代码质量清理（方案 F）
-
-- [ ] **CLEAN-01**: 佣金链断裂改为零额待审记录 — 新增 `CommissionStatusPendingReview = 99`，断链时创建 amount=0 的待审记录，不再静默 break
-- [ ] **CLEAN-02**: 废弃 sim:status:sync 任务代码删除 — 移除注册行 + 常量 + `internal/task/sim.go` + `internal/service/sync/service.go`
-- [ ] **CLEAN-03**: 错误不应被吞 — `asset/service.go` 中 `cards, _ :=` 改为记录 Warn 日志
-- [ ] **CLEAN-04**: C 端 Handler 迁移到 Service 层 — `handler/app/client_order.go` 订单查询改为调用 `client_order/service.go`，删除直接 DB 访问
-- [ ] **CLEAN-05**: Handler/Service 权限不一致修复 — `handler/admin/order.go` 创建订单时补充钱包支付仅允许代理账号的前置校验
-- [ ] **CLEAN-06**: StopResumeCallback / ResumeCallback 注入 — `internal/bootstrap/services.go` 中初始化后调用 `SetStopResumeCallback` 和 `SetResumeCallback`
-
-### TRAFFIC — 流量体系改革（方案 E，破坏性变更）
-
-- [ ] **TRAFFIC-01**: 新建 `tb_card_daily_usage` 日粒度流量表 — DB 迁移 + 唯一约束 `(iot_card_id, date)`
-- [ ] **TRAFFIC-02**: 轮询流量写入改为 Redis 增量缓存 — `insertDataUsageRecord()` 仅在有增量时写 `RedisCardDailyTrafficKey`
-- [ ] **TRAFFIC-03**: 每日落盘定时任务 — Asynq Scheduler 凌晨 2 点 SCAN Redis Key → UPSERT `tb_card_daily_usage` → 删 Key
-- [ ] **TRAFFIC-04**: 流量增量累加 — `calculateFlowUpdates()` 改为 `current_month_usage_mb += increment`，检测运营商重置日，新增 `tb_carrier.data_reset_day` 和 `tb_iot_card.last_gateway_reading_mb`
-- [ ] **TRAFFIC-05**: 流量查询层适配 — 新建 `TrafficQueryService.GetDailyUsage()` 兼容"今日 Redis + 历史 DB"两段数据
-
----
-
-## v2 Requirements（延后）
-
-- 卡/资产批量操作（停/复/注销）— 运营场景必须，当前仅有单卡接口
-- 卡/订单批量导出（Excel/CSV）— 财务对账标配，已有导入缺导出
-- 套餐到期前微信模板消息提醒 — 用户体验，竞品标配
-- 代理商完整资金流水账单（按时间倒序，标注来源类型）
-- 下级代理业绩报表（订单数/金额/活跃卡数）
-- 卡状态变更历史记录（溯源谁什么时候停了哪张卡）
-- SaaS 多租户架构 — v2+ 规划
-
----
-
-## Out of Scope
-
-- 自动化测试（unit/integration/e2e）— 项目明确不做
-- 设备定期轮询（P1-9）— 伪需求，改为按需实时拉取
-- P1-2 企业认证中间件 — 复用 AdminAuth，无需新中间件
-- P1-3 提现"已到账"确认接口 — 线下打款，系统无法感知
-- P2-6 告警通知渠道 — 优先级低，暂不做
-- P2-9 asset_type 校验 — Service 层已有兜底
-- P2-24 Carrier→Series 强绑定 — 系列可跨运营商
-- P2-30 轮询配置通用化 — 设备轮询取消后此问题不存在
-
----
-
-## Traceability
-
-*（由 roadmapper 在创建 ROADMAP.md 时填充 — 2026-03-27）*
-
-| REQ-ID | Phase | Status |
-|--------|-------|--------|
-| CRITICAL-01 | Phase 1 | Complete |
-| CRITICAL-02 | Phase 1 | Complete |
-| CRITICAL-03 | Phase 1 | Complete |
-| CRITICAL-04 | Phase 1 | Complete |
-| CRITICAL-05 | Phase 1 | Complete |
-| CRITICAL-06 | Phase 1 | Complete |
-| CRITICAL-07 | Phase 1 | Complete |
-| CRITICAL-08 | Phase 1 | Complete |
-| PERM-01 | Phase 2 | Complete |
-| PERM-02 | Phase 2 | Complete |
-| FIN-01 | Phase 2 | Complete |
-| FIN-02 | Phase 2 | Complete |
-| FIN-03 | Phase 2 | Complete |
-| REALNAME-01 | Phase 2 | Complete |
-| REALNAME-02 | Phase 2 | Complete |
-| REALNAME-03 | Phase 2 | Complete |
-| REALNAME-04 | Phase 2 | Complete |
-| REALNAME-05 | Phase 2 | Complete |
-| POLL-01 | Phase 2 | Complete |
-| POLL-02 | Phase 2 | Complete |
-| POLL-03 | Phase 2 | Complete |
-| POLL-04 | Phase 2 | Complete |
-| DEVICE-01 | Phase 3 | Complete |
-| DEVICE-02 | Phase 3 | Complete |
-| DEVICE-03 | Phase 3 | Complete |
-| DEVICE-04 | Phase 3 | Complete |
-| REFUND-01 | Phase 4 | Pending |
-| REFUND-02 | Phase 4 | Pending |
-| REFUND-03 | Phase 4 | Pending |
-| PAY-01 | Phase 4 | Pending |
-| PAY-02 | Phase 4 | Pending |
-| PAY-03 | Phase 4 | Pending |
-| PAY-04 | Phase 4 | Pending |
-| OPS-01 | Phase 4 | Pending |
-| OPS-02 | Phase 4 | Pending |
-| CLEAN-01 | Phase 5 | Pending |
-| CLEAN-02 | Phase 5 | Pending |
-| CLEAN-03 | Phase 5 | Pending |
-| CLEAN-04 | Phase 5 | Pending |
-| CLEAN-05 | Phase 5 | Pending |
-| CLEAN-06 | Phase 5 | Pending |
-| TRAFFIC-01 | Phase 6 | Pending |
-| TRAFFIC-02 | Phase 6 | Pending |
-| TRAFFIC-03 | Phase 6 | Pending |
-| TRAFFIC-04 | Phase 6 | Pending |
-| TRAFFIC-05 | Phase 6 | Pending |

.planning/ROADMAP.md

@@ -1,168 +0,0 @@
-# ROADMAP — 君鸿卡管系统 v1.0
-
-**Project:** 君鸿卡管系统  
-**Milestone:** v1.0 — MVP 上线准备  
-**Created:** 2026-03-27  
-**Granularity:** Standard (6 phases)  
-**Coverage:** 46/46 requirements mapped ✓  
-
----
-
-## Phases
-
-- [x] **Phase 1: P0 紧急修复** — 修复所有阻塞主链路的 P0 Bug，使充值→购包→佣金→实名激活全链路可跑通 (completed 2026-03-27)
-- [x] **Phase 2: 权限/财务/实名/轮询修复** — 补全企业权限、提现财务流程、实名激活架构重构、轮询系统小修 (completed 2026-03-28)
-- [x] **Phase 3: 设备体系完善** — 扩展设备模型字段、对接 Gateway sync-info、完善绑卡标识 (completed 2026-03-28)
-- [ ] **Phase 4: 退款 + 支付 + 运营修复** — 实现退款完整流程、补全富友支付接口、修复运营逻辑
-- [ ] **Phase 5: 代码质量清理** — 消除技术债务：佣金断链可观测、删废弃代码、修复权限不一致、迁移分层
-- [ ] **Phase 6: 流量体系改革（低峰期）** — 破坏性变更：日粒度流量表 + Redis 增量缓存 + 每日落盘任务
-
----
-
-## Phase Details
-
-### Phase 1: P0 紧急修复
-**Goal**: 修复所有已知的主链路断点，使"充值→自动购包→佣金计算→实名激活"的完整业务链路可端到端跑通，消除数据写入混乱（实名状态常量）和并发安全漏洞（提现重复创建）  
-**Depends on**: 无（基础）  
-**Requirements**: CRITICAL-01, CRITICAL-02, CRITICAL-03, CRITICAL-04, CRITICAL-05, CRITICAL-06, CRITICAL-07, CRITICAL-08  
-**Success Criteria** (what must be TRUE):
-  1. C 端用户完成实名后，实名状态正确写入 DB（值为常量 1，不再是 2），实名激活任务正确触发
-  2. C 端用户钱包充值成功后，自动购包任务入队并被消费，佣金计算任务被正确触发
-  3. 代理代购下级场景（场景 5）的订单金额正确使用 operatorCostPrice，佣金链计算正常
-  4. 批量导入设备 Excel 后，设备记录中含 IMEI 字段，Gateway 调用不再因 IMEI 缺失而失败
-  5. 并发提交提现申请时，RowsAffected 检查生效，不会创建重复提现单
-**Plans**: 5 plans
-
-Plans:
-- [x] 01-01-PLAN.md — CRITICAL-01/02：实名状态常量统一 + C 端实名校验修复（Wave 1）
-- [x] 01-02-PLAN.md — CRITICAL-03：实名激活任务断链（PollingHandler 注入 asynqClient）（Wave 2）
-- [x] 01-03-PLAN.md — CRITICAL-04/05：充值回调触发自动购包 + 佣金链补全（Wave 2，parallel）
-- [x] 01-04-PLAN.md — CRITICAL-06：代购订单 sellerCostPrice 6 处语义审查修正（Wave 1，parallel）
-- [x] 01-05-PLAN.md — CRITICAL-07/08：设备导入 IMEI + 提现冻结并发校验（Wave 1，parallel）
-
----
-
-### Phase 2: 权限/财务/实名/轮询修复
-**Goal**: 补全企业账号权限边界（可查但不可刷新）、修复提现流程数据完整性（审批人字段/remark 必填/激活配置并发锁）、重构实名激活判断架构（从布尔字段改为 expiry_base 枚举）、修复轮询调度和安全漏洞  
-**Depends on**: Phase 1（CRITICAL-01 先统一实名常量，REALNAME 重构再依此展开）  
-**Requirements**: PERM-01, PERM-02, FIN-01, FIN-02, FIN-03, REALNAME-01, REALNAME-02, REALNAME-03, REALNAME-04, REALNAME-05, POLL-01, POLL-02, POLL-03, POLL-04  
-**Success Criteria** (what must be TRUE):
-  1. 企业账号可以调用 Resolve 接口查询被授权资产，但无法触发 Refresh 刷新运营商数据
-  2. 提现审批通过后，approved_by 和 approved_at 字段正确填充；拒绝时若 remark 为空则返回校验错误
-  3. 同时激活两个提现配置时，数据库行锁生效，不会出现两条 active=true 的记录
-  4. 数据库中 tb_package 表不再有 enable_realname_activation 字段，改为 expiry_base 字段（值为 from_activation 或 from_purchase）
-  5. C 端购买普通号卡套餐时，实名检查按卡类型（card_category == "normal"）判断，逻辑简洁正确
-  6. polling:protect 任务正确进入调度器，停复机时若 gatewayClient 为 nil 返回业务错误而非静默成功
-**Plans**: 2 plans
-
-Plans:
-- [x] 02-01-PLAN.md — PERM-01/02 + FIN-01/02/03 + POLL-01/02/03/04：权限/财务/轮询小修合并（Wave 1）
-- [x] 02-02-PLAN.md — REALNAME-01~05：实名激活架构重构，原子执行（Wave 1，parallel）
-
----
-
-### Phase 3: 设备体系完善
-**Goal**: 扩展设备数据模型，对接 Gateway sync-info 接口实现设备在线状态/固件版本实时同步，建立"当前使用卡"标识，使设备详情页展示真实状态  
-**Depends on**: Phase 1（设备导入 IMEI 修复在 CRITICAL-07 完成）  
-**Requirements**: DEVICE-01, DEVICE-02, DEVICE-03, DEVICE-04  
-**Success Criteria** (what must be TRUE):
-  1. tb_device 表含 online_status / last_online_time / software_version / switch_mode / last_gateway_sync_at 字段（DB 迁移已执行）
-  2. 调用设备刷新接口后，设备的在线状态、固件版本、当前使用卡（is_current）从 Gateway 实时更新
-  3. tb_device_sim_binding 表含 is_current 字段，同一设备同一时刻只有一条 is_current=true 的绑定记录
-  4. 设备详情接口返回数据包含 online_status、software_version 等字段，值与 Gateway 同步结果一致
-**Plans**: 2 plans
-
-Plans:
-- [x] 03-01-PLAN.md — DEVICE-01/02/03：DB 迁移 + 模型扩展 + Gateway SyncDeviceInfo + DTO 字段（Wave 1）
-- [x] 03-02-PLAN.md — DEVICE-04：Asset Service 接入 sync-info，Refresh 追加设备状态同步（Wave 2）
-
----
-
-### Phase 03.1: 设备 sync-info 读取链路修复：补全 Phase 3 新增字段在查询接口的 DTO 映射缺口 (INSERTED)
-
-**Goal:** 补全 Phase 3 完成的设备数据写入链路在读取侧的缺口：修复 DTO 字段映射遗漏（5个 DB 缓存字段 + 2处 IsCurrent）+ 建立设备实时状态的 Gateway 查询链路（替换 mock → 真实 Gateway 数据）
-**Requirements**: DEVICE-02, DEVICE-03, DEVICE-04
-**Depends on:** Phase 3
-**Plans:** 1/1 plans complete
-
-Plans:
-- [ ] 03.1-01-PLAN.md — 补全静态 DTO 映射缺口 + 建立 GetRealtimeStatus Gateway 实时调用 + C 端 stub 替换（Wave 1）
-
-### Phase 4: 退款 + 支付 + 运营修复
-**Goal**: 实现完整退款流程（申请→审批→佣金回扣），补全富友支付 JSAPI/小程序接口（替换留桩），修复运营逻辑断点（卡状态 3/4 触发、payment_status 枚举统一）  
-**Depends on**: Phase 2（佣金链路稳定后再做退款佣金回扣）  
-**Requirements**: REFUND-01, REFUND-02, REFUND-03, PAY-01, PAY-02, PAY-03, PAY-04, OPS-01, OPS-02  
-**Success Criteria** (what must be TRUE):
-  1. tb_refund_request 表存在，退款申请/列表/详情/审批/拒绝/退回/重提共 7 个接口可正常调用
-  2. 退款审批通过后，代理佣金钱包按比例扣减（使用整数算术，无 float64 精度误差），负向交易流水写入
-  3. 富友支付 JSAPI 和小程序接口可正常发起支付，返回前端所需调起参数（FuiouPayJSAPIResponse DTO）
-  4. 平台代理使用钱包代购资产时，正确使用资产所属代理成本价，绕过代理身份检查
-  5. IoT 卡/设备在套餐激活成功后 status 更新为 3，最后一个 active 套餐到期后 status 更新为 4
-  6. C 端和管理端 payment_status 枚举值一致（1/2/3/4），不再存在独立的 C 端映射函数
-**Plans**: TBD
-
----
-
-### Phase 5: 代码质量清理
-**Goal**: 消除技术债务：使佣金断链可观测（创建零额待审记录），删除废弃的 sim:status:sync 任务代码，修复错误被吞、分层违规、权限不一致等问题，确保 bootstrap 完整注入所有回调  
-**Depends on**: Phase 4（所有业务功能稳定后集中清理）  
-**Requirements**: CLEAN-01, CLEAN-02, CLEAN-03, CLEAN-04, CLEAN-05, CLEAN-06  
-**Success Criteria** (what must be TRUE):
-  1. 佣金链计算遇到断链时，创建 status=99（amount=0）的待审记录，日志可见，不再静默跳过
-  2. 代码库中不再有 sim:status:sync 任务相关代码（注册行、常量、sim.go、sync/service.go）
-  3. asset/service.go 中的 cards 错误被记录为 Warn 日志，不再被 `_` 吞掉
-  4. client_order Handler 订单查询通过 Service 层调用，不再直接访问 DB
-  5. 停复机回调（StopResumeCallback / ResumeCallback）在 bootstrap 中正确注入，套餐联动触发正常
-**Plans**: TBD
-
----
-
-### Phase 6: 流量体系改革（低峰期）
-**Goal**: 重构流量统计架构为"日粒度 DB 落盘 + Redis 增量缓存"模式，解决运营商自然月归零覆盖问题，提供今日 Redis + 历史 DB 两段数据的统一查询层  
-**Depends on**: Phase 5（代码清理完成，系统稳定，降低破坏性变更风险）  
-**Requirements**: TRAFFIC-01, TRAFFIC-02, TRAFFIC-03, TRAFFIC-04, TRAFFIC-05  
-**Success Criteria** (what must be TRUE):
-  1. tb_card_daily_usage 表存在，含唯一约束 (iot_card_id, date)（DB 迁移已执行）
-  2. 流量轮询写入时，仅在有增量时写 Redis，不再直接覆盖 current_month_usage_mb
-  3. 每日凌晨 2 点 Asynq Scheduler 任务执行：SCAN Redis Key → UPSERT tb_card_daily_usage → 删 Key，日志可验证
-  4. current_month_usage_mb 使用增量累加而非覆盖，运营商自然月归零不会影响 DB 中的历史累计值
-  5. GetDailyUsage 接口返回"今日 Redis 数据 + 历史 DB 日粒度数据"合并结果，兼容两段数据
-**Plans**: TBD
-**⚠️ 部署警告**: 此 Phase 涉及 DB 迁移 + Redis 架构变更，必须在低峰期（凌晨 2~5 点）独立部署
-
----
-
-## Progress
-
-| Phase | Plans Complete | Status | Completed |
-|-------|----------------|--------|-----------|
-| 1. P0 紧急修复 | 5/5 | Complete   | 2026-03-27 |
-| 2. 权限/财务/实名/轮询修复 | 2/2 | Complete    | 2026-03-28 |
-| 3. 设备体系完善 | 2/2 | Complete   | 2026-03-28 |
-| 4. 退款 + 支付 + 运营修复 | 0/TBD | Not started | - |
-| 5. 代码质量清理 | 0/TBD | Not started | - |
-| 6. 流量体系改革（低峰期）| 0/TBD | Not started | - |
-
----
-
-## Requirement Coverage
-
-**Total v1 requirements:** 46  
-**Mapped:** 46 ✓  
-
-| Category | Count | Phase |
-|----------|-------|-------|
-| CRITICAL | 8 | Phase 1 |
-| PERM | 2 | Phase 2 |
-| FIN | 3 | Phase 2 |
-| REALNAME | 5 | Phase 2 |
-| POLL | 4 | Phase 2 |
-| DEVICE | 4 | Phase 3 |
-| REFUND | 3 | Phase 4 |
-| PAY | 4 | Phase 4 |
-| OPS | 2 | Phase 4 |
-| CLEAN | 6 | Phase 5 |
-| TRAFFIC | 5 | Phase 6 |
-
----
-*Roadmap created: 2026-03-27*

.planning/STATE.md

@@ -1,142 +0,0 @@
----
-gsd_state_version: 1.0
-milestone: v1.0
-milestone_name: milestone
-status: unknown
-last_updated: "2026-03-28T05:41:21.983Z"
-progress:
-  total_phases: 7
-  completed_phases: 4
-  total_plans: 10
-  completed_plans: 10
----
-
-# Project State — 君鸿卡管系统
-
-**Project:** 君鸿卡管系统 v1.0  
-**Milestone:** v1.0 — MVP 上线准备  
-**Last Updated:** 2026-03-28  
-
----
-
-## Current Position
-
-Phase: 4
-Plan: Not started
-| Field | Value |
-|-------|-------|
-| **Current Phase** | 3 — 设备体系完善 |
-| **Current Plan** | None (awaiting planning) |
-| **Status** | Ready to plan Phase 3 |
-| **Phase Progress** | 0/4 requirements complete |
-
-```
-Progress: [ 1 ]──[ 2 ]──[ 3 ]──[ 4 ]──[ 5 ]──[ 6 ]
-            ✓      ✓      ▲
-                          Next
-```
-
----
-
-## Project Reference
-
-**Core Value:** 业务链路完整可用——代理能采购分配卡/设备，C端客户能充值购包激活套餐，佣金能正确计算并可提现。这条主链路必须端到端跑通。
-
-**Current Focus:** Phase 03 — device-system
-
----
-
-## Phase Summary
-
-| Phase | Name | Requirements | Status |
-|-------|------|--------------|--------|
-| 1 | P0 紧急修复 | CRITICAL-01~08（8项） | ✓ Complete (2026-03-28) |
-| 2 | 权限/财务/实名/轮询修复 | PERM-01~02, FIN-01~03, REALNAME-01~05, POLL-01~04（14项） | ✓ Complete (2026-03-28) |
-| 3 | 设备体系完善 | DEVICE-01~04（4项） | ✓ Complete (2026-03-28) |
-| 3.1 | 设备 sync-info 读取链路修复 | DEVICE-02~04 读取侧 | ✓ Complete (2026-03-28) |
-| 4 | 退款 + 支付 + 运营修复 | REFUND-01~03, PAY-01~04, OPS-01~02（9项） | ○ Not started |
-| 5 | 代码质量清理 | CLEAN-01~06（6项） | ○ Not started |
-| 6 | 流量体系改革（低峰期）| TRAFFIC-01~05（5项） | ○ Not started |
-
----
-
-## Performance Metrics
-
-| Metric | Value |
-|--------|-------|
-| Phases total | 6 |
-| Requirements v1 | 46 |
-| Requirements mapped | 46/46 (100%) |
-| Plans created | 7 |
-| Plans complete | 7/7 |
-| Phases complete | 2/6 |
-
----
-| Phase 03-device-system P01 | 8min | 2 tasks | 10 files |
-| Phase 03-device-system P02 | 10min | 2 tasks | 3 files |
-| Phase 03.1-sync-info-phase-3-dto P01 | 5min | 3 tasks | 6 files |
-
-## Execution Log
-
-| Plan | Duration | Tasks | Files |
-|------|----------|-------|-------|
-| Phase 01 P01 | 15min | 2 tasks | 7 files |
-| Phase 01 P02 | 3min | 1 task | 2 files |
-| Phase 01 P03 | 8min | 2 tasks | 4 files |
-| Phase 01 P04 | 4min | 1 task | 1 file |
-| Phase 01 P05 | 8min | 2 tasks | 3 files |
-| Phase 02 P01 | 10min | 2 tasks | 14 files |
-| Phase 02 P02 | 25min | 2 tasks | 8 files |
-| Phase 03.1 P01 | 5min | 3 tasks | 6 files |
-
----
-
-## Accumulated Context
-
-### Key Decisions
-
-- TRAFFIC（Phase 6）必须独立部署，低峰期（凌晨 2~5 点），涉及 DB 迁移 + Redis 架构变更
-- REALNAME-01~05 是原子重构，必须在一个 plan 内完整执行，不可拆分
-- REFUND 退款佣金回扣（REFUND-03）必须使用整数算术，禁用 float64
-- CRITICAL-02 依赖 CRITICAL-01，CRITICAL-05 依赖 CRITICAL-04
-- DEVICE-02/03/04 依赖 DEVICE-01（字段扩展先行）✓ Phase 03 完成
-- REFUND-02/03 依赖 REFUND-01（数据模型先行）
-- DEVICE-04: gatewayClient nil guard 可选注入，sync-info 失败仅记 Warn 不阻断 Refresh 主流程
-- UpdateIsCurrentByDeviceID 事务两步原子更新 is_current，保证同一设备唯一 is_current=true
-- DeviceGatewayInfo（B端）与 DeviceRealtimeInfo（C端）独立结构体，SwitchMode 字符串→整型转换（Phase 03.1 决策）
-
-### Architecture Notes
-
-- 双进程（API + Worker），依赖集中在 bootstrap 装配
-- 数据权限：Store 层显式调用 ApplyShopFilter / ApplyEnterpriseFilter（非 GORM Callback）
-- StopResumeCallback / ResumeCallback 未注入 bootstrap（CLEAN-06 修复）
-- 流量体系当前用直接覆盖写，Phase 6 改为增量累加 + 日粒度 DB
-- expiry_base 枚举已替换 enable_realname_activation，激活决策为三维（卡类型+购买路径+expiry_base）
-
-### Roadmap Evolution
-
-- Phase 03.1 inserted after Phase 3: 设备 sync-info 读取链路修复：补全 Phase 3 新增字段在查询接口的 DTO 映射缺口 (URGENT)
-
-### Known Risks
-
-- sellerCostPrice 错误赋值可能不止场景 5（CRITICAL-06 已处理 6 处）
-- 分佣树形遍历无循环检测（不在当前 scope，v2 考量）
-- 店铺软删除无级联检查（v2 考量）
-- pkg/openapi/handlers.go CommissionWithdrawalHandler 签名已在 02-01 中同步修复
-
----
-
-## Session Continuity
-
-**Next Action:** Run `/gsd-plan-phase 4` to create detailed plan for Phase 4 (退款 + 支付 + 运营修复)
-
-**Context Files:**
-
-- `.planning/ROADMAP.md` — 完整路线图和成功标准
-- `.planning/REQUIREMENTS.md` — 46 个 v1 需求（含 Traceability 表）
-- `.planning/PROJECT.md` — 项目背景和约束
-- `.planning/research/SUMMARY.md` — 技术研究和陷阱分析
-- `.sisyphus/plans/修正业务-完整方案.md` — 每个 Bug 的完整修复规格（含代码片段）
-
----
-*State initialized: 2026-03-27 | Last phase completed: Phase 03.1 (2026-03-28)*

.planning/codebase/ARCHITECTURE.md

@@ -1,179 +0,0 @@
-# Architecture
-
-**Analysis Date:** 2026-03-27
-
-## Pattern Overview
-
-**Overall:** 双进程分层单体（API + Worker），核心代码按 `Handler → Service → Store → Model` 组织。
-
-**Key Characteristics:**
-- HTTP 入口与异步任务入口分离：`cmd/api/main.go` 负责 Fiber API，`cmd/worker/main.go` 负责 Asynq Worker 与轮询调度。
-- 依赖集中在 `internal/bootstrap/` 组装，再分发给 `internal/routes/`、`internal/handler/`、`internal/task/`。
-- 数据访问主要走 `internal/store/postgres/*.go`，模型与 DTO 分别位于 `internal/model/*.go` 与 `internal/model/dto/*.go`。
-- 路由注册统一经过 `internal/routes/registry.go` 的 `Register()`，同时驱动 Fiber 路由与 OpenAPI 元数据。
-- 多租户与权限控制主要依赖认证上下文 + Store 层显式过滤函数，而不是数据库外键或 ORM 关联。
-
-## Layers
-
-**Entrypoint / Composition Layer:**
-- Purpose: 进程启动、基础设施初始化、依赖装配、生命周期管理。
-- Location: `cmd/api/main.go`, `cmd/worker/main.go`, `internal/bootstrap/*.go`
-- Contains: 配置加载、日志、数据库、Redis、队列、对象存储、Gateway 客户端、Bootstrap 编排。
-- Depends on: `pkg/config`, `pkg/database`, `pkg/logger`, `pkg/queue`, `pkg/storage`, `internal/bootstrap`
-- Used by: 整个应用进程。
-
-**Routing / Transport Layer:**
-- Purpose: 路由域划分、认证挂载、HTTP 入参与响应封装、OpenAPI 文档注册。
-- Location: `internal/routes/*.go`, `internal/handler/**/*.go`
-- Contains: `RegisterRoutesWithDoc()` 总入口、Admin/Auth/Personal 域路由、Fiber Handler。
-- Depends on: `internal/bootstrap.Handlers`, `internal/bootstrap.Middlewares`, `pkg/openapi`, `pkg/response`
-- Used by: `cmd/api/main.go`
-
-**Service Layer:**
-- Purpose: 业务规则、权限判断、事务编排、幂等、异步任务提交、跨模块协作。
-- Location: `internal/service/**/*.go`
-- Contains: 账号、订单、套餐、轮询、设备、卡、认证、充值、佣金等服务。
-- Depends on: `internal/store/postgres`, `pkg/errors`, `pkg/middleware`, `pkg/queue`, `pkg/wechat`, `gorm.DB`, `redis.Client`
-- Used by: Handler 层、Worker Bootstrap、Task Handler。
-
-**Store Layer:**
-- Purpose: SQL 查询、分页、显式数据权限过滤、缓存辅助、事务基础能力。
-- Location: `internal/store/store.go`, `internal/store/options.go`, `internal/store/postgres/*.go`
-- Contains: 每个聚合的 PostgreSQL Store，例如 `internal/store/postgres/account_store.go`, `internal/store/postgres/order_store.go`。
-- Depends on: `gorm`, `redis`, `pkg/middleware/data_scope.go`
-- Used by: Service 层、部分 Handler 组装期专用读模型。
-
-**Model Layer:**
-- Purpose: 持久化模型、DTO、常量化状态值、表名映射。
-- Location: `internal/model/*.go`, `internal/model/dto/*.go`
-- Contains: `model.Account`, `model.Order`, `model.Shop`, `model.PollingConfig` 以及请求/响应 DTO。
-- Depends on: GORM tags、标准库类型。
-- Used by: Store、Service、Handler、OpenAPI 生成。
-
-**Task / Worker Layer:**
-- Purpose: Asynq 任务处理、轮询调度、定时任务、批处理导入。
-- Location: `internal/task/*.go`, `internal/polling/*.go`, `pkg/queue/*.go`
-- Contains: `pkg/queue/handler.go` 任务注册器、`internal/task/polling_handler.go`、`internal/task/order_expire.go`、`internal/polling/scheduler.go`。
-- Depends on: Worker bootstrap 产出的 stores/services、Redis、Asynq、Gateway。
-- Used by: `cmd/worker/main.go`
-
-## Data Flow
-
-**API Request Flow:**
-
-1. `cmd/api/main.go` 创建 Fiber 应用并注册 Recover、RequestID、访问日志、压缩中间件。
-2. `internal/routes/routes.go` 将请求分发到 `/api/auth`、`/api/admin`、`/api/c/v1`、`/api/callback` 四个域。
-3. `pkg/middleware/auth.go` 或 `internal/middleware/personal_auth` 将用户信息写入 Fiber `Locals` 和标准 `context.Context`。
-4. Handler 解析 DTO 并调用 Service，例如 `internal/handler/admin/account.go` → `internal/service/account/service.go`。
-5. Service 调用一个或多个 Store，必要时使用 `db.WithContext(ctx).Transaction(...)` 编排事务，例如 `internal/service/order/service.go`。
-6. Store 在查询中显式调用 `pkg/middleware/data_scope.go` 的过滤函数，例如 `internal/store/postgres/account_store.go`、`internal/store/postgres/order_store.go`。
-7. Handler 通过 `pkg/response/response.go` 返回统一响应；异常交由 `internal/middleware.ErrorHandler` 处理。
-
-**Worker Flow:**
-
-1. `cmd/worker/main.go` 初始化 PostgreSQL、Redis、Asynq Client、对象存储、Gateway。
-2. `internal/bootstrap/worker.go` 调用 `initWorkerStores()` 与 `initWorkerServices()`，生成 `queue.WorkerBootstrapResult`。
-3. `pkg/queue/handler.go` 基于 Bootstrap 结果注册导入、轮询、佣金、超时取消、告警、清理等任务处理器。
-4. `internal/polling/scheduler.go` 独立运行轮询调度循环：从 Redis Sorted Set / List 取卡片，再投递到 Asynq。
-5. `cmd/worker/main.go` 还额外创建 Asynq Scheduler，注册 `TaskTypeOrderExpire`、`TaskTypeAlertCheck`、`TaskTypeDataCleanup`。
-6. 具体任务处理器调用 Service 或直接使用 Store/DB 更新状态，例如 `internal/task/order_expire.go` → `order.Service.CancelExpiredOrders()`。
-
-**State Management:**
-- HTTP 侧状态主要放在 PostgreSQL；请求态身份与数据权限范围放在 `context.Context`。
-- 高速状态、Token、轮询队列、并发信号量、下级店铺缓存放在 Redis，如 `pkg/auth/token.go`、`internal/polling/scheduler.go`、`internal/store/postgres/shop_store.go`。
-- 异步处理采用 Redis-backed Asynq 队列，由 `pkg/queue/client.go` 提交、`pkg/queue/server.go` 消费。
-
-## Key Abstractions
-
-**BootstrapResult / WorkerBootstrapResult:**
-- Purpose: 启动期依赖编排结果。
-- Examples: `internal/bootstrap/bootstrap.go`, `internal/bootstrap/worker.go`
-- Pattern: 显式依赖注入，不使用外部 DI 框架。
-
-**Handlers / Middlewares 容器:**
-- Purpose: 路由注册时的装配清单。
-- Examples: `internal/bootstrap/types.go`, `internal/bootstrap/handlers.go`, `internal/bootstrap/middlewares.go`
-- Pattern: 结构体聚合所有已构造的 Handler 与 Middleware。
-
-**RouteSpec + Register():**
-- Purpose: 单次声明同时完成真实路由注册和 OpenAPI 元数据注册。
-- Examples: `internal/routes/registry.go`, `internal/routes/account.go`, `internal/routes/personal.go`
-- Pattern: 代码即文档，DTO 驱动文档生成。
-
-**QueryOptions:**
-- Purpose: Store 通用分页与排序选项。
-- Examples: `internal/store/options.go`, `internal/service/account/service.go`, `internal/service/order/service.go`
-- Pattern: Service 先构造查询选项，再下传到 Store。
-
-**UserContextInfo + Data Scope Filters:**
-- Purpose: 承载用户身份与可管理店铺范围，并在 Store 查询时执行过滤。
-- Examples: `pkg/middleware/auth.go`, `pkg/middleware/data_scope.go`, `internal/store/postgres/shop_store.go`
-- Pattern: 中间件预计算 `SubordinateShopIDs`，Store 按字段类型显式调用 `ApplyShopFilter` / `ApplyEnterpriseFilter` / `ApplySellerShopFilter`。
-
-## Entry Points
-
-**API Main:**
-- Location: `cmd/api/main.go`
-- Triggers: `go run cmd/api/main.go`、API 容器启动。
-- Responsibilities: 加载配置、初始化基础设施、执行 `bootstrap.Bootstrap()`、创建 Fiber、注册中间件和路由、生成运行时 OpenAPI 文件 `logs/openapi.yaml`。
-
-**Worker Main:**
-- Location: `cmd/worker/main.go`
-- Triggers: `go run cmd/worker/main.go`、Worker 容器启动。
-- Responsibilities: 初始化 Worker 依赖、执行 `bootstrap.BootstrapWorker()`、启动 Asynq Worker、启动轮询调度器和 Asynq Scheduler、优雅关闭。
-
-**OpenAPI Generation CLI:**
-- Location: `cmd/gendocs/main.go`
-- Triggers: 手动执行文档生成。
-- Responsibilities: 通过 `openapi.BuildDocHandlers()` + `routes.RegisterRoutesWithDoc()` 输出 `docs/admin-openapi.yaml`。
-
-## Routing Strategy
-
-**Domain Split:**
-- `/api/auth`：统一后台/H5 认证，见 `internal/routes/auth.go`
-- `/api/admin`：管理后台业务域，见 `internal/routes/admin.go`
-- `/api/c/v1`：个人客户端域，见 `internal/routes/personal.go`
-- `/api/callback`：支付回调，无认证，见 `internal/routes/order.go` 与 `internal/handler/callback/payment.go`
-
-**Registration Style:**
-- 所有 HTTP 接口使用 `internal/routes/registry.go` 的 `Register()`，文档规范见 `docs/api-documentation-guide.md`。
-- `internal/routes/admin.go` 以 handler 是否为 `nil` 决定是否挂载模块，便于文档生成和裁剪。
-- `internal/routes/personal.go` 明确区分公开路由与认证路由，并依赖注册顺序确保公开接口不被 `Use()` 拦截。
-
-## Error Handling
-
-**Strategy:** 统一错误码 + 全局 Fiber ErrorHandler。
-
-**Patterns:**
-- Handler 层只做参数解析与转发，返回 `pkg/errors` 中的 `AppError`，如 `internal/handler/admin/account.go`。
-- Service 层封装业务错误，不直接向外泄露底层错误文本，如 `internal/service/account/service.go`、`internal/service/order/service.go`。
-- Worker 任务记录结构化日志，并将可重试与不可重试逻辑写在处理器内部，如 `internal/task/order_expire.go`、`internal/task/polling_handler.go`。
-
-## Cross-Cutting Concerns
-
-**Logging:**
-- `pkg/logger/logger.go` 初始化 App/Access 日志；`pkg/logger/middleware.go` 记录完整请求/响应摘要。
-
-**Validation:**
-- Fiber `BodyParser` / `QueryParser` + `validator.v10`，示例见 `internal/handler/auth/handler.go`。
-
-**Authentication:**
-- 后台/H5 使用 Redis Token + `pkg/middleware/auth.go`；个人客户使用单独中间件，由 `internal/bootstrap/middlewares.go` 创建。
-
-**OpenAPI:**
-- 路由元数据写在 `RouteSpec`；文档生成器依赖 `cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go` 三处手工维护 Handler 清单。
-
-**Persistence Rules:**
-- 模型显式声明 `TableName()` 与字段列名，如 `internal/model/account.go`, `internal/model/order.go`, `internal/model/shop.go`。
-- 数据库结构通过 `migrations/*.sql` 管理，`pkg/database/postgres.go` 明确禁用自动建表。
-
-## Architectural Deviations
-
-**README / 规范与当前实现存在的偏差：**
-- `README.md` 与 `openspec/config.yaml` 多处描述“GORM Callback 自动注入数据权限过滤”，但当前 `internal/bootstrap/bootstrap.go` 第 67 行明确写明“数据权限过滤已移至 Store 层显式调用 ApplyXxxFilter 函数”。当前保留的 GORM Callback 只有 `pkg/gorm/callback.go` 中的创建人/更新人自动填充。
-- `internal/bootstrap/handlers.go` 为客户端场景直接新建多个 Store 和一个 `client_order` Service，而不是完全只消费 `services` 聚合；这说明 Handler 装配阶段存在读模型/适配层级的额外拼装。
-- `internal/task/polling_handler.go` 在首次实名激活流程中先构造 Asynq 任务，但实际通过 Redis List `RPush` 提交，文件内注释明确写出“实际应该通过依赖注入 asynq.Client”；这是 Worker 流程中的特殊机制与待收敛点。
-
----
-
-*Architecture analysis: 2026-03-27*

.planning/codebase/CONCERNS.md

@@ -1,173 +0,0 @@
-# Codebase Concerns
-
-**Analysis Date:** 2026-03-27
-
-## Tech Debt
-
-**配置与凭据管理（严重级别：Critical）:**
-- Issue: 仓库内存在已提交的生产/测试环境敏感配置与直连外部基础设施的写法，配置边界没有被代码、脚本和部署文件统一约束。
-- Files: `docker-compose.prod.yml`, `Makefile`, `pkg/config/defaults/config.yaml`, `scripts/verify_migration/main.go`, `scripts/verify_indexes/main.go`, `docs/deployment/deployment-guide.md`
-- Impact: 凭据轮换成本高；泄漏后影响数据库、Redis、对象存储、短信网关、Gateway 与部署链路；开发、测试、生产边界容易串用。
-- Supporting evidence:
-  - `docker-compose.prod.yml` 直接写入数据库、Redis、JWT、对象存储、Gateway、短信服务配置。
-  - `Makefile` 的 `DB_URL` 内嵌远程数据库连接串。
-  - `pkg/config/defaults/config.yaml` 为 `gateway.app_id`、`gateway.app_secret` 提供非空默认值，服务在未显式覆盖时仍会初始化 Gateway 客户端，见 `cmd/api/main.go:366-383`。
-  - `scripts/verify_migration/main.go` 与 `scripts/verify_indexes/main.go` 直接写死远程 PostgreSQL DSN。
-  - `docs/deployment/deployment-guide.md` 把 Registry 凭据与数据库连接示例直接写进文档。
-- Fix approach: 把所有密钥迁移到部署平台 Secret/环境注入；默认配置只保留空值；脚本统一改为读取环境变量；把示例文档改成占位符而不是真实值。
-- Suggested follow-up investigation topics:
-  - 盘点 `openspec/`, `docs/`, `scripts/` 中所有历史凭据残留。
-  - 审查 Gitea Secrets、Docker Registry、数据库、Redis、对象存储、短信网关、Gateway 的轮换计划。
-  - 检查 `.env`、`.env.local` 是否已在团队机器与 Runner 上扩散。
-
-**支付与微信配置迁移未闭环（严重级别：High）:**
-- Issue: 设计已经切到 `tb_wechat_config` + `payment_config_id`，但代码与文档仍保留环境变量和单例支付实现，处于半迁移状态。
-- Files: `docs/wechat-config-management/功能总结.md`, `internal/service/order/service.go`, `internal/service/recharge/service.go`, `internal/handler/callback/payment.go`, `docs/environment-variables.md`, `scripts/verify-wechat.sh`, `docker-compose.prod.yml`
-- Impact: 多支付配置切换、旧订单验签、客户端支付发起、OAuth 配置一致性存在行为不一致风险；运维很难判断哪些配置源仍然生效。
-- Supporting evidence:
-  - `docs/wechat-config-management/功能总结.md:232-238` 明确写着客户端支付发起仍是留桩，OAuth 仍从环境变量读取，且旧 `JUNHONG_WECHAT_PAYMENT_*` “可清理”。
-  - `internal/service/order/service.go:2107,2163,2356,2362` 与 `internal/service/recharge/service.go:271`、`internal/handler/callback/payment.go:66,143` 仍保留 TODO/留桩。
-  - `docs/environment-variables.md:36-69` 与 `scripts/verify-wechat.sh` 仍把微信支付环境变量当成必填启动前置条件。
-  - `docker-compose.prod.yml` 注释称“微信配置已迁移至数据库”，但部署文件仍维持部分旧式环境变量与其他支付相关外部配置模式。
-- Fix approach: 明确单一配置源；把“已迁移”“留桩”“仍依赖环境变量”的边界写入运维文档；在代码层补齐动态加载或删除旧入口。
-- Suggested follow-up investigation topics:
-  - 核实当前线上 OAuth 与支付分别读哪一套配置。
-  - 核查 `payment_config_id` 相关回调链路是否覆盖订单、资产充值、代理充值三条路径。
-  - 为未实现的客户端支付入口建立显式禁用清单。
-
-**核心服务体量过大（严重级别：High）:**
-- Issue: 部分核心服务文件已经远超团队规范中的函数/文件规模要求，维护成本和回归风险高。
-- Files: `internal/service/order/service.go`, `AGENTS.md`
-- Impact: 改动难以局部验证；支付、幂等、库存/余额、回调逻辑耦合；新需求更容易引入回归。
-- Supporting evidence:
-  - `AGENTS.md:371-375` 要求函数长度 ≤ 100 行，核心逻辑建议 ≤ 50 行。
-  - `internal/service/order/service.go` 的 TODO 已出现在 2107、2163、2356、2362 行，说明文件至少超过 2362 行。
-- Fix approach: 按支付发起、支付回调、订单状态流转、幂等与锁、钱包扣款等职责拆分子服务/辅助组件。
-- Suggested follow-up investigation topics:
-  - 统计 `internal/service/` 中超长文件与超长函数。
-  - 识别最常改动的热点段落与共享依赖。
-
-## Known Bugs
-
-**健康检查接口对故障返回 200 成功包裹（严重级别：High）:**
-- Symptoms: PostgreSQL 或 Redis 故障时，`/health` 仍通过 `response.Success` 返回成功包裹，只在 `data.status` 中标记 `degraded`。
-- Files: `internal/handler/health.go`, `docker-compose.prod.yml`, `Dockerfile.api`, `debug-deployment.sh`
-- Trigger: 数据库或 Redis Ping 失败。
-- Workaround: 监控端必须解析响应体里的 `data.status` 与 `services.*.status`，不能只看 HTTP 状态码。
-- Supporting evidence:
-  - `internal/handler/health.go:101-111` 注释与实现都明确“端点本身能响应即视为成功”。
-  - `docker-compose.prod.yml` 与 `Dockerfile.api` 的健康检查只执行 `wget --spider http://127.0.0.1:3000/health`，不会校验 JSON 内容。
-- Suggested follow-up investigation topics:
-  - 确认当前容器健康检查、反向代理、告警系统是否只看 200。
-  - 评估是否需要新增 `readyz`/`livez` 区分活性与依赖可用性。
-
-**API 路径文档与实际路由不一致（严重级别：Medium）:**
-- Symptoms: 文档仍混用 `/api/v1`、`/api/auth`、`/api/c/v1`，读者很难判断当前真实入口。
-- Files: `README.md`, `internal/routes/routes.go`, `scripts/check-comment-paths.sh`
-- Trigger: 新人按 README 试运行、按旧注释实现客户端、或依据文档回归接口。
-- Workaround: 以 `internal/routes/routes.go` 为准核对真实挂载路径。
-- Supporting evidence:
-  - `internal/routes/routes.go:21-39` 当前真实路由为 `/api/auth`、`/api/admin`、`/api/c/v1`、`/api/callback`。
-  - `README.md:577-583` 仍展示 `v1 := app.Group("/api/v1")` 的旧限流示例；`README.md:588-624` 仍以 `/api/v1/users` 讲解请求流。
-  - `scripts/check-comment-paths.sh` 只检查 `internal/handler/` 中残留 `/api/v1`，并不覆盖 `README.md`、`docs/`、`openspec/`。
-- Suggested follow-up investigation topics:
-  - 扫描所有 `docs/`, `README.md`, `openspec/`, `specs/` 中的旧路径。
-  - 明确哪些旧路径仍需要兼容，哪些应统一下线。
-
-## Security Considerations
-
-**部署流水线绕过 TLS 校验（严重级别：High）:**
-- Risk: 工作流检出步骤通过 `GIT_SSL_NO_VERIFY=1` 跳过证书校验，供应链完整性依赖内网信任而不是证书验证。
-- Files: `.gitea/workflows/deploy.yaml`
-- Current mitigation: 注释说明是“内网自签名证书”。
-- Recommendations: 为 Gitea/Registry 配置受信 CA；移除跳过校验；至少把跳过范围限制在明确的单一主机与受控 Runner。
-- Supporting evidence:
-  - `.gitea/workflows/deploy.yaml:23-27` 设置 `GIT_SSL_NO_VERIFY=1` 后执行 `git clone`。
-
-**对外/回调错误信息泄漏底层细节（严重级别：Medium）:**
-- Risk: 健康检查与富友回调把底层错误或内部状态直接返回给调用方，不符合统一错误暴露规范。
-- Files: `internal/handler/health.go`, `internal/handler/callback/payment.go`, `AGENTS.md`
-- Current mitigation: 有统一错误处理规范，但没有覆盖这两个特殊出口。
-- Recommendations: 对外返回统一错误码/固定消息，把底层错误仅写日志。
-- Supporting evidence:
-  - `AGENTS.md:124-129` 明确禁止直接暴露底层错误。
-  - `internal/handler/health.go:50-60,82-85` 直接返回 `err.Error()`。
-  - `internal/handler/callback/payment.go:178-191` 直接把 `err.Error()` 拼入富友回调失败响应。
-
-## Performance Bottlenecks
-
-**默认限流仍使用内存存储且默认关闭（严重级别：Medium）:**
-- Problem: 默认配置既不开启限流，也默认使用 `memory` 存储；多实例部署时无法形成统一配额。
-- Files: `pkg/config/defaults/config.yaml`, `cmd/api/main.go`, `README.md`
-- Cause: 配置更偏向本地开发便利，缺少生产默认值与环境级约束。
-- Improvement path: 明确生产必须启用 Redis 存储限流；在部署文档里给出环境变量模板；增加启动日志或自检提示当前限流模式。
-- Supporting evidence:
-  - `pkg/config/defaults/config.yaml:87-93` 默认 `enable_rate_limiter: false`、`storage: memory`。
-  - `cmd/api/main.go:236-278` 只有显式开启时才挂载限流，并根据配置选择 Redis 或内存存储。
-
-## Fragile Areas
-
-**OpenAPI 文档生成依赖手工双点维护（严重级别：Medium）:**
-- Files: `AGENTS.md`, `docs/api-documentation-guide.md`, `cmd/api/docs.go`, `cmd/gendocs/main.go`
-- Why fragile: 新增 Handler 必须同时更新两个文件；流程靠人工记忆，历史上已经出现清单不一致并专门做过修复。
-- Safe modification: 每次新增 Handler 时同时检查 `cmd/api/docs.go`、`cmd/gendocs/main.go` 与生成产物 `docs/admin-openapi.yaml`/`logs/openapi.yaml`。
-- Test coverage: 未发现自动化校验这两份清单一致性的 CI 步骤。
-- Supporting evidence:
-  - `AGENTS.md:53-65` 明确要求手工更新两个文件。
-  - `docs/api-documentation-guide.md` 多处把“忘记在两个文件中添加新 Handler”列为最常见问题。
-  - `.gitea/workflows/deploy.yaml` 中未见 `go run cmd/gendocs/main.go`、diff 校验或文档一致性检查。
-
-**部署脚本与运行时约定已漂移（严重级别：Medium）:**
-- Files: `debug-deployment.sh`, `docker-compose.prod.yml`, `README.md`, `docs/deployment/deployment-guide.md`
-- Why fragile: 诊断脚本仍假定旧环境变量名与外置配置文件存在，文档与当前嵌入式配置实现不完全一致。
-- Safe modification: 先以 `docker-compose.prod.yml`、`pkg/config/defaults/config.yaml`、`cmd/api/main.go` 为准修正运维脚本，再统一更新部署文档。
-- Test coverage: 未发现对诊断脚本、部署文档、健康检查语义的自动验证。
-- Supporting evidence:
-  - `debug-deployment.sh:52-57` 仍 grep `DB_|CONFIG_ENV`，并尝试读取 `/app/configs/config.yaml`；当前配置前缀实际是 `JUNHONG_`，配置默认嵌入二进制，见 `README.md:651-689`、`pkg/config/defaults/config.yaml`。
-  - `docs/deployment/deployment-guide.md:302-305` 仍建议从 `/app/.env` 拼接迁移命令，但容器实际入口用环境变量构造 DSN，见 `docker/entrypoint-api.sh:8-17`。
-
-## Scaling Limits
-
-**CI/CD 质量闸门过窄（严重级别：High）:**
-- Current capacity: 当前工作流只做 clone、build、push、main 分支部署。
-- Limit: 文档一致性、脚本检查、编译前规范、迁移安全、健康语义等问题都可能直接进入镜像与部署环境。
-- Scaling path: 在 `.gitea/workflows/deploy.yaml` 前置独立质量作业，至少执行 `bash scripts/check-all.sh`、`go build ./...`、OpenAPI 生成/校验，并在部署前验证 compose 文件与镜像健康策略。
-- Supporting evidence:
-  - `README.md:941-957` 声称脚本检查会在 CI/CD 自动执行。
-  - `.gitea/workflows/deploy.yaml` 未出现 `scripts/check-all.sh`、`go test`、`go vet`、`go build ./...`、OpenAPI 校验等步骤。
-
-## Dependencies at Risk
-
-**Go 版本与运行基础不统一（严重级别：Medium）:**
-- Risk: 版本声明分散在多个位置，升级与排障时容易出现“本地能过、容器不一致”的问题。
-- Impact: 构建环境复现、依赖升级与 bug 排查成本上升。
-- Migration plan: 约定单一权威版本源（如 `go.mod` + `.tool-versions`/`.go-version`），并让 Dockerfile、README、部署文档同步引用。
-- Supporting evidence:
-  - `go.mod:3` 使用 `go 1.25.0`。
-  - `Dockerfile.api:4` 与 `Dockerfile.worker:4` 使用 `golang:1.25.6-alpine`。
-  - `README.md:884` 写的是 `Go 1.25.1`。
-
-## Missing Critical Features
-
-**缺少可执行的自动化质量/回归入口（严重级别：High）:**
-- Problem: README、历史设计与测试文档大量提到 `go test`、`IntegrationTestEnv`、`tests/integration/`，但仓库当前未发现对应测试文件或 `tests/` 目录。
-- Blocks: 无法快速验证重构、支付回调、权限过滤、部署脚本变更；文档中的测试命令无法直接落地。
-- Supporting evidence:
-  - `AGENTS.md:324-354` 当前规范明确禁止自动化测试，和 `README.md:712-756`、`docs/testing/test-connection-guide.md` 的测试要求形成正面冲突。
-  - 读取仓库根目录未发现 `tests/` 目录；`glob` 搜索 `tests/**/*_test.go` 与 `internal/**/*_test.go` 未返回结果。
-  - `docs/testing/test-connection-guide.md` 仍宣称“204 个测试总耗时 ~10.5 秒”并要求所有新测试遵循该规范。
-
-## Test Coverage Gaps
-
-**部署、配置迁移、运维脚本与文档一致性未见自动验证（优先级：High）:**
-- What's not tested: `docker-compose.prod.yml`、`debug-deployment.sh`、`scripts/migrate.sh`、OpenAPI 文档生成器双清单、README/部署文档与代码的同步性。
-- Files: `.gitea/workflows/deploy.yaml`, `docker-compose.prod.yml`, `debug-deployment.sh`, `scripts/migrate.sh`, `cmd/api/docs.go`, `cmd/gendocs/main.go`, `README.md`
-- Risk: 配置漂移、凭据泄漏、文档错误、健康检查误报、迁移行为变化都可能在上线后才暴露。
-- Priority: High
-- Suggested follow-up investigation topics:
-  - 设计最小化“文档/脚本一致性检查”而不是恢复完整自动化测试体系。
-  - 评估是否要为部署文件与文档生成引入静态检查或 smoke check。
-
----
-
-*Concerns audit: 2026-03-27*

.planning/codebase/CONVENTIONS.md

@@ -1,168 +0,0 @@
-# Coding Conventions
-
-**Analysis Date:** 2026-03-27
-
-## Naming Patterns
-
-**Files:**
-- Go 源码使用 `snake_case.go` 或按领域拆分的普通小写命名；路由文件按模块命名放在 `internal/routes/*.go`，Handler 按域放在 `internal/handler/admin/*.go`、`internal/handler/auth/*.go`、`internal/handler/app/*.go`。
-- OpenAPI 与规范文档使用明确用途命名，例如 `docs/api-documentation-guide.md`、`docs/admin-openapi.yaml`、`cmd/api/docs.go`、`cmd/gendocs/main.go`。
-- 规范脚本使用动词前缀命名，例如 `scripts/check-all.sh`、`scripts/check-service-errors.sh`、`scripts/check-comment-paths.sh`、`scripts/verify_migration/main.go`。
-
-**Functions:**
-- 导出函数/方法使用 Go 的 `PascalCase`，例如 `NewAccountHandler()`、`Create()`、`Success()`、`RedisOrderIdempotencyKey()`，证据见 `internal/handler/admin/account.go`、`pkg/response/response.go`、`pkg/constants/redis.go`。
-- 未导出帮助函数使用 `camelCase`，例如 `generateOpenAPIDocs()`、`generateAdminDocs()`、`handleError()`、`safeLogWithLevel()`，证据见 `cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/errors/handler.go`。
-
-**Variables:**
-- 局部变量使用英文 `camelCase`，例如 `outputPath`、`httpStatus`、`roleID`、`groupPath`，证据见 `cmd/api/docs.go`、`pkg/errors/handler.go`、`internal/handler/admin/account.go`。
-- 错误变量统一使用 `err`，成功返回数据常用业务名，例如 `account`、`accounts`、`roles`，证据见 `internal/handler/admin/account.go`。
-
-**Types:**
-- 结构体和接口使用 `PascalCase`，接口语义化命名，配合 `-er` 后缀规则；项目规范明确要求接口名使用 `-er`，见 `AGENTS.md`。
-- 路由文档元数据类型使用语义名，如 `RouteSpec`、`FileUploadField`，证据见 `internal/routes/registry.go`。
-
-## Code Style
-
-**Formatting:**
-- 使用 `gofmt`；项目在 `AGENTS.md` 明确要求“使用 gofmt 格式化”。
-- 代码风格遵循 Go 惯用法，避免 Java 式过度抽象；证据见 `AGENTS.md` 的“Go 惯用法 vs Java 风格”。
-
-**Linting / Scripted Checks:**
-- 仓库未检测到 `.golangci.yml`、`golangci-lint`、`eslint`、`prettier` 之类自动 lint 配置；当前质量门主要依赖 shell 脚本和人工审查。
-- `scripts/check-service-errors.sh`：扫描 `internal/service/**/*.go` 中的 `fmt.Errorf`，要求改用 `errors.New()` / `errors.Wrap()`。
-- `scripts/check-comment-paths.sh`：扫描 `internal/handler/` 中残留的 `/api/v1` 注释，要求改成真实路径 `/api/admin`、`/api/h5`、`/api/c/v1`。
-- `scripts/check-all.sh`：串行执行以上两个检查。
-- 当前仓库与脚本规则存在冲突：`internal/service/polling/alert_service.go` 仍存在 4 处 `fmt.Errorf(...)`，按 `scripts/check-service-errors.sh` 的规则属于违规现状。
-
-## Language & Comment Requirements
-
-**语言要求：**
-- 用户可见内容、日志、注释、文档、提交信息都使用中文；变量名、函数名、类型名使用英文，证据见 `AGENTS.md` 的“语言要求”。
-
-**注释要求：**
-- 导出包、结构体、接口、函数、方法、常量、变量必须有中文文档注释，证据见 `AGENTS.md`。
-- Handler 方法注释必须包含 HTTP 方法与真实路径；实际示例见 `internal/handler/admin/account.go`、`internal/handler/callback/payment.go`。
-- 注释解释“为什么”，不要复述代码；复杂逻辑必须有实现注释，证据见 `AGENTS.md`。
-- 常量必须带中文注释；实际示例见 `pkg/constants/constants.go`、`pkg/constants/redis.go`。
-
-## Import Organization
-
-**Order:**
-1. Go 标准库，例如 `strconv`、`time`、`regexp`。
-2. 第三方库，例如 `github.com/gofiber/fiber/v2`、`go.uber.org/zap`。
-3. 项目内包，例如 `github.com/break/junhong_cmp_fiber/pkg/errors`、`internal/service/account`。
-
-**Pattern:**
-- 多数组件按“标准库 → 项目包/第三方包”分组，并保留空行分隔，证据见 `internal/handler/admin/account.go`、`pkg/errors/handler.go`、`cmd/gendocs/main.go`。
-- 项目使用完整 module import path，未体现短别名路径；必要时用语义别名，例如 `apphandler`、`accountService`，证据见 `cmd/gendocs/main.go`、`internal/handler/admin/account.go`。
-
-**Path Aliases:**
-- 未检测到 TS/JS 式路径别名；Go 代码通过 module path `github.com/break/junhong_cmp_fiber/...` 引用。
-
-## Layering Rules
-
-**Required Architecture:**
-- 必须遵循 `Handler → Service → Store → Model`，证据见 `AGENTS.md` 与 `README.md`。
-
-**How to apply it:**
-- Handler 只做参数解析、上下文读取、调用 service、返回统一响应；示例见 `internal/handler/admin/account.go`。
-- Service 承载业务逻辑，并向下调用 Store；项目规范在 `AGENTS.md` 明确禁止在 Handler 中写业务逻辑。
-- Store 负责数据访问和事务；规范说明见 `AGENTS.md`、`README.md`。
-- Model/DTO 定义请求、响应和持久化结构；OpenAPI 文档也依赖 DTO 元数据，证据见 `docs/api-documentation-guide.md`。
-
-## Error Handling
-
-**Centralized package:**
-- 所有错误码与应用错误类型集中在 `pkg/errors/`，证据见 `pkg/errors/codes.go`、`pkg/errors/errors.go`、`pkg/errors/handler.go`、`AGENTS.md`。
-
-**Rules to follow:**
-- Handler 层不要把底层错误直接暴露给客户端；参数校验失败统一返回 `errors.New(errors.CodeInvalidParam)` 或其中文变体，证据见 `AGENTS.md`、`internal/handler/admin/account.go`。
-- Service 层对外不要返回 `fmt.Errorf(...)`，要返回 `errors.New(...)` 或 `errors.Wrap(...)`；脚本 `scripts/check-service-errors.sh` 专门检查这一点。
-- 全局错误处理使用 `pkg/errors/handler.go` 的 `SafeErrorHandler()` / `handleError()`，统一输出 `{code, data, msg, timestamp}`，并按错误码映射 HTTP 状态码与日志级别。
-- 5xx 响应统一走通用中文消息，避免泄露敏感信息，证据见 `pkg/errors/handler.go`。
-
-**Error code system:**
-- `pkg/errors/codes.go` 定义 1000-1999 客户端错误、2000-2999 服务端错误。
-- `pkg/errors/codes.go` 在 `init()` 校验全部错误码都必须映射消息，新增错误码时要同步维护 `allErrorCodes` 和 `errorMessages`。
-
-## Response Format
-
-**Envelope:**
-- 所有 API 成功响应统一使用 `pkg/response/response.go`：`{code, data, msg, timestamp}`。
-- `Success()` 返回 `msg: "success"`；`SuccessWithMessage()` 允许覆盖消息；`SuccessWithPagination()` 将分页数据包进 `PaginationData`。
-
-**How handlers should respond:**
-- Handler 成功路径直接调用 `response.Success()` / `response.SuccessWithPagination()`；实际示例见 `internal/handler/admin/account.go`、`internal/handler/admin/iot_card.go`、`internal/handler/admin/shop.go`。
-- 错误路径直接 `return err` 交给全局 ErrorHandler，不在 Handler 内手动拼接 JSON，证据见 `internal/handler/admin/account.go`、`pkg/errors/handler.go`。
-
-## Constant Management
-
-**Location:**
-- 所有常量统一放在 `pkg/constants/`，证据见 `AGENTS.md` 与 `pkg/constants/constants.go`、`pkg/constants/redis.go`。
-
-**Rules to follow:**
-- 禁止硬编码字符串与 magic numbers；公共业务值放进 `pkg/constants/constants.go`。
-- Redis Key 必须通过函数生成，而不是手写字符串，命名格式使用 `Redis{Module}{Purpose}Key(...)`，证据见 `pkg/constants/redis.go` 与 `AGENTS.md`。
-- 常量要配中文注释；`pkg/constants/constants.go` 中的用户类型、任务类型、分页上限、默认管理员信息都按此方式组织。
-
-## API / OpenAPI Conventions
-
-**Route registration:**
-- 所有 HTTP 路由都应在 `internal/routes/*.go` 中通过 `Register()` 注册，不要直接 `router.Get/Post/...`，证据见 `docs/api-documentation-guide.md`、`internal/routes/registry.go`。
-- `Register()` 同时负责 Fiber 路由注册和 OpenAPI 生成；当 `doc != nil` 时，会把 `/:id` 转为 OpenAPI 的 `/{id}`，证据见 `internal/routes/registry.go`。
-
-**RouteSpec requirements:**
-- 每个接口需要提供中文 `Summary`，可选 Markdown `Description`，并声明 `Input`、`Output`、`Tags`、`Auth`；证据见 `internal/routes/registry.go`、`docs/api-documentation-guide.md`。
-- DTO 字段必须使用 `description` 标签，不依赖行尾注释；枚举字段要在 `description` 中列出可选值，证据见 `docs/api-documentation-guide.md`。
-
-**Handler + docs generator sync:**
-- 新增 Handler 时，除业务接线外，还必须同步更新 `internal/bootstrap/types.go`、`internal/bootstrap/handlers.go`、`internal/routes/admin.go`、`cmd/api/docs.go`、`cmd/gendocs/main.go`，证据见 `docs/api-documentation-guide.md` 与 `AGENTS.md`。
-- 文档生成命令使用 `go run cmd/gendocs/main.go` 或 `make docs`；代码证据见 `cmd/gendocs/main.go`、`Makefile`。
-
-## Documentation Expectations
-
-**Required docs workflow:**
-- 每个功能应在 `docs/{feature-id}/` 创建总结文档，并同步更新 `README.md`，证据见 `AGENTS.md`。
-- 文档和说明统一使用中文。
-- API 文档规范集中在 `docs/api-documentation-guide.md`；开发总规范集中在 `AGENTS.md`。
-
-**Repository reality:**
-- `README.md` 仍保留旧的自动化测试与覆盖率章节、旧项目结构中的 `tests/` 目录描述、以及“CI/CD 自动执行检查”的表述。
-- 当前仓库未发现任何 `*_test.go` 文件，也未发现 `tests/` 目录内容；因此后续文档和执行应优先遵循 `AGENTS.md` 的现行规则，而不是 `README.md` 中这些过期段落。
-
-## Operational Scripts
-
-**Quality / convention scripts:**
-- `bash scripts/check-service-errors.sh`：检查 Service 层是否违规使用 `fmt.Errorf`。
-- `bash scripts/check-comment-paths.sh`：检查 Handler 注释路径是否残留 `/api/v1`。
-- `bash scripts/check-all.sh`：运行上述两个检查。
-
-**Documentation script:**
-- `make docs` → `go run cmd/gendocs/main.go`，用于生成 `docs/admin-openapi.yaml`，证据见 `Makefile`、`cmd/gendocs/main.go`。
-
-**Migration verification helper:**
-- `go run scripts/verify_migration/main.go`：这是一个面向数据库迁移结果的人工验证脚本，会直接连接数据库并查询字段，不是自动测试框架，证据见 `scripts/verify_migration/main.go`。
-
-**Caution:**
-- `Makefile` 的 `test` 目标仍定义为 `go test -v ./...`，但这反映的是旧工具入口，不代表当前团队允许自动化测试。
-
-## Module Design
-
-**Exports:**
-- 构造函数使用 `NewXxx...`，例如 `NewAccountHandler()`、`NewGenerator()`。
-- Handler、response、errors、constants 都以小包单职责方式导出少量明确入口，证据见 `internal/handler/admin/account.go`、`pkg/response/response.go`、`pkg/errors/errors.go`。
-
-**Barrel Files:**
-- 未检测到 JS/TS 式 barrel file；Go 通过包目录与导出符号组织模块。
-
-## Prescriptive Summary
-
-- 写新 Handler 时：在 `internal/handler/...` 保持中文注释 + 英文标识符，只解析请求并调用 Service，成功统一走 `pkg/response/response.go`，失败直接返回 `error`。
-- 写新业务错误时：先在 `pkg/errors/codes.go` 注册错误码与中文消息，再用 `errors.New()` / `errors.Wrap()`。
-- 写新常量或 Redis Key 时：放入 `pkg/constants/`，并补中文注释与 Key 生成函数。
-- 写新 API 时：在 `internal/routes/*.go` 用 `Register()` + `RouteSpec` 注册，并同步更新 `cmd/api/docs.go` 与 `cmd/gendocs/main.go` 的文档 Handler 装配。
-- 运行规范检查时：优先使用 `scripts/check-*.sh` 与 `make docs`；不要把 `README.md` 中的测试/覆盖率描述当成当前执行标准。
-
----
-
-*Convention analysis: 2026-03-27*

.planning/codebase/INTEGRATIONS.md

@@ -1,215 +0,0 @@
-# External Integrations
-
-**Analysis Date:** 2026-03-27
-
-## APIs & External Services
-
-**Database / Cache Infrastructure:**
-- PostgreSQL - 主业务数据库，GORM 通过 DSN 建连并配置连接池，见 `pkg/database/postgres.go`
-  - Client: `gorm.io/gorm` + `gorm.io/driver/postgres`
-  - Config: `pkg/config/config.go` 的 `database.*`
-- Redis - Token、缓存、Asynq 后端、限流存储、微信配置缓存，见 `pkg/database/redis.go`、`pkg/queue/client.go`、`cmd/api/main.go`、`internal/service/wechat_config/service.go`
-  - Client: `github.com/redis/go-redis/v9`
-  - Config: `pkg/config/config.go` 的 `redis.*`
-
-**Object Storage:**
-- S3-compatible object storage - 文件直传、下载、导入任务临时落盘，见 `pkg/storage/s3.go`、`pkg/storage/service.go`
-  - SDK/Client: `github.com/aws/aws-sdk-go`
-  - Config: `storage.provider`、`storage.s3.*`、`storage.presign.*` in `pkg/config/config.go`
-  - Used by: `internal/handler/admin/storage.go`、`internal/routes/storage.go`、`internal/task/iot_card_import.go`、`internal/task/device_import.go`
-
-**WeChat ecosystem:**
-- WeChat Official Account OAuth - 公众号登录与用户信息拉取，见 `pkg/wechat/official_account.go`、`internal/service/client_auth/service.go`
-  - SDK/Client: `github.com/ArtisanCloud/PowerWeChat/v3`
-  - Config source: `tb_wechat_config` via `internal/model/wechat_config.go`
-- WeChat Mini Program login - `code2session` 换取 openid/session_key，见 `pkg/wechat/miniapp.go`、`internal/service/client_auth/service.go`
-  - Transport: 标准 `net/http`
-  - Config source: `tb_wechat_config`
-- WeChat Pay - JSAPI/H5 下单、查单、关单、支付回调验签，见 `pkg/wechat/payment.go`、`pkg/wechat/config.go`、`internal/handler/callback/payment.go`
-  - SDK/Client: `github.com/ArtisanCloud/PowerWeChat/v3`
-  - Config source: `tb_wechat_config`
-
-**Payment gateway:**
-- Fuiou - 预下单、回调解析、签名与验签 SDK 已存在，见 `pkg/fuiou/client.go`、`pkg/fuiou/wxprecreate.go`、`pkg/fuiou/notify.go`
-  - SDK/Client: repo-local `pkg/fuiou`
-  - Config source: `tb_wechat_config` provider=`fuiou`，字段位于 `internal/model/wechat_config.go`
-  - Callback endpoint: `internal/handler/callback/payment.go`
-  - Current state: 回调处理存在 `TODO`，当前路径解析 XML 但未按配置创建客户端做验签，见 `internal/handler/callback/payment.go`
-
-**SMS gateway:**
-- SMS HTTP gateway - 验证码/消息发送，见 `pkg/sms/client.go`、`cmd/api/main.go`
-  - Client: repo-local `pkg/sms`
-  - Config: `sms.gateway_url`、`sms.username`、`sms.password`、`sms.signature` in `pkg/config/config.go`
-
-**Business Gateway / IoT upstream:**
-- Gateway API - 设备信息、卡状态、流量、实名链接、设备限速/切卡等外部接口，见 `internal/gateway/client.go`、`internal/gateway/device.go`、`internal/gateway/flow_card.go`
-  - Auth: appId + appSecret，自定义 AES-128-ECB 加密 + MD5 签名，见 `internal/gateway/client.go`
-  - Config: `gateway.base_url`、`gateway.app_id`、`gateway.app_secret`、`gateway.timeout` in `pkg/config/config.go`
-  - Used by: `internal/service/iot_card/gateway_service.go`、`internal/service/device/gateway_service.go`、`internal/task/polling_handler.go`
-
-## Data Storage
-
-**Databases:**
-- PostgreSQL
-  - Connection keys: `JUNHONG_DATABASE_HOST`, `JUNHONG_DATABASE_PORT`, `JUNHONG_DATABASE_USER`, `JUNHONG_DATABASE_PASSWORD`, `JUNHONG_DATABASE_DBNAME`, `JUNHONG_DATABASE_SSLMODE`
-  - Connection code: `pkg/database/postgres.go`
-  - Runtime wiring: `cmd/api/main.go`, `cmd/worker/main.go`, `docker-compose.prod.yml`
-
-**Redis:**
-- Redis is shared across auth, cache, rate limiting, WeChat config cache, and Asynq
-  - Connection keys: `JUNHONG_REDIS_ADDRESS`, `JUNHONG_REDIS_PORT`, `JUNHONG_REDIS_PASSWORD`, `JUNHONG_REDIS_DB`
-  - Connection code: `pkg/database/redis.go`
-  - Asynq reuse: `pkg/queue/client.go`, `pkg/queue/server.go`
-  - Config cache key example: `wechat:config:active` in `internal/service/wechat_config/service.go`
-
-**File Storage:**
-- S3-compatible bucket storage
-  - Provider implementation: `pkg/storage/s3.go`
-  - Upload URL API: `internal/routes/storage.go`
-  - Import consumers download to temp files before parsing: `internal/task/iot_card_import.go`, `internal/task/device_import.go`
-
-**Local filesystem:**
-- Logs are persisted to `/app/logs` inside containers and mounted by Compose, see `pkg/config/defaults/config.yaml`, `Dockerfile.api`, `Dockerfile.worker`, `docker-compose.prod.yml`
-- OpenAPI runtime export writes to `logs/openapi.yaml`, see `cmd/api/main.go`, `cmd/api/docs.go`
-
-## Authentication & Identity
-
-**B-side auth:**
-- Redis-backed token management and JWT manager initialization occur in `cmd/api/main.go`
-  - Components: `pkg/auth`, Redis token manager, JWT manager
-
-**C-side identity via WeChat:**
-- 公众号 OAuth login path uses active config from `tb_wechat_config`, see `internal/service/client_auth/service.go`
-- 小程序 login path uses WeChat `code2session`, see `internal/service/client_auth/service.go`, `pkg/wechat/miniapp.go`
-
-## Monitoring & Observability
-
-**Application logs:**
-- Zap + Lumberjack app/access loggers, see `pkg/logger/logger.go`
-
-**Request tracing:**
-- Access logger captures request metadata and request/response bodies, see `pkg/logger/middleware.go`
-
-**SQL observability:**
-- GORM logger sends query errors and slow queries to Zap, see `pkg/database/postgres.go`
-
-**Container health:**
-- API health endpoint is used by Docker health checks and Compose dependency ordering, see `Dockerfile.api`, `docker-compose.prod.yml`
-
-## Queue, Scheduling, and Runtime Integrations
-
-**Asynq runtime:**
-- Worker server consumes Redis-backed queues configured in `queue.*`, see `pkg/queue/server.go`, `cmd/worker/main.go`
-- Task submission is wrapped in `pkg/queue/client.go`
-
-**Registered task domains:**
-- Email, data sync, SIM status sync, IoT card import, device import, commission stats, commission calculation, polling, package activation, order expiration, alert check, data cleanup, see `pkg/queue/handler.go`
-
-**Schedulers:**
-- Worker process starts an internal polling scheduler plus an Asynq Scheduler for recurring jobs, see `cmd/worker/main.go`
-- Recurring jobs include order expiration, alert checks, and nightly cleanup, see `cmd/worker/main.go`
-
-## Docs Generation Integrations
-
-**OpenAPI generation:**
-- Repo-local generator wraps `swaggest/openapi-go` and exports YAML, see `pkg/openapi/generator.go`
-- Runtime generation during API boot writes `logs/openapi.yaml`, see `cmd/api/main.go`, `cmd/api/docs.go`
-- Manual generation command writes `docs/admin-openapi.yaml`, see `Makefile`, `cmd/gendocs/main.go`
-- Route registration for docs reuses production route registration, see `internal/routes/routes.go`, `pkg/openapi/handlers.go`
-
-## CI/CD & Deployment
-
-**Hosting / Runtime:**
-- Dockerized API and Worker services are the deployment target, see `Dockerfile.api`, `Dockerfile.worker`, `docker-compose.prod.yml`
-
-**Registry:**
-- Images are pushed to a private registry declared in `.gitea/workflows/deploy.yaml`
-
-**CI Pipeline:**
-- Gitea workflow builds both images, pushes tag + SHA tags, copies `docker-compose.prod.yml`, and executes `docker compose pull/up -d`, see `.gitea/workflows/deploy.yaml`
-
-**Migration tooling:**
-- API image bundles `golang-migrate` and migration files, see `Dockerfile.api`
-- Local migration shortcuts are defined in `Makefile`
-
-## Environment Configuration
-
-**Required env vars:**
-- Database: `JUNHONG_DATABASE_HOST`, `JUNHONG_DATABASE_PORT`, `JUNHONG_DATABASE_USER`, `JUNHONG_DATABASE_PASSWORD`, `JUNHONG_DATABASE_DBNAME`
-- Redis: `JUNHONG_REDIS_ADDRESS` plus optional Redis port/password/db tuning vars
-- JWT: `JUNHONG_JWT_SECRET_KEY`
-
-**Optional env vars by integration:**
-- Storage: `JUNHONG_STORAGE_PROVIDER`, `JUNHONG_STORAGE_S3_*`
-- SMS: `JUNHONG_SMS_*`
-- Gateway: `JUNHONG_GATEWAY_*`
-- Logging: `JUNHONG_LOGGING_*`
-
-**Secrets location:**
-- Default app config is embedded from `pkg/config/defaults/config.yaml`
-- Most runtime secrets are expected through environment variables bound in `pkg/config/loader.go`
-- WeChat / payment provider secrets are stored in database table `tb_wechat_config`, see `internal/model/wechat_config.go`
-- Deployment wiring exists in `docker-compose.prod.yml` and `.gitea/workflows/deploy.yaml`; these files should be treated as sensitive and are not reproduced here
-
-## Webhooks & Callbacks
-
-**Incoming:**
-- WeChat Pay callback: `POST /api/callback/wechat-pay`, handler in `internal/handler/callback/payment.go`
-- Fuiou Pay callback: `POST /api/callback/fuiou-pay`, handler in `internal/handler/callback/payment.go`
-- Alipay callback stub: `POST /api/callback/alipay`, handler in `internal/handler/callback/payment.go`
-
-**Outgoing:**
-- WeChat OAuth and payment API calls from `pkg/wechat/*.go`
-- Gateway API calls from `internal/gateway/*.go`
-- SMS API calls from `pkg/sms/client.go`
-- S3 object storage calls from `pkg/storage/s3.go`
-
-## Evidence
-
-- `go.mod`
-- `README.md`
-- `cmd/api/main.go`
-- `cmd/api/docs.go`
-- `cmd/worker/main.go`
-- `cmd/gendocs/main.go`
-- `pkg/config/config.go`
-- `pkg/config/loader.go`
-- `pkg/config/defaults/config.yaml`
-- `pkg/database/postgres.go`
-- `pkg/database/redis.go`
-- `pkg/queue/client.go`
-- `pkg/queue/server.go`
-- `pkg/queue/handler.go`
-- `pkg/logger/logger.go`
-- `pkg/openapi/generator.go`
-- `pkg/openapi/handlers.go`
-- `pkg/storage/s3.go`
-- `pkg/storage/service.go`
-- `pkg/wechat/config.go`
-- `pkg/wechat/official_account.go`
-- `pkg/wechat/miniapp.go`
-- `pkg/wechat/payment.go`
-- `pkg/fuiou/client.go`
-- `pkg/fuiou/wxprecreate.go`
-- `pkg/fuiou/notify.go`
-- `pkg/sms/client.go`
-- `internal/gateway/client.go`
-- `internal/gateway/device.go`
-- `internal/gateway/flow_card.go`
-- `internal/model/wechat_config.go`
-- `internal/service/wechat_config/service.go`
-- `internal/service/client_auth/service.go`
-- `internal/service/client_order/service.go`
-- `internal/routes/storage.go`
-- `internal/handler/callback/payment.go`
-- `internal/task/iot_card_import.go`
-- `internal/task/device_import.go`
-- `Makefile`
-- `Dockerfile.api`
-- `Dockerfile.worker`
-- `docker-compose.prod.yml`
-- `.gitea/workflows/deploy.yaml`
-
----
-
-*Integration audit: 2026-03-27*

.planning/codebase/STACK.md

@@ -1,177 +0,0 @@
-# Technology Stack
-
-**Analysis Date:** 2026-03-27
-
-## Languages
-
-**Primary:**
-- Go 1.25.x - 应用代码、API、Worker、OpenAPI 生成和基础设施脚本，依据 `go.mod`、`cmd/api/main.go`、`cmd/worker/main.go`、`cmd/gendocs/main.go`
-
-**Secondary:**
-- YAML - 配置与部署编排，见 `pkg/config/defaults/config.yaml`、`docker-compose.prod.yml`、`.gitea/workflows/deploy.yaml`
-- Dockerfile - API/Worker 容器构建，见 `Dockerfile.api`、`Dockerfile.worker`
-- Makefile - 本地构建、文档生成、迁移命令，见 `Makefile`
-
-## Runtime
-
-**Environment:**
-- Go runtime；API 服务基于 Fiber HTTP 服务器，见 `cmd/api/main.go`
-- 独立 Worker 进程处理异步任务与调度，见 `cmd/worker/main.go`
-- 生产容器基础镜像为 Alpine，构建镜像使用 Go 1.25.6 Alpine，见 `Dockerfile.api`、`Dockerfile.worker`
-
-**Package Manager:**
-- Go Modules，见 `go.mod`
-- Lockfile: `go.sum` present
-
-## Frameworks
-
-**Core:**
-- Fiber v2.52.9 - HTTP 框架与路由宿主，见 `go.mod`、`cmd/api/main.go`
-- GORM v1.31.1 + `gorm.io/driver/postgres` v1.6.0 - PostgreSQL ORM 与连接层，见 `go.mod`、`pkg/database/postgres.go`
-- Viper v1.21.0 - 嵌入式默认配置 + 环境变量覆盖，见 `go.mod`、`pkg/config/loader.go`
-
-**Queue / Scheduling:**
-- Asynq v0.25.1 - 任务提交、Worker 消费、定时任务，见 `go.mod`、`pkg/queue/client.go`、`pkg/queue/server.go`、`cmd/worker/main.go`
-
-**Serialization / Validation:**
-- sonic v1.14.2 - Fiber JSON 编解码与任务载荷序列化，见 `go.mod`、`cmd/api/main.go`、`pkg/queue/client.go`
-- validator/v10 v10.28.0 - DTO 校验依赖，见 `go.mod`
-
-**Logging:**
-- zap v1.27.1 - 应用日志与 SQL 日志，见 `go.mod`、`pkg/logger/logger.go`、`pkg/database/postgres.go`
-- lumberjack.v2 v2.2.1 - 日志轮转，见 `go.mod`、`pkg/logger/logger.go`
-
-**Docs tooling:**
-- swaggest/openapi-go v0.2.60 - OpenAPI 3.0.3 文档生成，见 `go.mod`、`pkg/openapi/generator.go`
-
-## Build / Dev / Deploy
-
-**Build:**
-- `Makefile` 定义 `build`、`run`、`run-worker`、`docs`、`migrate-*` 目标，见 `Makefile`
-- API 与 Worker 使用多阶段 Docker 构建，编译产物分别来自 `./cmd/api` 与 `./cmd/worker`，见 `Dockerfile.api`、`Dockerfile.worker`
-
-**Deploy:**
-- 生产编排使用 Docker Compose，运行 `api` 与 `worker` 两个服务，见 `docker-compose.prod.yml`
-- Gitea Actions 工作流构建镜像、推送私有镜像仓库并在主分支执行 `docker compose up -d`，见 `.gitea/workflows/deploy.yaml`
-
-**Docs generation:**
-- API 启动时会生成 `logs/openapi.yaml`，见 `cmd/api/main.go`、`cmd/api/docs.go`
-- 手动文档命令 `make docs` 运行 `cmd/gendocs/main.go`，输出 `docs/admin-openapi.yaml`，见 `Makefile`、`cmd/gendocs/main.go`
-
-## Storage, Data, Messaging
-
-**Database:**
-- PostgreSQL 是唯一检测到的主数据库；连接、连接池、GORM logger、Ping 校验位于 `pkg/database/postgres.go`
-
-**Cache / KV:**
-- Redis 用于认证、缓存、队列后端、限流存储和配置缓存，见 `pkg/database/redis.go`、`cmd/api/main.go`、`internal/service/wechat_config/service.go`
-
-**Messaging / Queue:**
-- Asynq 直接复用 Redis 连接配置作为消息后端，见 `pkg/queue/client.go`、`pkg/queue/server.go`
-- Worker 内注册订单超时、告警检查、数据清理等调度任务，见 `cmd/worker/main.go`
-
-**Object storage:**
-- S3 兼容对象存储通过 AWS SDK v1 实现，支持上传、下载、预签名 URL、临时文件下载，见 `pkg/storage/s3.go`、`pkg/storage/service.go`
-
-## Configuration
-
-**Loading model:**
-- 默认配置从嵌入文件 `pkg/config/defaults/config.yaml` 读取，见 `pkg/config/embedded.go`
-- 运行时使用 `JUNHONG_` 前缀环境变量覆盖，见 `pkg/config/loader.go`
-- 必填配置校验包括数据库、Redis、JWT，见 `pkg/config/config.go`
-
-**Key config areas:**
-- 服务与超时：`server.*`，见 `pkg/config/config.go`
-- PostgreSQL：`database.*`，见 `pkg/config/config.go`
-- Redis：`redis.*`，见 `pkg/config/config.go`
-- Asynq：`queue.*`，见 `pkg/config/config.go`
-- 日志：`logging.*`，见 `pkg/config/config.go`
-- 短信：`sms.*`，见 `pkg/config/config.go`
-- 对象存储：`storage.*`，见 `pkg/config/config.go`
-- 外部 Gateway：`gateway.*`，见 `pkg/config/config.go`
-
-**WeChat config exception:**
-- 微信公众号/小程序/支付配置不走 Viper 主配置，业务侧从数据库表 `tb_wechat_config` 读取并缓存到 Redis，见 `internal/model/wechat_config.go`、`internal/service/wechat_config/service.go`、`pkg/wechat/config.go`
-
-## Logging & Observability
-
-**Application logs:**
-- `pkg/logger/logger.go` 初始化 app/access 双 logger；生产模式写 JSON，开发模式 app logger 同时输出控制台
-
-**Access logs:**
-- `pkg/logger/middleware.go` 记录 method、path、query、status、duration、request_id、ip、user_agent、user_id、请求/响应 body
-
-**SQL logs:**
-- `pkg/database/postgres.go` 自定义 GORM logger，记录错误、慢查询和普通 SQL trace
-
-**Health checks:**
-- `Dockerfile.api` 与 `docker-compose.prod.yml` 均通过 `GET /health` 做容器健康检查
-
-## Notable Dependencies
-
-**HTTP / App:**
-- `github.com/gofiber/fiber/v2` - API 服务核心框架，见 `go.mod`、`cmd/api/main.go`
-- `github.com/google/uuid` - 请求 ID 生成，见 `cmd/api/main.go`
-
-**Persistence / Cache:**
-- `gorm.io/gorm`、`gorm.io/driver/postgres` - ORM 与 PostgreSQL 驱动，见 `go.mod`、`pkg/database/postgres.go`
-- `github.com/redis/go-redis/v9` - Redis 客户端，见 `go.mod`、`pkg/database/redis.go`
-
-**Queue / Async:**
-- `github.com/hibiken/asynq` - 队列与调度器，见 `go.mod`、`pkg/queue/*.go`、`cmd/worker/main.go`
-
-**Serialization / File processing:**
-- `github.com/bytedance/sonic` - JSON 编解码，见 `cmd/api/main.go`、`pkg/queue/client.go`
-- `github.com/xuri/excelize/v2` - Excel 导入处理依赖，见 `go.mod`; 任务消费方在 `internal/task/iot_card_import.go`、`internal/task/device_import.go` 调用 Excel 解析
-
-**External SDKs:**
-- `github.com/ArtisanCloud/PowerWeChat/v3` - 微信公众号与微信支付 SDK，见 `go.mod`、`pkg/wechat/official_account.go`、`pkg/wechat/payment.go`
-- `github.com/aws/aws-sdk-go` - S3 兼容对象存储客户端，见 `go.mod`、`pkg/storage/s3.go`
-
-## Platform Requirements
-
-**Development:**
-- 需要 PostgreSQL、Redis、JWT 密钥与 `JUNHONG_` 环境变量；`config.Load()` 在启动时强校验，见 `pkg/config/config.go`
-- `make docs` 需要 Go 环境；`migrate-*` 目标需要系统安装 `migrate` 命令，见 `Makefile`
-
-**Production:**
-- 目标运行形态是 Docker 化 API + Worker 双进程部署，见 `Dockerfile.api`、`Dockerfile.worker`、`docker-compose.prod.yml`
-- 镜像发布到私有仓库 `registry.boss160.cn`，见 `.gitea/workflows/deploy.yaml`
-
-## Evidence
-
-- `go.mod`
-- `README.md`
-- `cmd/api/main.go`
-- `cmd/api/docs.go`
-- `cmd/worker/main.go`
-- `cmd/gendocs/main.go`
-- `pkg/config/config.go`
-- `pkg/config/loader.go`
-- `pkg/config/embedded.go`
-- `pkg/config/defaults/config.yaml`
-- `pkg/database/postgres.go`
-- `pkg/database/redis.go`
-- `pkg/queue/client.go`
-- `pkg/queue/server.go`
-- `pkg/queue/handler.go`
-- `pkg/logger/logger.go`
-- `pkg/logger/middleware.go`
-- `pkg/openapi/generator.go`
-- `pkg/openapi/handlers.go`
-- `pkg/storage/s3.go`
-- `pkg/storage/service.go`
-- `pkg/wechat/config.go`
-- `pkg/wechat/official_account.go`
-- `pkg/wechat/payment.go`
-- `pkg/sms/client.go`
-- `internal/gateway/client.go`
-- `Makefile`
-- `Dockerfile.api`
-- `Dockerfile.worker`
-- `docker-compose.prod.yml`
-- `.gitea/workflows/deploy.yaml`
-
----
-
-*Stack analysis: 2026-03-27*

.planning/codebase/STRUCTURE.md

@@ -1,250 +0,0 @@
-# Codebase Structure
-
-**Analysis Date:** 2026-03-27
-
-## Directory Layout
-
-```text
-junhong_cmp_fiber/
-├── cmd/                 # API、Worker、文档生成入口
-├── internal/            # 核心业务代码（handler/service/store/model/routes/bootstrap/task）
-├── pkg/                 # 可复用基础设施与跨模块工具
-├── migrations/          # SQL 迁移脚本
-├── docs/                # 业务文档、接入指南、架构说明
-├── openspec/            # 当前能力规格与变更档案
-├── specs/               # 早期 Speckit 规格文档
-├── scripts/             # 检查与初始化脚本
-├── docker/              # 部署相关辅助文件
-├── logs/                # 运行期日志输出目录
-└── .planning/codebase/  # 当前代码地图产物
-```
-
-## Directory Purposes
-
-**`cmd/`:**
-- Purpose: 进程级入口和独立命令。
-- Contains: `cmd/api/main.go`, `cmd/api/docs.go`, `cmd/worker/main.go`, `cmd/gendocs/main.go`
-- Key files: `cmd/api/main.go`, `cmd/worker/main.go`
-
-**`internal/bootstrap/`:**
-- Purpose: 依赖装配中心。
-- Contains: API/Worker 的 stores、services、handlers、middlewares 初始化。
-- Key files: `internal/bootstrap/bootstrap.go`, `internal/bootstrap/services.go`, `internal/bootstrap/worker.go`, `internal/bootstrap/types.go`
-
-**`internal/routes/`:**
-- Purpose: 路由域划分与 OpenAPI 绑定。
-- Contains: 域入口 `admin.go`, `auth.go`, `personal.go` 以及各模块路由文件。
-- Key files: `internal/routes/routes.go`, `internal/routes/registry.go`, `internal/routes/admin.go`, `internal/routes/personal.go`
-
-**`internal/handler/`:**
-- Purpose: HTTP Handler 层。
-- Contains: `admin/`、`app/`、`auth/`、`callback/` 四个子域。
-- Key files: `internal/handler/admin/account.go`, `internal/handler/auth/handler.go`, `internal/handler/callback/payment.go`
-
-**`internal/service/`:**
-- Purpose: 业务逻辑层。
-- Contains: 按业务模块拆分的子目录，每个模块通常有一个 `service.go`。
-- Key files: `internal/service/account/service.go`, `internal/service/order/service.go`, `internal/service/package/service.go`, `internal/service/polling/*.go`
-
-**`internal/store/`:**
-- Purpose: 数据访问层。
-- Contains: 基础抽象 `store.go`、查询选项 `options.go`、以及 `postgres/` 下的具体实现。
-- Key files: `internal/store/store.go`, `internal/store/options.go`, `internal/store/postgres/account_store.go`, `internal/store/postgres/order_store.go`
-
-**`internal/model/`:**
-- Purpose: 持久化模型与 DTO。
-- Contains: 业务实体模型、基础模型、DTO 子目录。
-- Key files: `internal/model/account.go`, `internal/model/order.go`, `internal/model/shop.go`, `internal/model/dto/account_dto.go`
-
-**`internal/task/`:**
-- Purpose: Asynq 任务处理逻辑。
-- Contains: 轮询、导入、订单超时、邮件、佣金等任务处理器。
-- Key files: `internal/task/polling_handler.go`, `internal/task/order_expire.go`, `internal/task/device_import.go`
-
-**`internal/polling/`:**
-- Purpose: 轮询调度器与专用运行时组件。
-- Contains: `Scheduler`、激活处理器、流量重置处理器。
-- Key files: `internal/polling/scheduler.go`
-
-**`internal/gateway/`:**
-- Purpose: 对外 Gateway HTTP 客户端封装。
-- Contains: 请求签名、设备/卡查询与操作客户端。
-- Key files: `internal/gateway/client.go`（由 `cmd/api/main.go`、`cmd/worker/main.go` 初始化）
-
-**`pkg/`:**
-- Purpose: 通用基础设施。
-- Contains: 配置、数据库、日志、认证、错误、响应、OpenAPI、队列、对象存储、微信、短信、中间件辅助。
-- Key files: `pkg/config/config.go`, `pkg/config/loader.go`, `pkg/database/postgres.go`, `pkg/middleware/auth.go`, `pkg/middleware/data_scope.go`, `pkg/openapi/generator.go`
-
-**`migrations/`:**
-- Purpose: 数据库结构演进。
-- Contains: 成对的 `*.up.sql` / `*.down.sql` 与少量补数 SQL。
-- Key files: `migrations/000000_create_legacy_tables.up.sql`, `migrations/000055_package_system_upgrade.up.sql`, `migrations/000088_rename_card_wallet_id_to_asset_wallet_id.up.sql`
-
-**`docs/`:**
-- Purpose: 面向开发和业务的说明文档。
-- Contains: 功能总结、架构说明、接入指南、运维说明、第三方资料。
-- Key files: `docs/api-documentation-guide.md`, `docs/auth-architecture.md`, `docs/polling-system/README.md`
-
-**`openspec/`:**
-- Purpose: 规范驱动开发资产。
-- Contains: `config.yaml`、当前 specs、历史归档变更。
-- Key files: `openspec/config.yaml`, `openspec/specs/**/spec.md`, `openspec/changes/archive/**`
-
-## Key File Locations
-
-**Entry Points:**
-- `cmd/api/main.go`: API 服务主入口。
-- `cmd/worker/main.go`: Worker 服务主入口。
-- `cmd/gendocs/main.go`: 离线 OpenAPI 生成命令。
-
-**Configuration:**
-- `pkg/config/config.go`: 配置结构与校验规则。
-- `pkg/config/loader.go`: 嵌入配置 + 环境变量覆盖加载。
-- `openspec/config.yaml`: 规范生成器上下文与规则。
-
-**Core Logic:**
-- `internal/service/`: 所有业务服务主实现。
-- `internal/store/postgres/`: 所有 PostgreSQL 访问实现。
-- `internal/bootstrap/`: 依赖注入和装配。
-- `internal/polling/scheduler.go`: 轮询核心调度逻辑。
-
-**API Surface:**
-- `internal/routes/`: 路由分组与注册。
-- `internal/handler/admin/`, `internal/handler/app/`, `internal/handler/auth/`, `internal/handler/callback/`: 传输层处理器。
-
-**Data Definitions:**
-- `internal/model/*.go`: 表模型。
-- `internal/model/dto/*.go`: 请求/响应 DTO。
-
-**Documentation / Planning:**
-- `docs/`: 功能文档。
-- `openspec/specs/`: 现行规格。
-- `openspec/changes/archive/`: 历史变更记录。
-
-## Naming Conventions
-
-**Files:**
-- 模块按业务名命名：`internal/service/account/service.go`, `internal/handler/admin/account.go`
-- 大部分 Store 文件采用 `{resource}_store.go`：`internal/store/postgres/account_store.go`
-- DTO 文件采用 `{module}_dto.go`：`internal/model/dto/account_dto.go`
-- 路由文件按模块命名：`internal/routes/account.go`, `internal/routes/polling_config.go`
-
-**Directories:**
-- 分层目录使用小写单数语义：`internal/service/`, `internal/store/`, `internal/model/`
-- 传输域用子目录表达边界：`internal/handler/admin/`, `internal/handler/app/`, `internal/handler/callback/`
-- 规格目录按能力名组织：`openspec/specs/account-management/`, `openspec/specs/order-payment/`
-
-## Ownership / Responsibility Guide
-
-**如果改接口路径或加新 API：**
-- 先看 `internal/routes/registry.go` 与对应模块路由文件。
-- 再同步检查 `docs/api-documentation-guide.md`、`cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go`。
-
-**如果改业务规则：**
-- 主要落点在 `internal/service/{module}/service.go`。
-- 如涉及跨模块，先看 `internal/bootstrap/services.go` 中该服务依赖谁。
-
-**如果改查询或权限过滤：**
-- 主要落点在 `internal/store/postgres/*.go`。
-- 数据范围辅助逻辑集中在 `pkg/middleware/data_scope.go` 与 `pkg/middleware/permission_helper.go`。
-
-**如果改表结构或模型：**
-- SQL 先改 `migrations/`。
-- Go 模型同步改 `internal/model/*.go`。
-- DTO 变更再改 `internal/model/dto/*.go`。
-
-**如果改异步任务：**
-- 任务实现放 `internal/task/*.go`。
-- 注册入口在 `pkg/queue/handler.go`。
-- Worker 依赖拼装在 `internal/bootstrap/worker*.go`。
-
-**如果改轮询系统：**
-- 调度逻辑看 `internal/polling/scheduler.go`。
-- 执行逻辑看 `internal/task/polling_handler.go`。
-- 配置/监控/清理相关服务看 `internal/service/polling/*.go`。
-
-## Where to Add New Code
-
-**New Admin API Feature:**
-- Primary code: `internal/handler/admin/{module}.go`, `internal/service/{module}/service.go`, `internal/store/postgres/{module}_store.go`, `internal/routes/{module}.go`
-- Models / DTOs: `internal/model/{module}.go`, `internal/model/dto/{module}_dto.go`
-- Wiring: `internal/bootstrap/services.go`, `internal/bootstrap/handlers.go`, `internal/bootstrap/types.go`, `internal/routes/admin.go`
-
-**New Personal Client Feature:**
-- Primary code: `internal/handler/app/{feature}.go`, `internal/service/{feature}/service.go` 或复用现有服务
-- Routes: `internal/routes/personal.go`
-- Auth-sensitive DTOs: `internal/model/dto/` 下新增对应 DTO 文件
-
-**New Worker Task:**
-- Implementation: `internal/task/{task_name}.go`
-- Registration: `pkg/queue/handler.go`
-- Dependencies: `internal/bootstrap/worker_services.go` 或 `internal/bootstrap/worker_stores.go`
-- Constants: `pkg/constants/` 中对应任务类型定义
-
-**New Shared Utility:**
-- Shared helpers: `pkg/{subsystem}/`
-- 仅限跨多个业务模块复用的基础能力，不要把业务逻辑塞进 `pkg/`
-
-**New Business Spec / Plan Artifact:**
-- Current capability spec: `openspec/specs/{capability}/spec.md`
-- Historical change proposal: `openspec/changes/...`
-- Developer-facing long-form doc: `docs/{feature-id}/` 或现有专题目录
-
-## Practical Navigation Guide
-
-**从请求入口追代码：**
-1. 在 `internal/routes/*.go` 找路径。
-2. 跳到对应 `internal/handler/...` 方法。
-3. 看该 Handler 注入了哪个 Service。
-4. 到 `internal/service/...` 看业务编排。
-5. 再进入 `internal/store/postgres/...` 看 SQL 过滤与分页。
-6. 最后回到 `internal/model/` / `internal/model/dto/` 看字段定义。
-
-**从一个模块反查装配方式：**
-1. 先找 `internal/bootstrap/services.go` 是否实例化该 Service。
-2. 再看 `internal/bootstrap/handlers.go` 是否把它交给 Handler。
-3. 再看 `internal/routes/admin.go` 或 `internal/routes/personal.go` 是否挂载了该模块。
-
-**从一个异步任务反查来源：**
-1. 看 `pkg/queue/handler.go` 的 `registerXxxHandler()`。
-2. 跳到 `internal/task/{task}.go`。
-3. 若任务由调度器触发，再看 `internal/polling/scheduler.go` 或 `cmd/worker/main.go` 的 Asynq Scheduler 注册。
-
-## Special Directories
-
-**`logs/`:**
-- Purpose: 运行日志输出目录。
-- Generated: Yes
-- Committed: No（运行期产物）
-
-**`migrations/`:**
-- Purpose: 数据库迁移脚本。
-- Generated: No
-- Committed: Yes
-
-**`docs/第三方文档/`:**
-- Purpose: 外部供应商或接口资料归档。
-- Generated: No
-- Committed: Yes
-
-**`openspec/changes/archive/`:**
-- Purpose: 已归档历史变更。
-- Generated: No
-- Committed: Yes
-
-**`.planning/codebase/`:**
-- Purpose: 供规划/执行命令消费的代码地图文档。
-- Generated: Yes
-- Committed: Yes
-
-## Structural Notes for Contributors
-
-- 这个仓库的“物理结构”严格围绕 Go 后端单体展开；新增代码优先放进现有层级，不要新造平行架构。
-- `internal/bootstrap/handlers.go` 当前会为客户端能力额外 new 一批 Store，这意味着某些接口不是纯 Service 注入；新增客户端功能前先确认是否要复用现有 `services` 聚合，还是遵循当前适配方式。
-- OpenAPI 不是完全自动发现；新增 Handler、Route 之后，必须同步维护 `internal/bootstrap/types.go`、`internal/bootstrap/handlers.go`、`internal/routes/*.go`、`cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go`。
-- 数据权限过滤不在统一 GORM 查询回调中自动生效；新增 Store 查询时，要主动选对 `ApplyShopFilter`、`ApplyEnterpriseFilter`、`ApplySellerShopFilter`、`ApplyOwnerShopFilter` 等函数。
-
----
-
-*Structure analysis: 2026-03-27*

.planning/codebase/TESTING.md

@@ -1,182 +0,0 @@
-# Testing Patterns
-
-**Analysis Date:** 2026-03-27
-
-## Test Framework
-
-**Runner:**
-- 当前仓库未检测到有效的 Go 自动化测试文件：`glob("**/*_test.go")` 返回空，`glob("tests/**")` 返回空。
-- 因此，仓库当前状态下不存在可执行的项目内单元测试、集成测试或 E2E 测试代码。
-
-**Assertion Library:**
-- 未检测到；因为当前仓库没有 `*_test.go` 文件。
-
-**Configured / Documented commands:**
-```bash
-go test ./...                 # `README.md` 文档命令；当前仓库没有测试文件
-go test -cover ./...          # `README.md` 文档命令；覆盖率描述与仓库现状不符
-go test -v ./...              # `Makefile` 的 `test` 目标与 `README.md` 一致
-go test ./pkg/...             # `README.md` 文档命令；当前没有对应测试文件
-go test ./tests/integration/... # `README.md` 文档命令；当前仓库不存在 `tests/` 目录内容
-go test -v ./internal/middleware -run TestKeyAuth # `README.md` 文档命令；当前未检测到对应测试
-```
-
-## Policy Reality
-
-**Current project rule (authoritative):**
-- `AGENTS.md` 明确规定：本项目不使用任何形式的自动化测试代码。
-- `AGENTS.md` 明确禁止单元测试、集成测试、验收测试、流程测试、E2E 测试，以及创建 `*_test.go` 文件；唯一例外是用户明确要求“请写测试”。
-
-**Repository reality:**
-- 当前仓库与该规则一致：未发现任何 `*_test.go` 文件，也未发现 `tests/` 目录内容。
-
-**Stale documentation conflicts:**
-- `README.md` 仍包含完整“测试”章节，列出 `go test ./...`、覆盖率、集成测试、`tests/integration/`、以及 `docs/testing/test-connection-guide.md` 的说明。
-- `README.md` 的项目结构段仍展示 `tests/integration/auth_test.go`、`tests/integration/ratelimit_test.go`。
-- `README.md` 的 “Speckit / 宪章” 段仍写有 “70%+ 测试覆盖率，核心业务 90%+”。
-- 这些内容与 `AGENTS.md` 的现行禁令、以及仓库中真实文件状态冲突。后续执行应以 `AGENTS.md` + 实际文件现状为准。
-
-## Verification Approach Actually Used
-
-**Primary approach:**
-- 人工验证 + 脚本检查 + 文档生成检查 + 生产日志/监控。
-
-**Evidence from policy:**
-- `AGENTS.md` 将替代方案明确写为：
-  - 使用 PostgreSQL MCP 工具手动验证数据
-  - 使用 Postman/curl 手动测试 API
-  - 依赖生产环境日志和监控发现问题
-
-**Repository scripts that support this model:**
-- `scripts/check-service-errors.sh`：静态扫描 Service 层错误处理规则。
-- `scripts/check-comment-paths.sh`：静态扫描 Handler 注释中的 API 路径是否过时。
-- `scripts/check-all.sh`：聚合上述脚本。
-- `scripts/verify_migration/main.go`：直接连接数据库查询表和字段，验证迁移结果；这是一种手工校验辅助程序，不是自动测试框架。
-- `cmd/gendocs/main.go` / `make docs`：通过重新生成 OpenAPI 文档来验证路由注册和文档接线是否完整。
-
-## Test File Organization
-
-**Location:**
-- 当前无自动化测试文件。
-
-**Naming:**
-- 按 Go 常规应为 `*_test.go`，但本项目现行规则禁止新增，除非用户明确要求。
-
-**Structure:**
-```text
-自动化测试目录：未检测到
-README 中声明的 `tests/integration/`：当前不存在实际文件
-```
-
-## Manual Validation Patterns
-
-**API / behavior validation:**
-- 使用 Postman、curl 或 Swagger/OpenAPI 文档进行接口人工验证，依据见 `AGENTS.md` 与 `docs/api-documentation-guide.md`。
-- 生成 OpenAPI 文档后检查路径是否出现：`go run cmd/gendocs/main.go`，再检查 `docs/admin-openapi.yaml`，依据见 `docs/api-documentation-guide.md`。
-
-**Database validation:**
-- 涉及数据正确性时，使用 PostgreSQL MCP 工具做手动查询验证，依据见 `AGENTS.md` 的 `db-validation` 说明。
-- 涉及迁移结果时，可运行 `go run scripts/verify_migration/main.go` 检查表与字段；该脚本读取真实数据库 schema，不产出测试报告。
-
-**Convention validation:**
-- 改动 Service 层错误处理后运行 `bash scripts/check-service-errors.sh`。
-- 改动 Handler 注释或路由后运行 `bash scripts/check-comment-paths.sh`。
-- 需要一次性检查时运行 `bash scripts/check-all.sh`。
-
-**Documentation / OpenAPI validation:**
-- 新增 Handler 后必须同步更新 `cmd/api/docs.go` 与 `cmd/gendocs/main.go`，然后重新生成文档并检查目标路径，依据见 `docs/api-documentation-guide.md`。
-
-## Mocking
-
-**Framework:**
-- Not applicable；当前没有自动化测试代码。
-
-**Patterns:**
-```text
-未检测到 mock 框架、测试替身、fixture helper 或 testutil 包的实际使用。
-```
-
-**What to Mock:**
-- 当前仓库没有现行自动化测试实践可供复用。
-
-**What NOT to Mock:**
-- 当前仓库没有现行自动化测试实践可供复用。
-
-## Fixtures and Factories
-
-**Test Data:**
-```text
-未检测到 fixture/factory 测试数据目录或 `_test.go` 中的构造模式。
-```
-
-**Reality check:**
-- `README.md` 仍引用 `docs/testing/test-connection-guide.md` 和 `testutils.NewTestTransaction(...)` 示例，但当前仓库没有对应测试文件作为实际落点。
-
-## Coverage
-
-**Requirements:**
-- 当前现行项目规则不要求覆盖率，且原则上禁止自动化测试，依据见 `AGENTS.md`。
-
-**Conflict to document clearly:**
-- `README.md` 和其中引用的 Speckit 宪章仍声称需要覆盖率目标；这与 `AGENTS.md` 的测试禁令冲突，且与当前“零测试文件”现状不符。
-
-**View Coverage:**
-```bash
-go test -cover ./...    # 仅为 README 中遗留命令，不代表现行流程
-```
-
-## Test Types
-
-**Unit Tests:**
-- 当前未使用。
-
-**Integration Tests:**
-- 当前未使用。
-- `README.md` 里提到的 `tests/integration/` 是过期描述，不是当前仓库事实。
-
-**E2E Tests:**
-- 当前未使用。
-
-## CI Reality
-
-**Actual workflow present:**
-- `.gitea/workflows/deploy.yaml` 只有检出、Docker 构建、推送镜像、部署到测试环境的步骤。
-
-**What is not in CI:**
-- 未发现 `go test`。
-- 未发现 `bash scripts/check-all.sh`。
-- 未发现 `bash scripts/check-service-errors.sh`。
-- 未发现 `bash scripts/check-comment-paths.sh`。
-- 未发现独立的质量门或覆盖率上传步骤。
-
-**Conflict to document clearly:**
-- `README.md` 写着“这些检查会在 CI/CD 流程中自动执行”，但 `.gitea/workflows/deploy.yaml` 中没有相应步骤。当前 CI 现实是“构建/部署优先，无显式质量校验门”。
-
-## Common Verification Commands
-
-```bash
-bash scripts/check-service-errors.sh   # 校验 Service 错误处理规则
-bash scripts/check-comment-paths.sh    # 校验 Handler 注释路径是否过时
-bash scripts/check-all.sh              # 运行当前已存在的全部静态脚本检查
-go run cmd/gendocs/main.go             # 重新生成 OpenAPI 文档，验证路由接线
-make docs                              # 等价于生成 OpenAPI 文档
-go run scripts/verify_migration/main.go # 人工验证数据库迁移结果
-```
-
-## Current Gaps and Caveats
-
-- `Makefile` 仍保留 `test:` 目标并执行 `go test -v ./...`，这属于历史遗留入口，不应被误解为现行团队要求。
-- `README.md` 的测试章节、目录结构和覆盖率目标明显滞后于当前 `AGENTS.md` 规则。
-- `scripts/check-service-errors.sh` 虽然存在，但当前仓库 `internal/service/polling/alert_service.go` 仍有 `fmt.Errorf(...)` 违规点，说明现有脚本检查并未通过 CI 强制执行。
-- `scripts/verify_migration/main.go` 内含直接数据库连接字符串，反映的是临时人工验证脚本，而不是可复用、无环境依赖的测试体系。
-
-## Prescriptive Summary
-
-- 讨论“测试”时，先区分三件事：`README.md` 的历史文档、`AGENTS.md` 的现行规则、仓库当前真实文件状态。
-- 在当前仓库中，默认不要新增 `*_test.go`；只有用户明确要求时才编写测试代码。
-- 日常验证优先使用：静态检查脚本、OpenAPI 文档再生成、数据库手查、Postman/curl、人肉回归。
-- 判断 CI 是否有质量门时，以 `.gitea/workflows/deploy.yaml` 为准，而不是 `README.md` 的说明。
-
----
-
-*Testing analysis: 2026-03-27*

.planning/config.json

@@ -1,36 +0,0 @@
-{
-  "model_profile": "balanced",
-  "commit_docs": true,
-  "parallelization": true,
-  "search_gitignored": false,
-  "brave_search": false,
-  "firecrawl": false,
-  "exa_search": false,
-  "git": {
-    "branching_strategy": "none",
-    "phase_branch_template": "gsd/phase-{phase}-{slug}",
-    "milestone_branch_template": "gsd/{milestone}-{slug}",
-    "quick_branch_template": null
-  },
-  "workflow": {
-    "research": true,
-    "plan_check": true,
-    "verifier": true,
-    "nyquist_validation": true,
-    "auto_advance": false,
-    "node_repair": true,
-    "node_repair_budget": 2,
-    "ui_phase": false,
-    "ui_safety_gate": false,
-    "text_mode": false,
-    "research_before_questions": false,
-    "discuss_mode": "discuss",
-    "skip_discuss": false,
-    "_auto_chain_active": false
-  },
-  "hooks": {
-    "context_warnings": true
-  },
-  "agent_skills": {},
-  "resolve_model_ids": "omit"
-}

.planning/phases/01-p0/01-01-PLAN.md

@@ -1,224 +0,0 @@
----
-phase: 01-p0
-plan: 01
-type: execute
-wave: 1
-depends_on: []
-files_modified:
-  - internal/task/polling_handler.go
-  - internal/model/iot_card.go
-  - internal/service/client_order/service.go
-autonomous: true
-requirements:
-  - CRITICAL-01
-  - CRITICAL-02
-must_haves:
-  truths:
-    - "parseRealnameStatus 返回 constants.RealNameStatusVerified（=1），不再返回硬编码 2"
-    - "isFirstRealname 判断使用常量比较，不再使用 == 2"
-    - "Model 注释与常量一致：0=未实名, 1=已实名"
-    - "client_order 实名校验使用 constants.RealNameStatusVerified，不再硬编码 1"
-  artifacts:
-    - path: internal/task/polling_handler.go
-      provides: "parseRealnameStatus 返回常量值，isFirstRealname 使用常量"
-      contains: "constants.RealNameStatusVerified"
-    - path: internal/model/iot_card.go
-      provides: "Model 字段注释统一"
-      contains: "0-未实名 1-已实名"
-    - path: internal/service/client_order/service.go
-      provides: "实名校验改为常量比较"
-      contains: "constants.RealNameStatusVerified"
-  key_links:
-    - from: internal/task/polling_handler.go
-      to: pkg/constants/iot.go
-      via: "constants.RealNameStatusVerified"
-      pattern: "constants\\.RealNameStatusVerified"
-    - from: internal/service/client_order/service.go
-      to: pkg/constants/iot.go
-      via: "constants.RealNameStatusVerified"
-      pattern: "constants\\.RealNameStatusVerified"
----
-
-<objective>
-统一实名状态常量（CRITICAL-01），并修复 C 端实名校验（CRITICAL-02）。
-
-Purpose: 这是整个修复链路的前置条件。轮询写入 2、常量定义 1、校验用 1 三处不一致造成实名链路全面断裂。修复后实名状态全链路统一为 0=未实名、1=已实名。CRITICAL-02 依赖本 Plan 完成才能自动正确。
-
-Output: 
-- polling_handler.go 写入值改为常量 1
-- iot_card.go 注释与常量统一
-- client_order/service.go 校验使用常量
-</objective>
-
-<execution_context>
-@$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
-@$HOME/.config/opencode/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/phases/01-p0/01-CONTEXT.md
-
-# 修复规格书（核心参考）
-@.sisyphus/plans/修正业务-完整方案.md
-
-<interfaces>
-<!-- 从 pkg/constants/iot.go 提取的常量，executor 直接使用 -->
-
-```go
-// pkg/constants/iot.go（已确认存在，第 47-48 行附近）
-const (
-    RealNameStatusNotVerified = 0 // 未实名
-    RealNameStatusVerified    = 1 // 已实名
-)
-```
-
-<!-- polling_handler.go 当前错误代码（需改掉） -->
-<!-- 第 696-700 行：parseRealnameStatus 返回 2（错误） -->
-<!-- 第 170 行：isFirstRealname 使用 == 2（错误） -->
-
-<!-- client_order/service.go 当前代码（第 115 行附近） -->
-<!-- assetInfo.RealNameStatus != 1（硬编码，需改为常量） -->
-</interfaces>
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: 修复 polling_handler.go 实名状态写入值（CRITICAL-01 核心）</name>
-  <files>internal/task/polling_handler.go, internal/model/iot_card.go</files>
-  <action>
-**修改 `internal/task/polling_handler.go`：**
-
-① `parseRealnameStatus` 函数（第 696-700 行附近）：
-```go
-// 修改前
-func (h *PollingHandler) parseRealnameStatus(realStatus bool) int {
-    if realStatus {
-        return 2 // 已实名
-    }
-    return 0 // 未实名
-}
-
-// 修改后（使用常量，per D-01）
-func (h *PollingHandler) parseRealnameStatus(realStatus bool) int {
-    if realStatus {
-        return constants.RealNameStatusVerified // = 1，已实名
-    }
-    return constants.RealNameStatusNotVerified // = 0，未实名
-}
-```
-
-② `isFirstRealname` 判断（第 170 行附近）：
-```go
-// 修改前
-isFirstRealname := (card.RealNameStatus == 0 || card.RealNameStatus == 1) && newRealnameStatus == 2
-
-// 修改后（使用常量比较，per D-01）
-isFirstRealname := card.RealNameStatus != constants.RealNameStatusVerified &&
-    newRealnameStatus == constants.RealNameStatusVerified
-```
-
-③ 全局搜索 `polling_handler.go` 及 `internal/model/dto/` 下 DTO 注释，将所有 `2=已实名`、`1实名中` 改为 `0=未实名, 1=已实名`（执行：`grep -rn "2=已实名\|1实名中\|RealNameStatus.*2" internal/model/dto/ --include="*.go"`）。
-
-**修改 `internal/model/iot_card.go`：**
-
-找到第 30 行附近 `RealNameStatus` 字段的 gorm comment：
-```go
-// 修改前
-RealNameStatus int `gorm:"...; comment:实名状态 0-未实名 1-已实名(行业卡可以保持0)"`
-
-// 修改后（统一，per D-01）
-RealNameStatus int `gorm:"...; comment:实名状态 0-未实名 1-已实名"`
-```
-
-修改完成后执行：`go build ./...`，确认编译通过，提交一个独立 commit（per D-05）。
-  </action>
-  <verify>
-    <automated>go build ./... && rg "return 2" internal/task/polling_handler.go && echo "FAIL: 仍存在 return 2" || echo "PASS: return 2 已消除"</automated>
-  </verify>
-  <done>
-    - polling_handler.go 中 parseRealnameStatus 不再 return 2，改为 return constants.RealNameStatusVerified
-    - isFirstRealname 不再用 == 2，改为 == constants.RealNameStatusVerified
-    - iot_card.go 注释统一为 0-未实名 1-已实名
-    - go build ./... 编译通过
-  </done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 修复 C 端实名校验（CRITICAL-02）</name>
-  <files>internal/service/client_order/service.go</files>
-  <action>
-**修改 `internal/service/client_order/service.go`（第 115 行附近）：**
-
-找到实名校验判断：
-```go
-// 修改前（硬编码 1，本质上是 A-1 修完后 DB 里是 1 才会正确，但语义要用常量）
-if packagesNeedRealname(validationResult.Packages) && assetInfo.RealNameStatus != 1 {
-    return errors.New(errors.CodeForbidden, "请先完成实名认证")
-}
-
-// 修改后（使用常量，per CRITICAL-02 规格）
-if packagesNeedRealname(validationResult.Packages) && assetInfo.RealNameStatus != constants.RealNameStatusVerified {
-    return errors.New(errors.CodeForbidden, "请先完成实名认证")
-}
-```
-
-同时检查同文件和 `polling_handler.go:982` 是否有其他硬编码 `!= 1` 的实名判断（`rg "RealNameStatus.*!= 1\|!= 1.*RealNameStatus" internal/`），若有，同样改为常量。
-
-确认 constants 包已正确 import（若未 import，在 import 块补充 `pkgpath/constants`）。
-
-修改完成后执行：`go build ./...`，编译通过后提交独立 commit（per D-05）。
-  </action>
-  <verify>
-    <automated>go build ./... && rg "RealNameStatus != 1" internal/service/client_order/service.go && echo "FAIL: 仍有硬编码" || echo "PASS: 硬编码已消除"</automated>
-  </verify>
-  <done>
-    - client_order/service.go 实名校验改为 constants.RealNameStatusVerified
-    - go build ./... 编译通过
-    - rg 确认不再有 != 1 的硬编码实名判断
-  </done>
-</task>
-
-</tasks>
-
-<verification>
-整体验收（两个任务完成后）：
-
-```bash
-# 1. 编译验证
-go build ./...
-
-# 2. 确认 parseRealnameStatus 不再写 2
-rg "return 2" internal/task/polling_handler.go
-
-# 3. 确认实名判断全部使用常量
-rg "RealNameStatusVerified" internal/task/polling_handler.go internal/service/client_order/service.go
-
-# 4. 搜索遗漏的硬编码
-rg "newRealnameStatus == 2\|RealNameStatus == 2\|RealNameStatus != 1" internal/ --include="*.go"
-```
-
-人工验收（参见修正业务-完整方案.md 方案 A 验收清单 A-1、A-2）：
-- DBHub 执行：`SELECT DISTINCT real_name_status FROM tb_iot_card ORDER BY 1;`
-  - 预期：只存在 0 和 1，不存在 2
-</verification>
-
-<success_criteria>
-1. `go build ./...` 编译通过，无错误
-2. `parseRealnameStatus(true)` 返回 1（constants.RealNameStatusVerified），不再返回 2
-3. `isFirstRealname` 不再使用 == 2 判断
-4. `client_order/service.go` 实名校验使用常量，不再硬编码 1
-5. Model 注释与常量定义一致
-6. 两个独立 commit 已提交
-</success_criteria>
-
-<output>
-完成后创建 `.planning/phases/01-p0/01-01-SUMMARY.md`，记录：
-- 修改了哪些文件（文件路径 + 改动说明）
-- 关键代码片段（修改前后对比）
-- 编译验证结果
-- CRITICAL-01 和 CRITICAL-02 完成状态
-</output>