@devflow-core/dsh-devflow 0.1.0

package/assets/skills/devflow-prove/references/proof-recovery-methods.md

@@ -0,0 +1,26 @@
+# DevFlow Proof And Recovery Methods
+
+Owners: `devflow-prove` and `devflow-pua`. Load this reference after completed Build directly enters Prove or when Core selects Proof or Recovery for a non-unique artifact.
+
+## Method 13: Proof Before Done
+
+Run fresh, narrow evidence before a completion claim. Rules and skills need file, trigger, load, and downstream evidence. Code needs a focused test, build, lint, typecheck, or reproducible scenario. A bug fix needs symptom or regression proof.
+
+```text
+Command: <actual command>
+Result: <key output>
+Adversarial review: <acceptance, regressions, activation, proof coverage>
+Judgment: PASS / FAIL / BLOCKED
+```
+
+`PASS` is Prove's terminal success after Learn review. Proof `FAIL`, `BLOCKED`, a real adversarial gap, unresolved Code Review Blocker/Warning, or incomplete PUA recovery evidence returns its facts to `devflow-core`; Core selects the repair, recovery, or re-clarification path. Prove never infers that next owner.
+
+### Quality-Finding Recovery
+
+A Code Review Blocker or Warning requires a Build correction selected by Core. After that correction, Prove reviews the new actual diff against the same File Structure boundary, Prewalk evidence, direct contracts, and nearby convention. It explicitly records every prior finding as closed with fresh evidence or still open; stale test output, stale review output, or an implementer claim cannot close it. Ordinary quality repair remains separate from PUA unless the failure also has a user challenge, repeated miss, or changed-wrong signal.
+
+## Method 14: Recovery By Changing Approach
+
+On an unexpected verification failure or repeated user challenge, re-read facts, restate the desired result, list three hypotheses, choose a materially different approach, and rerun proof. PUA additionally loads its methodology router, library, and display protocol before a recovery patch.
+
+Do not retry the same move with superficial wording changes. Reusable lessons go to `devflow-learn` after proof.

package/assets/skills/devflow-pua/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: devflow-pua
+description: "Use when the user repeatedly points out that the same function or result has a problem in one task lifecycle, repeatedly identifies missing coverage for the same function, or Recovery needs pressure to stop the current approach and realign before more edits."
+---
+
+# DevFlow PUA
+
+Apply pressure as accountability: stop the wrong path, quarantine the wrong working context, diagnose why the user thinks the result is wrong, load the local methodology router, display the active flavor/method, return recovery facts to `devflow-core`, switch method when the current one failed, and let Core decide whether request re-confirmation or any later lifecycle work is needed. PUA never selects the replacement execution skill. Do not use persona theater or insults.
+
+## Repeated Same-Function Trigger
+
+Trigger this skill only when the user repeatedly points out that the **same function, result, or requested capability** has a problem in one task lifecycle. Evidence may be repeated “不对/有问题/还是不对/还有缺漏” feedback about that same target, including after an attempted correction.
+
+Do not infer pressure recovery from an isolated phrase alone. The decisive fact is repeated dissatisfaction with the same target, not whether a message is labeled as a first correction.
+
+The direct `/devflow-pua` command remains an explicit opt-in and may activate this skill immediately.
+
+## Methodology Assets
+
+When this skill activates, read these local references before choosing or switching method:
+
+- `skills/devflow-pua/references/methodology-router.md`
+- `skills/devflow-pua/references/methodology-library.md`
+- `skills/devflow-pua/references/flavor-display.md`
+
+These files are the runtime method source. Do not link out to the original PUA project at runtime.
+
+## Process
+
+Load `skills/devflow-prove/references/proof-recovery-methods.md` before applying recovery proof rules. Keep the PUA methodology router, library, and flavor-display assets as the owner of method selection and output display.
+
+1. **Stop the current path**: do not keep editing with the same assumption when the user repeatedly reports that the same function, result, or requested capability remains wrong, incomplete, or missing.
+2. **Name the pressure signal**: repeated same-target dissatisfaction in one task lifecycle, including after an attempted correction; record the function/result/capability that the user keeps identifying as problematic.
+3. **Quarantine wrong context**: keep only verified facts and user-stated constraints; discard the previous solution hypothesis, implementation path, and "almost fixed" assumptions.
+4. **Load methodology**: read `references/methodology-router.md`, `references/methodology-library.md`, and `references/flavor-display.md`.
+5. **Route flavor/method**: choose the starting or switched flavor from the pressure signal and failure pattern.
+6. **Display method**: output one compact visible line: `METHOD: {flavor} / {method}`. If the method changed, add one `SWITCH:` line.
+7. **Diagnose the user-view miss**: classify why the user would still feel unsatisfied before proposing another patch.
+8. **Request re-confirmation facts**: when the repeated same-target trigger applies, do not continue editing; include the need for fresh request confirmation in the recovery facts.
+9. **Ask what is wrong and what result is wanted**: ask the smallest concrete set when the answer is not already explicit.
+10. **Restate the goal**: say what you now believe the user wants and what result they should see.
+11. **List 3 hypotheses**: include at least one hypothesis that the previous approach was solving the wrong problem.
+12. **Switch method if needed**: if the last guiding method still missed, mark it failed, choose a different or opposite method lens, and restart checks from facts before editing again.
+13. **Change approach**: name the old approach being abandoned and the materially different path now chosen.
+14. **Prepare the handoff**: include only recovery facts, including any request re-confirmation need, in the required output for Core selection.
+15. **Close learning**: if the miss is reusable, load `devflow-learn` before claiming completion.
+
+## Guiding Principles
+
+- **Customer Backwards**: start from the result the user expected to see, not from why the old patch seemed reasonable.
+- **Miss Taxonomy**: identify the satisfaction gap before choosing the next fix.
+- **Owner/RCA Discipline**: own the outcome, inspect facts, find the root cause, and do not push discoverable work back to the user.
+- **Blue-Team + Evidence Loop**: attack the new plan from the user's point of view, then prove the corrected result with evidence.
+
+The user wants a corrected outcome, not an explanation that the previous attempt was "almost right". Every recovery must produce a new success contract: expected result, not-doing boundary, changed approach, and proof.
+
+## Why User Thinks It Is Wrong
+
+Classify the miss before changing files:
+
+| Miss | Meaning | Recovery bias |
+|---|---|---|
+| Goal mismatch | The agent solved a different problem than the user cared about. | Customer Backwards; re-ask or infer the desired result. |
+| Artifact mismatch | The agent changed the wrong file, page, skill, command, docs location, or install scope. | Trace the artifact owner and target surface before editing. |
+| Behavior gap | The visible behavior did not change, or only wording changed. | Reproduce behavior and pick a behavior-changing path. |
+| Missing coverage | The agent fixed one part but missed entrypoints, commands, validation, docs, user-level sync, or sibling flows. | Coverage Map; enumerate required surfaces before Build. |
+| Proof gap | Verification was absent or did not cover the user's scenario. | Evidence Loop; define proof from the user's acceptance scenario. |
+| UX/result gap | The result works technically but is unclear, hard to distinguish, incomplete, or not satisfying. | Customer Backwards + Blue-Team user review. |
+
+Treat repeated "少了/少个/缺少/缺漏/遗漏/漏了/still missing/incomplete" as a pressure signal. It usually means Missing coverage or UX/result gap, not a normal feature add.
+
+## Method Switch Rule
+
+If one guiding method was already used and the user still says the result is wrong, incomplete, or missing pieces, do not repeat that method unchanged. The next recovery must automatically switch to a different or opposite method and restart checking from facts.
+
+Switch by failure pattern:
+
+- Goal, artifact, or UX miss -> **Customer Backwards**.
+- Missing pieces, missing sync, missing command/entry/validation coverage -> **Coverage Map**.
+- Bug, proof failure, or behavior still unchanged -> **Owner/RCA Discipline**.
+- Repeated tweaks, same hypothesis, or "almost fixed" thinking -> **Blue-Team Opposite Hypothesis**.
+
+Opposite method switching:
+
+| Failed method | Switch to | Why |
+|---|---|---|
+| Customer Backwards still misses details | Coverage Map | The desired result may be right, but the surfaces were incomplete. |
+| Coverage Map still misses the result | Customer Backwards | The list may be complete but aimed at the wrong user-visible outcome. |
+| Owner/RCA still leaves behavior unchanged | Blue-Team Opposite Hypothesis | The root cause hypothesis may be wrong. Attack it directly. |
+| Blue-Team still produces no fix | Owner/RCA Discipline | Stop debating the plan and trace facts, callers, and proof. |
+
+Before visible output, decide whether the prior method is still valid or must switch to Customer Backwards, Coverage Map, Owner-RCA, or Blue-Team Opposite Hypothesis. Do not expose that decision as extra output fields unless the user asks for full diagnostics. When the method changes, use only this visible line:
+
+```text
+SWITCH: <old flavor>/<old method> -> <new flavor>/<new method>: <reason>
+```
+
+If the switched method also fails once, stop editing and ask the user to confirm the new success contract before another patch. If it fails twice, record the reusable miss through `devflow-learn`.
+
+On DeepSeek Harness (DSH), fresh-agent iteration via the `ralph` tool (each round a fresh agent, workspace as durable memory) is an available form of the materially-different-approach switch, but only when the user explicitly requests fresh-agent iteration; otherwise keep the normal re-read-facts-and-switch-method flow above.
+
+## Hard Restart Rule
+
+Trigger this rule when, in one task lifecycle, the user repeatedly points out that the same function, result, or requested capability remains wrong, incomplete, or missing, including after an attempted correction.
+
+The trigger is repeated dissatisfaction with the same target; do not infer it from an isolated keyword or from message count alone.
+
+## Pointed Questions
+
+Use the smallest blocking set. Prefer these shapes:
+
+```text
+1. Where exactly is the current result wrong?
+2. What exact result should the user see after this is fixed?
+3. What must stay unchanged?
+4. What proof would make you say this is corrected?
+```
+
+If code, backend behavior, existing UI, docs, or prior messages answer the question, state the inference with evidence instead of asking.
+
+## Required Output
+
+```text
+Pressure check: <signal and why normal Recovery is not enough>
+Restart Brainstorm: <re-confirmation required / not required; Core selects whether to invoke it>
+Discarded context: <old assumption/path not reused>
+Keep only verified facts: <facts retained from prior work>
+METHOD: {flavor} / {method}
+SWITCH: <none or old flavor/method -> new flavor/method: reason>
+User-view miss: <Goal mismatch / Artifact mismatch / Behavior gap / Missing coverage / Proof gap / UX-result gap>
+Satisfaction gap: <why the user would still say this is not enough>
+User goal restated: <current understanding>
+Desired result: <visible/file/behavior outcome>
+Blocking questions: <none, inferred from facts, or 2-4 pointed questions>
+Hypotheses: 1 / 2 / 3
+Blue-team attack: <how the new plan could still fail from the user's point of view>
+New success contract: <expected result + affected surfaces + verification + not-doing>
+Changed approach: <old path abandoned; new path>
+Verification: <command or scenario to prove the new path>
+Learning closure: <none or devflow-learn handoff>
+```
+
+## Escalation Rules
+
+- After two corrected, challenged, or failed attempts in one task lifecycle, stop editing and return re-confirmation facts to `devflow-core`; ask the pointed questions unless the answers are directly inferable from facts.
+- When the user repeatedly reports that the same function, result, or requested capability remains wrong, incomplete, or missing in one task lifecycle, return the Brainstorm re-confirmation need to Core.
+- If the user repeatedly adds missing details for the same target, run Missing coverage diagnosis and Coverage Map before Build.
+- If the selected guiding method still fails once, switch to a different or opposite method and restart the checks from facts; if it fails twice, stop and ask the user to confirm the new success contract before editing.
+- If the same proof fails twice, do not rerun it unchanged; change the hypothesis or implementation path first.
+- If the previous approach only changed wording, parameters, or nearby files, that is not a materially different approach.
+- Do not use previous erroneous context as the basis for the next patch. Use it only to identify what failed.
+- If the user explicitly tells you the goal and safe next action, use it and continue; do not stall with ritual questions.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|---|---|
+| "I'll just tweak it once more." | Repeated tweaks are the failure pattern. Stop and re-align. |
+| "The user is unhappy, so I should rush." | Pressure means more facts and sharper questions, not faster guessing. |
+| "I changed something, so the approach changed." | A new approach changes the hypothesis, target, or proof path. |
+| "The old context is probably close." | The old context produced the wrong result. Quarantine it and return re-confirmation facts to Core. |
+| "The user is just adding scope." | Repeated "missing" feedback is a satisfaction gap until coverage and goal are rechecked. |
+| "The same method should work if I try harder." | If the method already failed, switch method or prove why it still fits. |
+| "Learning can wait." | Reusable misses must become a next-time intercept before completion. |
+
+## Handoff Gate
+
+After pressure recovery, return only the clarified request or recovery facts to Core:
+
+```text
+Next skill: devflow-core
+Reason: Brainstorm re-confirmed the request or recovery facts require Core lifecycle routing
+```
+
+This is PUA's sole handoff: return recovery facts to `devflow-core`, which alone selects any later lifecycle work.
+
+## Verification
+
+Before leaving this skill, confirm:
+
+- [ ] The previous path was stopped or explicitly kept with evidence.
+- [ ] Repeated dissatisfaction with the same function, result, or requested capability returned a Brainstorm re-confirmation need to `devflow-core`.
+- [ ] Previous erroneous context was quarantined and not reused as the next solution basis.
+- [ ] Local methodology references were read before selecting method.
+- [ ] The compact methodology line `METHOD: {flavor} / {method}` was output.
+- [ ] A concise `SWITCH:` line was output when the method changed.
+- [ ] User-view miss and satisfaction gap were classified.
+- [ ] A guiding method was selected, or switched if the prior method failed.
+- [ ] Missing-piece feedback triggered coverage mapping.
+- [ ] The new plan was blue-team attacked from the user's point of view.
+- [ ] New success contract is explicit.
+- [ ] Goal and desired result were restated.
+- [ ] Blocking questions were asked only when facts could not answer them.
+- [ ] Three hypotheses were listed.
+- [ ] The changed approach is materially different.
+- [ ] A proof command or scenario is named.
+- [ ] Learning handoff is made when the miss is reusable.

package/assets/skills/devflow-pua/references/flavor-display.md

@@ -0,0 +1,49 @@
+# DevFlow PUA Flavor Display
+
+Use this display protocol when `devflow-pua` activates or switches method. Keep the user-visible methodology contract short; put routing detail into the reasoning/work notes only when needed.
+
+## Required Lines
+
+Every pressure recovery must show one compact visible line:
+
+```text
+METHOD: {flavor} / {method}
+```
+
+If the method changed after a failed recovery, add one concise switch line:
+
+```text
+SWITCH: <old flavor>/<old method> -> <new flavor>/<new method>: <reason>
+```
+
+## Compact Display
+
+```text
+METHOD: Huawei / RCA + Blue-Team
+```
+
+## Switch Display
+
+```text
+METHOD: Alibaba / Closure + Coverage Map
+SWITCH: Amazon/Customer Backwards -> Alibaba/Coverage Map: goal is understood, but entrypoints, commands, sync, and proof coverage are incomplete.
+```
+
+## Flavor Voice Map
+
+| Flavor | Visible name |
+|---|---|
+| Alibaba | Alibaba |
+| Huawei | Huawei |
+| Amazon | Amazon |
+| Musk | Musk |
+| Jobs | Jobs |
+| Baidu | Baidu |
+| ByteDance | ByteDance |
+| Microsoft | Microsoft |
+| Pinduoduo | Pinduoduo |
+| JD | JD |
+
+## Anti-Theater Rule
+
+The compact line is a user-facing contract, not decoration. It is invalid unless the selected method is also backed by method steps, a changed approach, and proof in the recovery work.

package/assets/skills/devflow-pua/references/methodology-library.md

@@ -0,0 +1,193 @@
+# DevFlow PUA Methodology Library
+
+This is the local method library used by `devflow-pua`. It extracts the practical execution parts of the original PUA methodology files into DevFlow-Core runtime form.
+
+Read this after `methodology-router.md` chooses a flavor.
+
+## Alibaba: Closure Method
+
+Use when feedback says the work is incomplete, missing surfaces, or not closed.
+
+Steps:
+
+1. Define the exact goal and visible result.
+2. Build a Coverage Map: files, commands, skills, docs, install sync, UI/backend behavior, validation.
+3. Track each surface to proof.
+4. Deliver result evidence.
+5. Retrospect and capture learning if repeatable.
+
+Evidence:
+
+```text
+Coverage Map: <surface -> status -> proof>
+Closure proof: <command/scenario>
+```
+
+## Huawei: RCA + Blue-Team
+
+Use when behavior is still wrong, bug/proof failed, or a root cause is unclear.
+
+Steps:
+
+1. State the symptom in the user's words.
+2. Run 5-Why or equivalent root-cause tracing.
+3. Search callers/references and sibling entrypoints.
+4. Blue-team attack the proposed fix before editing.
+5. Prove the original symptom no longer reproduces.
+
+Evidence:
+
+```text
+RCA: symptom -> cause chain -> selected fix point
+Blue-team attack: <how this could still fail>
+Proof: <original symptom command/scenario>
+```
+
+## Amazon: Customer Backwards
+
+Use when user-visible result, UX, API, workflow, or acceptance is mismatched.
+
+Steps:
+
+1. Write the customer-visible success result first.
+2. Define what the user should see, do, or distinguish.
+3. Identify internal surfaces needed to create that result.
+4. Dive deep into facts instead of explaining old work.
+5. Prove with the user's acceptance scenario.
+
+Evidence:
+
+```text
+Customer result: <visible outcome>
+Acceptance proof: <scenario>
+```
+
+## Musk: The Algorithm
+
+Use when the previous work may be solving the wrong requirement or overbuilding.
+
+Steps:
+
+1. Question whether the requirement or artifact is correct.
+2. Delete unnecessary scope.
+3. Simplify the remaining path.
+4. Accelerate implementation only after simplification.
+5. Automate only when the manual path is proven.
+
+Evidence:
+
+```text
+Deleted scope: <what was cut>
+Simplified path: <why this is smaller>
+```
+
+## Jobs: Subtraction + Highest Standard
+
+Use when the result technically works but is unclear, ugly, hard to distinguish, or unsatisfying.
+
+Steps:
+
+1. Define the visible quality bar.
+2. Remove confusing or unnecessary elements.
+3. Make the primary result unmistakable.
+4. Keep one DRI-owned path.
+5. Inspect the final artifact from the user's eye level.
+
+Evidence:
+
+```text
+Quality bar: <what must be visibly true>
+User-eye review: <what changed>
+```
+
+## Baidu: Search First
+
+Use when the agent guessed from memory, missed docs, or facts may be stale.
+
+Steps:
+
+1. Search local source/docs before deciding.
+2. Prefer primary/local source over explanation.
+3. Record what was found and what is still unknown.
+4. Choose the simplest reliable option.
+
+Evidence:
+
+```text
+Source facts: <files/docs/commands checked>
+Unknowns: <none or remaining>
+```
+
+## ByteDance: Data/Proof
+
+Use when verification is weak, metrics matter, or confidence is replacing evidence.
+
+Steps:
+
+1. Define the proof metric or scenario before editing.
+2. Run the smallest meaningful check.
+3. Compare output to acceptance.
+4. Report PASS/FAIL/BLOCKED without hiding gaps.
+
+Evidence:
+
+```text
+Proof metric: <what proves it>
+Result: <actual output>
+```
+
+## Microsoft: Learning Loop
+
+Use when the same hypothesis keeps repeating or the agent did not change action after failure.
+
+Steps:
+
+1. Name the failed assumption.
+2. Gather new evidence.
+3. State the changed action.
+4. Verify impact.
+5. Capture next-time intercept if reusable.
+
+Evidence:
+
+```text
+Failed assumption: <old belief>
+Changed action: <new behavior>
+Verified impact: <proof>
+```
+
+## Pinduoduo: Cut Middle Layers
+
+Use when process, abstraction, or intermediate artifacts are blocking result.
+
+Steps:
+
+1. List the current chain of steps.
+2. Remove every middle layer not required for the user-visible result.
+3. Keep the shortest decision chain.
+4. Deliver the result path, not methodology theater.
+
+Evidence:
+
+```text
+Removed middle layers: <items>
+Shortest path: <remaining path>
+```
+
+## JD: Frontline Result
+
+Use when remote guessing, install/runtime mismatch, or real user environment is the risk.
+
+Steps:
+
+1. Inspect the actual runtime/install surface.
+2. Verify where the user will experience the result.
+3. Push decision to frontline evidence.
+4. Report only what real environment proof supports.
+
+Evidence:
+
+```text
+Frontline surface: <runtime/project/user-level surface>
+Environment proof: <command/scenario>
+```

package/assets/skills/devflow-pua/references/methodology-router.md

@@ -0,0 +1,78 @@
+# DevFlow PUA Methodology Router
+
+This is the local runtime source for pressure-recovery methodology. It is adapted into DevFlow-Core from the PUA methodology-router idea so agents do not need to link to or read another project at runtime.
+
+Use this file whenever `devflow-pua` activates.
+
+## Rule
+
+A flavor is not decoration. It is the active problem-solving method plus a short visible voice. Switching flavor means switching behavior.
+
+Always display the selected method with this compact user-facing line:
+
+```text
+METHOD: {flavor} / {method}
+```
+
+If switching away from a failed method, add:
+
+```text
+SWITCH: <old flavor>/<old method> -> <new flavor>/<new method>: <reason>
+```
+
+The route, switch reason, and evidence still matter, but they are internal selection checks unless the user asks for full diagnostics.
+
+## Starting Route
+
+| Signal | Flavor | Method | Required behavior |
+|---|---|---|---|
+| Bug, error, regression, behavior unchanged | Huawei | RCA + Blue-Team | Trace root cause, search callers, attack the fix before editing. |
+| User-visible UX/product/result mismatch | Amazon | Customer Backwards | Start from the user-visible result and acceptance proof. |
+| Repeated missing pieces, missed sync, incomplete entrypoints | Alibaba | Closure + Coverage Map | Enumerate every required surface and prove each one. |
+| New feature, scope pressure, overbuilding risk | Musk | The Algorithm | Question need, delete, simplify, then build the minimum. |
+| Quality complaint, hard-to-distinguish result, polish gap | Jobs | Subtraction + Highest Standard | Remove noise and define the visible quality bar. |
+| Guessing without evidence, docs/API uncertainty | Baidu | Search First | Retrieve facts before deciding. |
+| Proof gap, metrics, validation uncertainty | ByteDance | Data/Proof | Define measurable evidence before claiming result. |
+| Repeated same hypothesis, no changed action | Microsoft | Learning Loop | Failed assumption -> new evidence -> changed action -> proof. |
+| Too many middle steps, ceremony, or unnecessary layers | Pinduoduo | Cut Middle Layers | Remove process and ship the shortest result path. |
+
+Default when no signal is clear: Alibaba Closure, because recovery needs goal, process, result, and retrospective.
+
+## Failure Switch
+
+When the current method fails, switch by failure pattern. Do not repeat a failed method unchanged.
+
+| Failure pattern | Switch chain | Why |
+|---|---|---|
+| Same approach loop | Musk -> Pinduoduo -> Huawei | Reset assumptions, cut noise, then attack root cause. |
+| Missing this / missing that | Alibaba -> Amazon -> Huawei | Map surfaces, re-check desired result, then trace root cause. |
+| User says result is not what they wanted | Amazon -> Jobs -> Alibaba | Rebuild from user outcome, tighten visible quality, then close coverage. |
+| Behavior still unchanged | Huawei -> Microsoft -> Baidu | Root cause failed, inspect learning loop, then retrieve new facts. |
+| Proof absent or weak | ByteDance -> JD -> Alibaba | Evidence first, result ownership, closure. |
+| Guessing or stale memory | Baidu -> Amazon -> Huawei | Find facts, work backwards, then root-cause. |
+| Overbuilt or wrong artifact | Musk -> Jobs -> Alibaba | Delete wrong structure, focus target surface, close coverage. |
+
+## Pre-Switch Check
+
+Before switching, answer:
+
+1. Did the current method's core steps actually run?
+2. Is failure due to the method being wrong, or execution being incomplete?
+3. Does the next method directly address the failure pattern?
+
+If the current method was not executed, run it properly before switching. If it was executed and still missed, switch immediately and restart checks from facts.
+
+## Method Summaries
+
+| Flavor | Method summary |
+|---|---|
+| Alibaba | Define goal, track process, get result, retrospective. Recovery uses Coverage Map and closure proof. |
+| Huawei | RCA 5-Why, caller/reference search, Blue-Team attack, evidence-based delivery. |
+| Amazon | Customer Obsession, Working Backwards, Dive Deep, Single-Threaded Owner. |
+| Musk | Question requirement, delete, simplify, accelerate, automate only after proof. |
+| Jobs | Subtraction before addition, visible quality bar, DRI responsibility. |
+| Baidu | Search and source retrieval before judgment; simple and reliable output. |
+| ByteDance | Data before intuition; verification path before completion claim. |
+| Microsoft | Learning loop: failed assumption, new evidence, changed action, verified impact. |
+| Pinduoduo | Cut all middle layers; results only; shortest decision chain. |
+| JD | Customer result and frontline reality; no remote guessing. |

package/assets/skills/devflow-spec/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: devflow-spec
+description: "Use after devflow-core selects a saved spec for a confirmed request that needs approach comparison, a reviewable design contract, and a requirements document before implementation."
+---
+
+# DevFlow Spec
+
+Write the smallest useful spec document before implementation when the request needs more than a short design contract.
+
+This is Superpowers-style spec discipline adapted to DevFlow: write specs only when they reduce ambiguity, review them before planning, and keep plans traceable to specs or approved designs.
+
+## When To Write A Spec
+
+Use a saved spec when any of these are true:
+
+- The user asks for a spec, specs doc, design doc, or requirements document.
+- The work crosses modules, roles, persistence, APIs, release flow, or user-visible workflows.
+- Several requirements must stay aligned across implementation tasks.
+- The plan would be hard to review without a written source of truth.
+
+Do not force a spec for Design-lite work where a short design contract and quick proof are enough.
+
+## Process
+
+1. Consume the `Confirmed request` that `devflow-core` selected for Spec work, then read the relevant project facts. Do not re-confirm settled request fields or route the lifecycle.
+2. Load `skills/devflow-spec/references/spec-plan-methods.md`, then compare the smallest real options before writing: no change/reuse when it can meet the request, direct implementation, and any existing project pattern that materially changes the decision. State trade-offs and why the selected approach is the smallest useful one.
+3. Write the design contract and saved spec under `docs/specs/YYYY-MM-DD-<short-kebab-name>.md`, resolved from the current target project's root, unless that project already documents another specs path.
+4. Include the required sections with English headers:
+   - Goal
+   - Context
+   - Requirements
+   - Non-goals
+   - Approach
+   - Impact
+   - Acceptance
+   - Verification
+   - Code Documentation
+   - Open Questions
+
+   In `Approach`, record the compared options, trade-offs, chosen design, boundaries, and why rejected options do not meet the current request. Section content should be written in the user's language, but section headers must remain in English so `scripts/devflow-spec.js` can validate them.
+
+   The **Code Documentation** section records the documentation requirements this feature actually creates:
+   - Which modules/files or public interfaces need an explanation, and why
+   - Which functions/classes need a comment because their contract, failure behavior, or decision is not evident from code
+   - Which non-obvious, business, security, or compatibility boundaries need inline WHY comments
+   - Reference to existing project comment conventions when they apply
+   - For trivial changes or self-explanatory code with no triggered requirement, state "none — trivial change" explicitly
+5. Run the design/spec self-review:
+   - Unresolved-marker scan: no draft markers, unresolved question marks, or unresolved angle values.
+   - Consistency: requirements, chosen approach, impact, acceptance, and verification do not contradict.
+   - Scope: if multiple independent subsystems appear, split into separate specs.
+   - Design: the comparison names the real alternatives and the selected approach has an explicit trade-off.
+6. Run `node scripts/devflow-spec.js <spec-file>` when the script exists. If not found at `scripts/devflow-spec.js` (project-level), try `~/.codex/scripts/devflow-spec.js` or `~/.claude/scripts/devflow-spec.js` (user-level). Do NOT look under `skills/scripts/`. See `core-methods.md` Script Path Resolution.
+7. **STOP — Wait for user approval of the design contract and spec.** On DSH, request approval with the structured `ask_user_question` tool (single-select: approve / request changes). Tell the user the spec path and review result. If they request changes, revise the comparison/design contract and re-run self-review. An approved A-branch Spec directly enters `devflow-cut`; any non-success state returns facts to `devflow-core`.
+
+## Output
+
+```text
+Spec: docs/specs/YYYY-MM-DD-<short-kebab-name>.md
+Source: <Confirmed request selected by devflow-core>
+Design: options compared <pass/fail>; selected approach and trade-off <pass/fail>
+Review: unresolved-marker scan <pass/fail>; consistency <pass/fail>; scope <pass/fail>; design <pass/fail>
+Next: approved A-branch Spec -> `devflow-cut`; non-success facts -> `devflow-core`
+```
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|---|---|
+| "A plan is enough." | If requirements can drift across tasks, write the spec first. |
+| "The spec can be vague; the plan will decide." | Vague specs create wrong plans. Resolve or mark the question before planning. |
+| "Brainstorm already chose the approach." | Brainstorm confirms what the user wants; Spec compares how to satisfy it and records the design contract. |
+| "The user approved the spec, so Core must route it." | An approved A-branch Spec has one successor and directly enters Cut; exceptions still return Core facts. |
+| "This belongs in docs/features." | `docs/features/` is product ledger memory, not a generated implementation spec. |
+| "The user said implement, so skip approval." | Implementation requests still need the lightest useful design/spec source before Build. |
+| "Code Documentation is unnecessary, the code is self-explanatory." | Record the actual decision: `none — trivial change` is valid only when no project convention, public boundary, or non-obvious WHY needs preservation. |
+| "Comments will get stale." | Keep required documentation accurate; stale wording is not a reason to omit a needed contract or decision record. |
+| "I'll add comments later." | Name required documentation in the Spec so Plan and Build can verify it with the implementation. |
+
+## Verification
+
+Before leaving this skill, confirm:
+
+- [ ] Spec scope was named.
+- [ ] Real options, trade-offs, and the chosen approach are recorded in the design contract.
+- [ ] Required sections exist, including Code Documentation.
+- [ ] Spec landed under the current project's `docs/specs/YYYY-MM-DD-<short-kebab-name>.md` path or a documented target-project specs path.
+- [ ] Unresolved-marker, consistency, scope, and design checks ran.
+- [ ] Code Documentation section names triggered documentation requirements and locations (or explicitly states "none — trivial change").
+- [ ] `scripts/devflow-spec.js` ran when available.
+- [ ] User reviewed and approved the design contract and written spec.
+- [ ] An approved A-branch Spec entered `devflow-cut`; any non-success facts returned to `devflow-core`.

package/assets/skills/devflow-spec/references/spec-plan-methods.md

@@ -0,0 +1,15 @@
+# DevFlow Spec And Plan Methods
+
+Owner: `devflow-spec` and `devflow-plan`. Load this reference only after Core selects Spec or Plan.
+
+## Method 10: Spec Document And Plan Pack
+
+`devflow-spec` consumes an A-branch Confirmed request, compares real no-change/reuse/direct options, writes a reviewable design contract under `docs/specs/`, and waits for user approval. An approved A-branch Spec directly enters Cut; non-success facts return to Core.
+
+`devflow-plan` consumes A/B `CUT_PASS` plus an approved design or confirmed Spec. It creates one implementation plan under `docs/plans/`, then waits for user review. An approved A/B Plan directly enters Build; scope-drift facts return to Core.
+
+A Spec contains Goal, Context, Requirements, Non-goals, Approach, Impact, Acceptance, Verification, Code Documentation, and Open Questions. A Plan states Source, Spec coverage, Cut Decision, External Skills, exact files or anchors, interfaces, current and target behavior, mechanics, call impact, verification, comments, and exclusions.
+
+## Plan Contract
+
+The static plan checker validates structure, not architecture. A Plan must not expand the Cut Decision; any added dependency, abstraction, file responsibility, or feature returns scope-drift facts to Core.

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# @devflow-core/dsh-devflow bundle patch: inserts the host plugin row into the
+# web profile roster. Applied as a profile bundle layer (the `dsh.bundle.patch`
+# manifest field) over dsh-base; activate with
+# `dsh plugin --profile web add @devflow-core/dsh-devflow`.
+#
+# The row is a bare plugin by package name: the node half (exports ".") runs
+# in the host process and syncs the bundled DevFlow assets (preset devflow-2,
+# skills, commands, scripts) into ~/.dsh on startup. No browser half.
+- insert:
+    - id: devflow
+      name: '@devflow-core/dsh-devflow'