@devflow-core/dsh-devflow 0.1.0

package/assets/skills/devflow-core/references/core-methods.md

@@ -0,0 +1,131 @@
+# DevFlow Core Methods
+
+This is the shared method source loaded by `devflow-core` before route selection. It contains only the invariants needed by every route. Load the selected owner reference from the map below before applying lifecycle-specific rules.
+
+## Method 0: Architect Mindset
+
+Apply these principles to every route:
+
+1. Read the affected system and blast radius before changing it.
+2. Preserve contracts unless the accepted goal requires a contract change.
+3. Prefer the smallest necessary coupling and mechanism.
+4. Trace data and callers before diagnosing a bug.
+5. Scale ceremony to reversibility and failure modes.
+6. Treat complexity as a limited budget.
+7. Use fresh evidence, not intuition, for completion claims.
+8. Prefer the nearest established project convention before introducing a new pattern; a deliberate deviation states its reason, impact, and proof.
+9. Give each type or module one dominant responsibility; split, merge, or abstract only when responsibilities, dependencies, lifecycle, or likely change reasons materially differ.
+10. Evaluate caching, optimization, and concurrency against demonstrated workload or a concrete failure mode; add them only with measurable benefit plus clear ownership, invalidation, and consistency behavior.
+11. Optimize for local understanding: a maintainer familiar with the project should be able to identify business intent, key rules, failure paths, and side effects from nearby names and structure.
+12. Apply SOLID and platform best practices as decision lenses, not mandatory patterns. A simpler solution is preferred when it preserves correctness, readability, maintainability, contracts, and required performance.
+
+## Capability Map
+
+| Need | Runtime owner | Load when |
+|---|---|---|
+| Context, route choice, clarification, small-boundary, method lens, skill contract | this file | every `devflow-core` route |
+| Reuse, root cause, native, overbuild, debt | `skills/devflow-cut/references/cut-methods.md` | user-selected A/B/C direct entry or Core exception selection |
+| Spec or Plan | `skills/devflow-spec/references/spec-plan-methods.md` | A direct Spec / A/B direct Plan or Core exception selection |
+| Build minimal change and implementation slices | `skills/devflow-build/references/build-methods.md` | C `CUT_PASS`, approved A/B Plan, or Core exception selection |
+| Proof and recovery | `skills/devflow-prove/references/proof-recovery-methods.md` | completed Build direct Prove or Core exception selection |
+| Learning-card lifecycle | `skills/devflow-learn/SKILL.md` | Prove PASS review or reusable correction |
+
+## Method 1: Context Map
+
+Read the narrowest useful facts:
+
+1. Project rules and relevant source, tests, commands, and current docs.
+2. `.copilot/LEARNING_INDEX.md`, then only cards whose Trigger and Scope match.
+3. `docs/project-knowledge/AI-START-HERE.md` or `index.md`, then only navigation-selected documents.
+4. `graphify-out/GRAPH_REPORT.md` when architecture impact is in scope.
+5. Available environment skills; record a matching specialist skill without widening DevFlow scope. For a matched specialist, record the bounded-work contract:
+
+```text
+Owner: current DevFlow node
+Role: bounded specialist work
+Expected evidence: result needed by that node
+Return: result / not-applicable / failure facts
+
+The current owner evaluates the return using its existing gate.
+```
+
+A specialist result cannot alter depth, approval, direct-success, or Core-return rules; DevFlow remains the lifecycle meta-skill.
+
+Missing indexes or references are non-blocking and must not create storage.
+
+```text
+Facts: read/confirmed <files or commands>
+Methods: read/confirmed core-methods.md; selected owner references <paths or none>
+Knowledge recall: none / learning index + matched card / project knowledge entry + matched docs
+Skill Discovery: none / <skill-name> (matched: <why>)
+Unknowns: <none or specific unknown>
+```
+
+On DeepSeek Harness (DSH), a long autonomous node — a multi-command Problem or Fast investigation, or Prove evidence gathering with no user gate — may persist its objective with the `create_goal` / `update_goal` tools so it survives context compaction. Never use a goal to span the gated creative lifecycle (Brainstorm clarification, Spec or Plan approval stops): those remain explicit user gates.
+
+On DeepSeek Harness code mode (PTC, `run_code`), batch the independent Sense reads above into one program with `Promise.all` (read-only calls may overlap) and `print` only the needed fields instead of dumping full text, so the summary lands in the compaction head. Split into multiple calls when a later read depends on an earlier result. Wrap optional reads — missing indexes or matched cards — in `try/catch` around `ToolCallError` so a missing source stays non-blocking.
+
+## Method 2: Brainstorm Clarification
+
+Before any creative work — creating features, building components, adding functionality, modifying behavior, or defining an unapproved problem-directed change — select `devflow-brainstorm`. This applies even when the request appears clear or low risk. Pure Q&A, lookup, verification, investigation-only reports, and already approved changes remain outside this entry gate.
+
+Read minimum facts, send a Semantic Echo-Back, resolve one real uncertainty at a time, and stop after this fixed artifact:
+
+```text
+Confirmed request:
+- Goal: ...
+- Scope: ...
+- Out of scope: ...
+- Constraints: ...
+- Acceptance: ...
+- Open questions: ...
+- Status: clarified
+```
+
+After the fixed summary, Brainstorm presents A/B/C for an explicit user selection. A directly enters Spec; B and C directly enter Cut. Brainstorm never selects the depth itself. All non-success or non-unique artifacts return facts to Core for routing.
+
+## Method 3: Small Request Boundary
+
+Use Fast only when impact, risk, uncertainty, and proof are all small. Design-lite is for an existing feature with one plausible path after facts are read. Choose full Design when behavior, options, contracts, modules, compatibility, or rollback are unclear. Ask the user to choose when facts cannot distinguish the route.
+
+## Method 4: Method Lens
+
+Select one lens only when it changes execution judgment:
+
+| Lens | Use when | Action |
+|---|---|---|
+| Root Cause | Bug or regression | Search callers and shared cause before proposing a fix. |
+| Working Backwards | Product or workflow ambiguity | Start from a user-visible acceptance result. |
+| First Principles Cut | Problem solving, bug fixing, architecture, scope, or abstraction pressure | Reduce to facts, constraints, invariants, and smallest mechanism. |
+| Data/Proof | Metrics or verifier-sensitive work | Define evidence and owner before implementation. |
+| Operational Owner | Cross-file or release work | Name responsible surface and rollback or follow-through evidence. |
+
+## Method 15: Skill As Executable Contract
+
+Every skill must state when it applies, concrete actions, artifact or output, stop or return boundary, and verification. Put trigger language in its description. Do not duplicate the full framework in every skill or entry file.
+
+## Shared Output Contracts
+
+Design:
+
+```text
+Goal: ...
+Motivation: ...
+Smallest useful plan: ...
+Not doing: ...
+Impact: ...
+Verification: ...
+```
+
+Completion:
+
+```text
+Command: ...
+Result: ...
+Adversarial review: ...
+Judgment: PASS / FAIL / BLOCKED
+```
+
+## Script Path Resolution
+
+Resolve DevFlow checker scripts in this order: `scripts/devflow-<name>.js` in the target project, `~/.codex/scripts/devflow-<name>.js`, then `~/.claude/scripts/devflow-<name>.js`. A missing checker is noted as unavailable; do not search `skills/scripts/`. On DeepSeek Harness (DSH), run the target-project checker through the DSH shell tool as `node scripts/devflow-<name>.js` and resolve a user-level checker at `~/.dsh/scripts/devflow-<name>.js`; DSH has no `~/.codex` or `~/.claude` home.

package/assets/skills/devflow-core/references/reference-projects.md

@@ -0,0 +1,133 @@
+# Reference Project Extraction
+
+This file records what the local reference projects actually provide and what DevFlow-Core absorbed as native capabilities. It is an implementation audit, not a dependency map.
+
+## Ponytail
+
+What it does:
+
+- Enforces a smallest-working-solution ladder.
+- Prioritizes existing code, standard library, native platform, installed dependencies, one-line/config, then minimum new code.
+- Runs the ladder after reading and tracing the touched flow.
+- For bug fixes, searches callers and prefers the shared root-cause fix when it is the smaller correct fix.
+- Provides overengineering review and whole-repo audit tags: `delete`, `reuse`, `stdlib`, `native`, `yagni`, `shrink`.
+- Tracks deliberate simplifications with debt markers.
+- Provides `lite`, `full`, and `ultra` intensity modes.
+- Ships multi-host adapters and command entries.
+
+Absorbed into DevFlow-Core:
+
+- `devflow-cut` now owns the Minimal Solution Ladder and overengineering review tags.
+- `devflow-cut` now includes cut intensity levels and the bug-fix Root-Cause Check.
+- `skills/devflow-cut/references/native-capability-checklist.md` provides platform and standard-library alternatives.
+- `devflow-build` allows intentional simplification markers with explicit ceiling and revisit trigger.
+- `commands/devflow-debt.toml` harvests `devflow:` markers into a shortcut ledger.
+- `commands/devflow-review.toml` exposes a delete-list style review.
+- `commands/devflow-audit.toml`, `skills/devflow-audit/SKILL.md`, and `scripts/devflow-audit.js` expose a repo-wide overengineering audit without applying fixes.
+- `reuse` is a first-class overengineering tag for repeated helpers, utilities, types, or patterns that should use existing project code.
+
+Not absorbed:
+
+- Benchmark scoreboard and hook-based mode persistence. They are useful product features, but not required for the first practical DevFlow release.
+
+## Agent Skills
+
+What it does:
+
+- Organizes development into lifecycle commands: define, plan, build, verify, review, ship.
+- Defines a consistent skill anatomy: frontmatter, process, rationalizations, red flags, verification.
+- Uses context engineering, source-driven development, incremental implementation, test-driven development, code simplification, and launch checklists.
+- Provides commands and persona-style reviewers.
+
+Absorbed into DevFlow-Core:
+
+- `skills/devflow-core/references/skill-guide.md` and all `SKILL.md` files now require executable skill contracts, anti-rationalization checks, and verification.
+- `devflow-core` maps work to route and next skill.
+- `devflow-build` includes plan-pack, source-check, and slice execution.
+- `devflow-prove` includes rules/skills/references validation.
+- `commands/*.toml` expose practical lifecycle entry points.
+
+Not absorbed:
+
+- Full 24-skill lifecycle. DevFlow-Core keeps a small focused skill set to stay lightweight.
+
+## Superpowers
+
+What it does:
+
+- Makes brainstorming mandatory before creative/build work.
+- Writes design docs and implementation plans with hard handoffs.
+- Executes plans through small tasks with verification.
+- Uses subagent-driven development, code review gates, TDD, and verification-before-completion.
+- Tests skills through real pressure scenarios.
+
+Absorbed into DevFlow-Core:
+
+- `Sense -> Brainstorm -> [STOP: Depth A/B/C] -> (A: devflow-spec -> /devflow-plan | B: /devflow-plan | C: direct) -> devflow-cut -> devflow-build -> devflow-prove` remains the default chain.
+- `devflow-brainstorm` includes design approval shape, assumption challenges, and approach comparison.
+- `devflow-spec`, `commands/devflow-spec.toml`, and `scripts/devflow-spec.js` add a saved requirements source for larger or explicitly spec-requested work.
+- Generated specs default to `docs/specs/YYYY-MM-DD-<short-kebab-name>.md`; `docs/plans/` remains implementation planning.
+- `devflow-plan` and Plan Pack now require `Source:` and `Spec coverage:` so tasks trace to a spec or approved design.
+- `devflow-build` includes implementation slices and exact verification per slice.
+- `skills/devflow-prove/references/flow-self-test.md` defines pressure scenarios for the framework itself.
+
+Not absorbed:
+
+- Mandatory worktree/subagent/full TDD or full design-doc approval for every task. DevFlow-Core uses saved specs only when they reduce ambiguity.
+
+## PUA-Driven Spec Engineering
+
+What it does:
+
+- Adds Fast / Design / Escalate routing.
+- Requires project fact checks, Graphify, project knowledge, learning index, and coding rules before conclusions.
+- Enforces skill activation evidence and completion proof.
+- Maintains cross-platform rule consistency.
+- Defines Codex-compatible proof contracts where local verification is candidate evidence, not final external verifier status.
+
+Absorbed into DevFlow-Core:
+
+- `devflow-core` now includes Fast / Design / Recovery routing.
+- `skills/devflow-core/references/core-methods.md` includes Method Lens so Design, Recovery, and high-risk proof can choose a task-specific working strategy.
+- `devflow-pua` now owns a local pressure-recovery methodology stack under `skills/devflow-pua/references/`: router, method library, and flavor display protocol.
+- `devflow-brainstorm` now requires Method Lens selection or an explicit "standard route is enough" decision before the design contract.
+- `devflow-learn` preserves the learning/pitfall card loop with `.copilot/LEARNING_INDEX.md` and matched cards.
+- `AGENTS.md`, `.github/copilot-instructions.md`, and CodeBuddy rules stay semantically aligned.
+- `devflow-prove` requires command/result/judgment and separates `candidate_pass` from external final approval when relevant.
+- `devflow-prove` includes a Skill Activation Chain Check after rule, command, prompt, entry, or skill changes.
+- `skills/devflow-prove/references/flow-self-test.md` includes correction and learning scenarios.
+
+Not absorbed:
+
+- Heavy pressure rhetoric and full spec-heavy process default. DevFlow-Core keeps the recovery mechanics without making every task high-pressure.
+
+## PUA
+
+What it does:
+
+- Packages one core behavior across many platforms.
+- Provides explicit commands, submodes, multi-language entry points, verifier/policy/action/self-review roles, and high-agency recovery.
+- Uses method routing and failure-pattern switching.
+- Emphasizes proactive follow-through, evidence, and independent verification.
+
+Absorbed into DevFlow-Core:
+
+- `plugin.json`, `gemini-extension.json`, commands, Copilot, and CodeBuddy entries make the framework installable/adaptable.
+- Method Lens absorbs PUA method routing as native DevFlow behavior for normal work: Root Cause, Working Backwards, First Principles Cut, Data/Proof, and Operational Owner are selectable lenses.
+- `devflow-pua/references/methodology-router.md`, `methodology-library.md`, and `flavor-display.md` absorb the practical PUA flavor-method routing for pressure recovery, including the compact visible output `METHOD: {flavor} / {method}` plus a concise `SWITCH:` line when the method changes.
+- `devflow-prove` forbids self-certifying completion without evidence.
+- `devflow-core` includes Recovery route and 3-hypothesis approach switching.
+
+Not absorbed:
+
+- Full PUA persona theater, pressure rhetoric, leaderboard, network feedback, agent lifecycle accounting, hook automation, and default full spec-heavy process. DevFlow-Core only keeps the lightweight flavor-method display needed for pressure recovery.
+
+## Resulting Product Shape
+
+DevFlow-Core is intentionally smaller than the reference projects:
+
+- A small focused skill set, not 20+ lifecycle skills.
+- One native method reference, not multiple competing method systems.
+- Commands and platform entry files are thin adapters.
+- Verification is runnable with `npm test`.
+- Heavy flows are optional escalation, not the default developer experience.

package/assets/skills/devflow-core/references/skill-guide.md

@@ -0,0 +1,63 @@
+# DevFlow Skill Guide
+
+## Skill Chain
+
+```text
+devflow-core -> devflow-brainstorm -> user-selected A/B/C
+  -> A: devflow-spec -> devflow-cut -> devflow-plan -> devflow-build -> devflow-prove
+  -> B: devflow-cut -> devflow-plan -> devflow-build -> devflow-prove
+  -> C: devflow-cut -> devflow-build -> devflow-prove
+  -> non-unique artifact: return facts to devflow-core
+  -> devflow-pua (when user challenge/repeated miss appears)
+  -> devflow-learn (when correction/pitfall appears)
+  -> devflow-audit (when repo-wide overengineering audit is requested)
+```
+
+## Skill Responsibilities
+
+| Skill | Responsibility |
+|---|---|
+| `devflow-core` | Route entry and any non-unique artifact, load shared methods, and maintain the compact flow map. |
+| `devflow-brainstorm` | Clarify intent, then let the user select A/B/C and start its direct branch. |
+| `devflow-spec` | Write and validate saved requirements specs under `docs/specs/` before implementation planning. |
+| `devflow-plan` | Create a Plan Pack from a `CUT_PASS`-bounded spec or approved design. |
+| `devflow-cut` | Prevent overengineering and force reuse checks. |
+| `devflow-build` | Implement the approved smallest useful change. |
+| `devflow-prove` | Verify and report evidence before completion. |
+| `devflow-pua` | Stop wrong-path recovery, re-ask or infer the desired result, switch approach, and hand back to Prove/Learn. |
+| `devflow-learn` | Capture reusable corrections and pitfalls into `.copilot` learning cards. |
+| `devflow-audit` | Audit a repository or scope for overengineering candidates without editing files. |
+
+## Authoring Rules
+
+- Keep each skill short enough to load directly.
+- Put trigger phrases in `description`.
+- Prefer imperative steps over explanation.
+- Do not duplicate all framework rules inside every skill.
+- A skill directly follows only its named A/B/C success edge; every other artifact returns facts to Core or states an independent stop boundary.
+- Each skill must be executable: trigger, action steps, anti-rationalization check, stop/handoff, proof.
+- Put shared routing details in `skills/devflow-core/references/core-methods.md`; put detailed lifecycle methods in the selected owner's local reference.
+- Keep runtime methods in `skills/*/references/*`. `docs/` is reserved for product and generated artifacts — `docs/specs/` for saved specs, `docs/plans/` for saved plans — never runtime framework methods.
+
+## Minimum Skill Contract
+
+Every `SKILL.md` must include:
+
+1. YAML frontmatter with `name` matching the folder.
+2. A `description` that says what the skill does and when to use it.
+3. Concrete steps.
+4. Required output or artifact.
+5. Handoff target or stop condition.
+6. Verification or Proof section.
+
+## Command Mapping
+
+| Command | Primary skill |
+|---|---|
+| `/devflow` | `devflow-core` |
+| `/devflow-spec` | `devflow-spec` |
+| `/devflow-plan` | Plan creation from spec or approved design |
+| `/devflow-review` | `devflow-cut` |
+| `/devflow-prove` | `devflow-prove` |
+| `/devflow-pua` | `devflow-pua` |
+| `/devflow-audit` | `devflow-audit` |

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

@@ -0,0 +1,208 @@
+---
+name: devflow-cut
+description: "Use before adding code, dependencies, abstractions, configs, folders, framework layers, generic engines, reusable capabilities, or when checking YAGNI, Ponytail ladder reuse, root-cause fixes, platform-native options, scope creep, bloat, and simplification. Cuts unnecessary work before writing it. Also use when the user says 'review for over-engineering', 'is this over-engineered', 'simplify review', 'review this diff/PR for cuts', or '/devflow-cut'."
+---
+
+# DevFlow Cut
+
+Cut unnecessary work before writing it.
+
+**Violating the letter of the rules is violating the spirit of the rules.**
+
+## Context
+
+Receives a Core-selected approved design or an approved A-branch Spec. Cut decides the smallest implementation boundary before any construction plan; do not use a future plan as evidence for these gates.
+
+Before applying the Minimal Solution Ladder or Required Gates, load `skills/devflow-cut/references/cut-methods.md`. That reference owns the detailed reuse, root-cause, native, overbuild, and debt rules.
+
+- `CUT_PASS` produces a Cut Decision and directly enters Plan for A/B or Build for C.
+- A user-approved Plan Pack receives only a lightweight Cut-consistency review. If it adds scope, dependencies, abstractions, or file responsibilities outside the Cut Decision, return the affected-gate facts to Core before any further lifecycle choice.
+
+## Cut Intensity
+
+Choose the lightest level that fits the risk:
+
+| Level | Use when | Behavior |
+|---|---|---|
+| `lite` | User asks for a normal feature and the requested path is plausible. | Build the requested path, but name the smaller alternative in one line. |
+| `full` | Default for coding, fixes, dependencies, abstractions, and framework work. | Enforce the ladder and block avoidable new structure. |
+| `ultra` | User asks to simplify, remove bloat, avoid overengineering, or review a diff/repo for cuts. | Prefer deletion before addition and challenge the requirement when a smaller outcome covers it. |
+
+## Minimal Solution Ladder
+
+This is the canonical ladder; `cut-methods.md` does not redefine it. **Ponytail** names the reference project whose smallest-solution ladder this section absorbs natively — the `Ponytail Rung` field in the Required Gates reports the numbered rung where this ladder stops.
+
+After reading the touched flow, stop at the first rung that works:
+
+1. Does this need to exist?
+2. Can the user goal be met by not changing code?
+3. Does it already exist in this codebase?
+4. Does an available skill in the environment handle this without writing new code? (e.g., `pdf` for reading a PDF, `understand` for codebase analysis. If a skill like `frontend-design` can perform bounded specialist work, load it alongside the devflow route — it complements, not replaces, the devflow chain. Produce `CUT_REUSE` only when the skill fully handles the task with no new code needed.)
+5. Does the standard library do it?
+6. Does the native platform do it?
+7. Does an already-installed dependency do it?
+8. Can it be one line or direct configuration?
+9. Only then write the minimum new code.
+
+If two rungs both work, take the earlier rung and move on. The ladder is not permission to skip reading; first trace the real flow the change touches.
+
+External specialist skills complement the chain but never widen it. Under conflict the priority is: Cut Decision > Plan Pack > external skill guidance. When a matched skill (e.g., `frontend-design`) recommends structure outside the allowed scope, keep the Cut scope and return the broader recommendation as scope-drift facts to `devflow-core`.
+
+## Root-Cause Fix Check
+
+For bug fixes, do not patch only the reported symptom. Before editing a function, component, route, command, or rule:
+
+1. Search callers/references of the touched unit.
+2. Decide whether one shared guard/fix solves all callers with less code than per-caller patches.
+3. If the shared fix would change unrelated behavior, name that risk and keep the narrower fix.
+
+Output:
+
+```text
+Root-Cause Check: searched <callers/references>; fix location <shared/narrow>; reason <why>
+```
+
+## Native Capability Check
+
+Before adding a dependency or wrapper, scan `skills/devflow-cut/references/native-capability-checklist.md` for the relevant layer.
+
+Output:
+
+```text
+Native Check: checked <layer>; native option <used/not enough>; reason <why>
+```
+
+If the native option is not enough, name the current limitation and evidence.
+
+## Required Gates
+
+Missing answers block Build:
+
+```text
+Reuse Check: what existing capability was searched/confirmed? Include available environment skills that match the task.
+Ponytail Rung: where did the ladder stop, and why were lower rungs insufficient?
+Root-Cause Check: for bug fixes, were callers/shared entry points searched? shared or narrow fix, and why?
+Native Check: is platform or standard-library capability enough?
+Overbuild Check: any new dependency/abstraction/config/directory/framework layer/generic engine? why needed now?
+Diff Check: how does each planned change trace to the goal?
+Scope Check: what unrequested behavior was cut?
+External Skills: <skill-name>; role: <bounded specialist work>; expected evidence: <result needed by this node>; return facts: <result / not-applicable / failure> / none — matched at Sense via Skill Discovery; inherited by the Plan Pack and loaded by Build.
+```
+
+## Overengineering Review Tags
+
+When reviewing a diff or plan, output one line per finding:
+
+```text
+<file>:L<line>: <tag>: <what to cut>. <replacement>.
+```
+
+Tags:
+
+- `delete`: dead code, unused flexibility, speculative feature
+- `reuse`: duplicate code or helper that should use an existing project helper, utility, type, or pattern
+- `stdlib`: hand-rolled thing the standard library ships
+- `native`: dependency or code doing what the platform already does
+- `yagni`: abstraction/config/layer with no current need
+- `shrink`: same behavior with fewer moving parts
+
+End with:
+
+```text
+net: <N> lines/deps/steps possible
+```
+
+If nothing should be cut, say:
+
+```text
+Lean already. Ship.
+```
+
+## Examples
+
+✅ `src/validator.js:L12-38: stdlib: 27-line EmailValidator class. "@" in email, 1 line; real validation is the confirmation mail.`
+
+✅ `utils/time.js:L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`
+
+✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`
+
+✅ `api/retry.js:L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`
+
+✅ `build.js:L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`
+
+✅ `helpers/format.js:L9: reuse: duplicate date formatter. Use utils/time.js:formatDate, already in project.`
+
+❌ "This EmailValidator class might be more complex than necessary, have you considered whether all these validation rules are needed at this stage?" — 太软，无定位、无替换方案、无量化。
+
+## Intentional Simplification Marker
+
+If you intentionally choose a shortcut with a real ceiling, mark it in code or docs:
+
+```text
+devflow: <ceiling>, revisit when <trigger>
+```
+
+Use the marker only for deliberate, accepted simplifications. The marker must name both the ceiling and the revisit trigger so `/devflow-debt` can harvest it later.
+
+Never use a marker to excuse missing security, data safety, accessibility, or required validation.
+
+## Do Not Cut
+
+Do not remove:
+
+- trust-boundary validation
+- auth, permission, or data-loss protection
+- security and accessibility
+- explicitly requested behavior
+- the smallest useful verification for non-trivial logic
+
+## Cut Result
+
+Output one of:
+
+```text
+CUT_PASS: smallest scope holds; A/B enter `devflow-plan`, C enters `devflow-build`
+CUT_REDUCE: proposed scope is too heavy; reduce to <smaller option>
+CUT_REUSE: existing capability can be reused; do not write new implementation
+CUT_BLOCKED: missing facts or risk too high; return the blocking facts to `devflow-core`
+```
+
+When `CUT_REDUCE` or `CUT_REUSE` occurs, **STOP — present the reduction or reuse finding to the user**. Explain what was cut, what existing capability replaces it, and why the smaller option is sufficient. After confirmation, return the confirmed result to `devflow-core`.
+
+When `CUT_BLOCKED` occurs, return the blocking facts to `devflow-core`. Core decides whether it must restart `devflow-brainstorm` to re-explore the goal and constraints.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|---|---|
+| "This abstraction will help later." | Later can add it when there is a second real use. |
+| "A dependency is cleaner." | Cleaner than platform/native only when a current limitation proves it. |
+| "It's just a tiny wrapper." | Wrappers become owned API. Check if they add real value. |
+| "Tests are bloat." | The smallest useful verification is not bloat. |
+| "This is only the ticketed path." | For bugs, check callers first; the shared root cause may be the smaller fix. |
+| "We can add the upgrade later." | If a shortcut has a known ceiling, record the trigger with `devflow:` now. |
+
+## Red Flags — STOP
+
+- About to write new code without running the ladder
+- "This abstraction will help later" without a second real use today
+- Adding a dependency when native/stdlib covers it
+- Skipping Root-Cause Check for a bug fix
+- Cutting trust-boundary validation, security, or data-loss protection
+- Proceeding to Build with `CUT_REDUCE` or `CUT_REUSE` without user confirmation
+
+**All of these mean: stop and run the gates.**
+
+## Handoff
+
+After `CUT_PASS`, record a Cut Decision containing the allowed scope, reuse conclusion, exclusions, required verification, `External Skills`, and `Depth`. A recorded specialist role performs bounded work only; Cut retains reuse and scope authority, and `CUT_PASS` is never delegated. A/B directly enter `devflow-plan`; C directly enters `devflow-build`. `CUT_REDUCE`, `CUT_REUSE`, and `CUT_BLOCKED` return facts to `devflow-core`; `CUT_REDUCE` and `CUT_REUSE` remain stopped until user confirmation. A Plan Pack that broadens scope returns affected-gate facts to Core before any later selection.
+
+## Verification
+
+Before leaving this skill, confirm:
+
+- [ ] Reuse, Root-Cause when relevant, Native, Overbuild, Diff, and Scope checks were answered.
+- [ ] Any new structure has a current need.
+- [ ] Removed scope is explicitly named.
+- [ ] Intentional simplifications have `devflow:` ceiling and revisit trigger markers.
+- [ ] Cut result is one of the four allowed statuses.

package/assets/skills/devflow-cut/references/cut-methods.md

@@ -0,0 +1,65 @@
+# DevFlow Cut Methods
+
+Owner: `devflow-cut`. Load this reference after a user-selected A/B/C direct Cut entry or when Core selects Cut for a non-unique artifact.
+
+## Method 5: Minimal Solution Ladder
+
+The canonical Minimal Solution Ladder lives in `skills/devflow-cut/SKILL.md` (nine rungs, plus the `Ponytail` definition). Do not redefine the ladder here: read the SKILL.md ladder, stop at the first rung that meets the accepted goal, and record the selected rung.
+
+Record:
+
+```text
+Reuse Check: searched <files/helpers/patterns/skills>; selected rung <N>; reason <why lower rungs failed>
+```
+
+Do not cut explicit behavior, accessibility, security, data protection, or the smallest useful verification.
+
+## Method 6: Root-Cause Fix Check
+
+For bugs, search the likely function, route, command, helper, and callers before editing. Prefer a shared correction when it covers sibling callers without changing unrelated behavior; otherwise record why the narrow correction is safer.
+
+```text
+Root-Cause Check: searched <callers/references>; fix location <shared/narrow>; reason <why>
+```
+
+## Method 7: Native Capability Check
+
+Read `native-capability-checklist.md` before adding a dependency or wrapper. Name the current platform limitation when native capability is insufficient.
+
+```text
+Native Check: checked <layer>; platform option <used/not enough>; reason <why>
+```
+
+## Method 8: Anti-Overengineering Gate
+
+Before adding a dependency, abstraction, configuration surface, directory, framework layer, or generic engine, answer why it is needed now. One caller favors direct code. Hypothetical reuse does not justify a new structure.
+
+```text
+Overbuild Check: what new structure is being added? Why is it needed now?
+Reuse Check: what existing capability was checked first?
+Trace Check: what accepted request does each key change trace to?
+Scope Check: what tempting but unrequested feature was removed?
+Diff Check: which user goal does each changed file serve?
+```
+
+## Method 8A: Contextual Design Quality Check
+
+For changes that introduce or relocate code, alter module responsibilities, or add performance behavior, inspect the nearest comparable project code before selecting a shape. Record the decision without requiring a fixed layer, class count, interface, or cache:
+
+```text
+Convention Check: compared <nearby files/patterns>; followed <convention> / deviated because <current reason>; impact <none or specific>
+Responsibility Check: <type/module> owns <dominant responsibility>; split/merge/abstraction <not needed or reason tied to dependencies/lifecycle/change reason>
+Performance Check: workload/failure evidence <facts or none>; cache/optimization/concurrency <not needed or chosen>; benefit, ownership, invalidation, consistency <when chosen>
+Readability Check: local names/structure expose <intent, key rules, failure paths, side effects>; remaining trade-off <none or specific>
+```
+
+A simpler solution may replace a nearby pattern when it improves correctness, readability, maintainability, or measured performance without breaking an accepted contract. Do not add a structure merely to satisfy a principle name.
+
+
+When a safe, deliberate shortcut has a known ceiling, mark it near the choice:
+
+```text
+devflow: <ceiling>, revisit when <trigger>
+```
+
+Never use a marker to excuse missing security, data safety, accessibility, or requested behavior.