@devflow-core/dsh-devflow 0.1.0

package/assets/scripts/devflow-review.js

@@ -0,0 +1,93 @@
+const fs = require("node:fs");
+
+const requiredGates = [
+  { name: "Reuse Check", pattern: /Reuse Check/i },
+  { name: "Ponytail Rung", pattern: /Ponytail Rung/i },
+  { name: "Native Check", pattern: /Native Check/i },
+  { name: "Overbuild Check", pattern: /Overbuild Check/i },
+  { name: "Diff Check", pattern: /Diff Check/i },
+  { name: "Scope Check", pattern: /Scope Check/i }
+];
+
+function usage() {
+  console.log("Usage: node scripts/devflow-review.js [plan-or-diff-file] [--self-test] [--json]");
+  console.log("Checks whether a plan or review text includes the DevFlow anti-overengineering gates.");
+}
+
+function reviewText(body) {
+  const missing = requiredGates.filter((gate) => !gate.pattern.test(body));
+  const present = requiredGates.filter((gate) => gate.pattern.test(body));
+
+  return {
+    present,
+    missing,
+    ok: missing.length === 0
+  };
+}
+
+function report(body, json) {
+  const result = reviewText(body);
+  const judgment = result.ok ? "PASS" : "FAIL";
+
+  if (json) {
+    console.log(JSON.stringify({ checker: "review", present: result.present.map((gate) => gate.name), missing: result.missing.map((gate) => gate.name), judgment }));
+    return result.ok ? 0 : 1;
+  }
+
+  console.log("DevFlow review gate report");
+  console.log(`Present gates: ${result.present.map((gate) => gate.name).join(", ") || "none"}`);
+  console.log(`Missing gates: ${result.missing.map((gate) => gate.name).join(", ") || "none"}`);
+
+  if (!result.ok) {
+    console.log("Judgment: FAIL");
+    return 1;
+  }
+
+  console.log("Judgment: PASS");
+  return 0;
+}
+
+function readInput(args) {
+  const targetArg = args.find((arg) => !arg.startsWith("-"));
+  if (targetArg) {
+    return fs.readFileSync(targetArg, "utf8");
+  }
+  return fs.readFileSync(0, "utf8");
+}
+
+function selfTest() {
+  const validPlan = [
+    "Reuse Check: searched existing helpers",
+    "Ponytail Rung: one-line/config",
+    "Native Check: standard library not enough",
+    "Overbuild Check: no new abstraction",
+    "Diff Check: README only",
+    "Scope Check: no extra features"
+  ].join("\n");
+  const invalidPlan = "Reuse Check: searched existing helpers";
+
+  if (!reviewText(validPlan).ok) {
+    throw new Error("Self-test expected valid plan to pass");
+  }
+  const invalidResult = reviewText(invalidPlan);
+  if (invalidResult.ok || invalidResult.missing.length !== 5) {
+    throw new Error("Self-test expected invalid plan to fail with 5 missing gates");
+  }
+
+  console.log("DevFlow review self-test passed");
+  console.log("Checked required gate detection and missing gate reporting");
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+if (args.includes("--self-test")) {
+  selfTest();
+  process.exit(0);
+}
+
+const body = readInput(args);
+process.exitCode = report(body, args.includes("--json"));

package/assets/scripts/devflow-spec.js

@@ -0,0 +1,238 @@
+const fs = require("node:fs");
+
+const requiredFields = [
+  "Goal",
+  "Context",
+  "Requirements",
+  "Non-goals",
+  "Approach",
+  "Impact",
+  "Acceptance",
+  "Verification",
+  "Code Documentation",
+  "Open Questions"
+];
+
+const fieldPatterns = Object.fromEntries(
+  requiredFields.map((field) => [field, new RegExp(`^\\s*(?:#+\\s*)?${field}\\s*(?::|$)`, "im")])
+);
+
+const unresolvedPatterns = [
+  /\bTODO\b/i,
+  /\bTBD\b/i,
+  /\bcoming soon\b/i,
+  /\?\?\?/,
+  /<[^>\n]+>/
+];
+
+const vaguePatterns = [
+  /\bhandle edge cases\b/i,
+  /\bas needed\b/i,
+  /\bdefine later\b/i,
+  /\bfigure out\b/i,
+  /\bmake it work\b/i
+];
+// 可选生命周期状态字段：缺失视为 legacy（向后兼容），存在时值域受限；checker 只校验格式，不裁决状态转换。
+const validStatuses = ["draft", "approved", "in-progress", "done"];
+const statusPattern = /^\s*(?:\*\*)?Status(?:\*\*)?\s*:\s*([^\n]+)/im;
+
+function usage() {
+  console.log("Usage: node scripts/devflow-spec.js [spec-file] [--self-test] [--json]");
+  console.log("Checks whether a DevFlow spec has required sections, clear content, and the right landing path.");
+  console.log("--json prints a single-line machine-readable summary; optional Status header values: " + validStatuses.join(" | "));
+}
+
+function findMatches(body, patterns) {
+  return patterns.flatMap((pattern) => {
+    const matches = body.match(pattern);
+    return matches ? [matches[0]] : [];
+  });
+}
+
+function checkSpec(body) {
+  const missing = requiredFields.filter((field) => !fieldPatterns[field].test(body));
+  const unresolved = findMatches(body, unresolvedPatterns);
+  const vague = findMatches(body, vaguePatterns);
+  const statusMatch = body.match(statusPattern);
+  const status = statusMatch ? statusMatch[1].trim() : "legacy";
+  const invalidStatus = statusMatch ? !validStatuses.includes(status) : false;
+
+  return {
+    missing,
+    unresolved,
+    vague,
+    status,
+    invalidStatus,
+    ok: missing.length === 0 && unresolved.length === 0 && vague.length === 0 && !invalidStatus
+  };
+}
+
+function checkSpecLanding(filePath) {
+  if (!filePath) {
+    return { ok: true, message: "Spec landing: stdin input, no file path checked" };
+  }
+
+  const normalized = filePath.replaceAll("\\", "/");
+  const isDocsSpecs = /(^|\/)docs\/specs\/[^/]+\.md$/i.test(normalized);
+  const isFeatureLedger = /(^|\/)docs\/features\/[^/]+\.md$/i.test(normalized);
+  const isPlanDoc = /(^|\/)docs\/plans\/[^/]+\.md$/i.test(normalized);
+
+  if (isDocsSpecs) {
+    return { ok: true, message: "Spec landing: ok docs/specs/YYYY-MM-DD-<short-kebab-name>.md" };
+  }
+
+  if (isFeatureLedger) {
+    return {
+      ok: false,
+      message: "Spec landing: docs/features is for feature ledgers; put generated specs under docs/specs/YYYY-MM-DD-<short-kebab-name>.md"
+    };
+  }
+
+  if (isPlanDoc) {
+    return {
+      ok: false,
+      message: "Spec landing: docs/plans is for implementation plans; put specs under docs/specs/YYYY-MM-DD-<short-kebab-name>.md"
+    };
+  }
+
+  return {
+    ok: true,
+    message: "Spec landing: warning expected docs/specs/YYYY-MM-DD-<short-kebab-name>.md unless this project has a documented specs path"
+  };
+}
+
+function report(body, filePath, json) {
+  const result = checkSpec(body);
+  const landing = checkSpecLanding(filePath);
+  const judgment = !result.ok || !landing.ok ? "FAIL" : "PASS";
+
+  if (json) {
+    console.log(
+      JSON.stringify({
+        checker: "spec",
+        landing: landing.message,
+        status: result.status,
+        invalidStatus: result.invalidStatus,
+        missing: result.missing,
+        unresolved: result.unresolved,
+        vague: result.vague,
+        judgment
+      })
+    );
+    return judgment === "PASS" ? 0 : 1;
+  }
+
+  console.log("DevFlow spec report");
+  console.log(landing.message);
+  console.log(`Status: ${result.invalidStatus ? "invalid" : result.status}`);
+  console.log(`Missing sections: ${result.missing.join(", ") || "none"}`);
+  console.log(`Unresolved markers: ${result.unresolved.join(", ") || "none"}`);
+  console.log(`Vague terms: ${result.vague.join(", ") || "none"}`);
+
+  if (!result.ok || !landing.ok) {
+    console.log("Judgment: FAIL");
+    return 1;
+  }
+
+  console.log("Judgment: PASS");
+  return 0;
+}
+
+function readInput(args) {
+  const targetArg = args.find((arg) => !arg.startsWith("-"));
+  if (targetArg) {
+    return fs.readFileSync(targetArg, "utf8");
+  }
+  return fs.readFileSync(0, "utf8");
+}
+
+function selfTest() {
+  const validSpec = [
+    "Goal: Add spec validation",
+    "Context: DevFlow needs a saved requirements source before larger plans.",
+    "Requirements: Validate required sections and landing path.",
+    "Non-goals: Generate specs automatically.",
+    "Approach: Use a zero-dependency Node checker.",
+    "Impact: scripts/devflow-spec.js and command metadata.",
+    "Acceptance: Complete spec reports PASS.",
+    "Verification: node scripts/devflow-spec.js --self-test",
+    "Code Documentation: scripts/devflow-spec.js needs file-level comment explaining checker purpose; checkSpec function needs comment explaining validation logic.",
+    "Open Questions: none"
+  ].join("\n");
+  const missingSpec = [
+    "Goal: Add spec validation",
+    "Context: DevFlow needs a saved requirements source.",
+    "Code Documentation: none — trivial change"
+  ].join("\n");
+  const vagueSpec = [
+    "Goal: TODO",
+    "Context: define later",
+    "Requirements: handle edge cases",
+    "Non-goals: none",
+    "Approach: make it work",
+    "Impact: scripts/devflow-spec.js",
+    "Acceptance: ???",
+    "Verification: node scripts/devflow-spec.js --self-test",
+    "Code Documentation: none — trivial change",
+    "Open Questions: <question>"
+  ].join("\n");
+
+  if (!checkSpec(validSpec).ok) {
+    throw new Error("Self-test expected valid spec to pass");
+  }
+
+  const missingResult = checkSpec(missingSpec);
+  if (missingResult.ok || !missingResult.missing.includes("Requirements")) {
+    throw new Error("Self-test expected missing sections to fail");
+  }
+
+  const vagueResult = checkSpec(vagueSpec);
+  if (vagueResult.ok || vagueResult.vague.length === 0 || vagueResult.unresolved.length === 0) {
+    throw new Error("Self-test expected vague and unresolved terms to fail");
+  }
+
+  const validLanding = checkSpecLanding("docs/specs/2026-07-14-add-spec-scanner.md");
+  if (!validLanding.ok) {
+    throw new Error("Self-test expected docs/specs landing to pass");
+  }
+
+  const withValidStatusSpec = validSpec.replace(
+    "Goal: Add spec validation",
+    "Status: draft\nGoal: Add spec validation"
+  );
+  const withInvalidStatusSpec = validSpec.replace(
+    "Goal: Add spec validation",
+    "Status: shipped\nGoal: Add spec validation"
+  );
+  if (!checkSpec(withValidStatusSpec).ok) throw new Error("Self-test expected valid Status to pass");
+  if (checkSpec(withInvalidStatusSpec).ok) throw new Error("Self-test expected invalid Status to fail");
+  if (checkSpec(validSpec).status !== "legacy") throw new Error("Self-test expected missing Status to stay legacy");
+
+  const badPlanLanding = checkSpecLanding("docs/plans/2026-07-14-add-spec-scanner.md");
+  if (badPlanLanding.ok) {
+    throw new Error("Self-test expected docs/plans spec landing to fail");
+  }
+
+  const badFeatureLanding = checkSpecLanding("docs/features/add-spec-scanner.md");
+  if (badFeatureLanding.ok) {
+    throw new Error("Self-test expected docs/features spec landing to fail");
+  }
+
+  console.log("DevFlow spec self-test passed");
+  console.log("Checked required section detection, vague spec blocking, and spec landing guidance");
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+if (args.includes("--self-test")) {
+  selfTest();
+  process.exit(0);
+}
+
+const targetArg = args.find((arg) => !arg.startsWith("-"));
+const body = readInput(args);
+process.exitCode = report(body, targetArg, args.includes("--json"));

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

@@ -0,0 +1,71 @@
+---
+name: devflow-adversarial
+description: "Use when a user explicitly asks for an independent deep adversarial review, upgraded adversarial review, red-team review, 对抗审查, 升级版对抗审查, or a five-angle challenge of current work. It can run at any task stage and does not read, require, modify, or hand off to devflow-prove, PUA, Build, Learn, or any completion state."
+---
+
+# DevFlow Adversarial Review
+
+Run an independent, user-requested challenge of the current task materials. This skill does not declare global task status or perform work beyond review.
+
+## Entry Gate
+
+1. Confirm the user explicitly requested this review.
+2. Immediately identify the review target from the user's request, current files, diff, requirements, tests, or supplied evidence.
+3. If the target is unclear, ask one smallest question to identify it.
+4. As an independent manual review, do not read, require, or alter `devflow-prove`, PUA, Build, Learn, or any lifecycle state.
+
+On DeepSeek Harness (DSH), run this review as a fresh `subagent` with no conversation seed so the challenge is genuinely independent of the main agent's reasoning; the subagent returns findings only and never declares lifecycle status, edits files, or invokes another skill.
+
+## Five-Angle Review
+
+Challenge the target from each angle:
+
+1. **Requirement coverage**: What stated requirement, constraint, or non-goal may be missing or contradicted?
+2. **Reachability**: Can the intended user, command, route, or runtime path actually reach the result?
+3. **Boundaries and regressions**: Which edge, sibling path, compatibility boundary, or affected surface may fail?
+4. **Evidence strength**: Which claim lacks direct evidence, uses stale output, or has inadequate verification?
+5. **User-visible outcome**: What would make the result technically plausible but still wrong, unclear, incomplete, or unusable for the user?
+
+Use facts from inspected material. Label unsupported possibilities as hypotheses, not facts.
+
+## Required Output
+
+```text
+Review confirmation: explicit request received
+Adversarial review target: <scope reviewed>
+Findings:
+- Critical: <finding or none>; evidence: <facts>; confidence: high/medium/low
+- Important: <finding or none>; evidence: <facts>; confidence: high/medium/low
+- Observation: <finding or none>; evidence: <facts>; confidence: high/medium/low
+Five-angle coverage:
+- Requirement coverage: <challenge and result>
+- Reachability: <challenge and result>
+- Boundaries and regressions: <challenge and result>
+- Evidence strength: <challenge and result>
+- User-visible outcome: <challenge and result>
+Context limitations: <unavailable material or none>
+Suggested next action: <manual action for the user, or none>
+```
+
+`Suggested next action` is advice only. Do not automatically edit files, create tasks, invoke another skill, or change lifecycle state.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|---|---|
+| "The task is already complete." | This skill is independent and may inspect any current task state. |
+| "The review is lengthy." | An explicit review request authorizes the review; do not add a second confirmation gate. |
+| "A likely issue is a fact." | Separate observed evidence from a hypothesis. |
+| "A Critical finding should trigger a fix." | Report it; the user decides whether to request follow-up work. |
+| "Another skill has a status." | Do not read or change that status. |
+
+## Verification
+
+Before leaving this skill, confirm:
+
+- [ ] The user explicitly requested adversarial review.
+- [ ] The review started without a second confirmation gate.
+- [ ] The review covers all five angles.
+- [ ] Findings have level, evidence, and confidence.
+- [ ] Context limitations are visible.
+- [ ] No lifecycle state, code, or other skill was changed or invoked.

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

@@ -0,0 +1,78 @@
+---
+name: devflow-audit
+description: "Use when auditing a repository or scope for overengineering, bloat, unnecessary abstraction, missed reuse, stdlib/native replacements, or asking what code can be deleted or simplified. Trigger phrases: 'audit this codebase', 'audit for over-engineering', 'what can I delete from this repo', 'find bloat', '/devflow-audit'."
+---
+
+# DevFlow Audit
+
+Audit code for unnecessary complexity across a repository or named scope.
+
+This is repo-wide `devflow-cut`, not correctness review and not implementation.
+
+## Process
+
+1. Define scope: whole repo, directory, file set, or user-provided focus.
+2. Read project rules and obvious ignore paths before scanning.
+3. Inspect files with `rg --files`, then read representative code in the chosen scope.
+4. Hunt for delete-list findings:
+   - `delete`: dead code, speculative feature, unused flexibility.
+   - `reuse`: duplicate code or helper that should use an existing project helper, utility, type, or pattern.
+   - `stdlib`: hand-rolled behavior the language standard library covers.
+   - `native`: dependency or custom code doing what the platform already does.
+   - `yagni`: abstraction, config, factory, wrapper, or layer with no current second use.
+   - `shrink`: same behavior with fewer moving parts.
+   - Hunt targets: stdlib/platform-shipped deps, single-implementation interfaces, factories with one product, wrappers that only delegate, files exporting one thing, dead flags and config, hand-rolled stdlib.
+5. Rank biggest useful cut first.
+6. Do not apply fixes unless the user explicitly asks for a follow-up implementation.
+
+When `scripts/devflow-audit.js` exists, use it as a first-pass candidate scan. The script output is evidence, not final judgment; confirm important findings by reading the referenced code.
+
+## Output
+
+One finding per line:
+
+```text
+<file>:L<line>: <delete|reuse|stdlib|native|yagni|shrink>: <what to cut>. <replacement>.
+```
+
+End with:
+
+```text
+net: -<N> lines, -<M> deps possible.
+```
+
+If nothing material should be cut:
+
+```text
+Lean already. Ship.
+```
+
+## Boundaries
+
+- Do not report correctness bugs, security issues, performance issues, or style preferences as audit findings.
+- Do not flag tests, small assertions, validation, accessibility, auth, permission, data-loss protection, or rollback safeguards as bloat.
+- Do not infer unused code only from one grep result when dynamic entry points or exports may exist; mark it as "candidate" or skip.
+- Do not change files during audit.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|---|---|
+| "The scanner found it, so it is removable." | The scanner only finds candidates. Read the code before reporting a real finding. |
+| "This abstraction looks big." | Size is not enough. Flag only avoidable complexity with a smaller current replacement. |
+| "This is a bug too." | Correctness, security, performance, and style belong to review or debugging, not audit. |
+| "I can just clean it up now." | Audit reports findings only. Fixes require a separate Build route. |
+
+## Handoff
+
+If the user wants fixes after the audit, hand off to `devflow-core -> devflow-brainstorm -> devflow-cut -> devflow-build -> devflow-prove` with selected findings as the design input.
+
+## Verification
+
+Before leaving this skill, confirm:
+
+- [ ] Scope was named.
+- [ ] Code was read or script output was confirmed with code reads.
+- [ ] Findings use the audit tags.
+- [ ] Boundaries were respected.
+- [ ] No files were changed.

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

@@ -0,0 +1,176 @@
+---
+name: devflow-brainstorm
+description: "You MUST use this before any creative work — creating features, building components, adding functionality, modifying behavior, or defining a problem-directed change. Explores user intent, requirements, problem boundaries, and design intent before implementation. Acts as a brainstorming partner: clarifies what the user wants through a semantic echo-back, examines the problem from multiple angles, surfaces gaps and risks, and recommends directions within the problem space; stops after a fixed Confirmed request summary and explicit A/B/C depth gate. Do NOT use it for pure Q&A, lookup, verification, or an already approved change; do NOT select a route or depth, produce implementation designs, or hand off except through the user-selected predefined direct branch."
+---
+
+# DevFlow Brainstorm
+
+Explore **what** the user wants as a true brainstorming partner. Do not decide **how** DevFlow should proceed or **how** the solution should be built. Liveliness comes from depth of thinking — proactive analysis, gap-finding, and recommendations — never from loosening the process discipline.
+
+## Responsibility Boundary
+
+This skill owns only:
+
+- minimal fact reading needed to understand the request;
+- Semantic Echo-Back and understanding correction;
+- mandatory multi-angle problem exploration: surfacing gaps, risks, blind spots, and unstated assumptions in the user's request;
+- ideas, suggestions, and direction recommendations inside the problem space;
+- one-at-a-time clarification of goal, scope, exclusions, constraints, acceptance, and real open questions;
+- the fixed `Confirmed request` summary.
+- an explicit A/B/C depth gate after the summary, followed only by the user-selected direct branch.
+
+Use `references/interview-discipline.md` for the Semantic Echo-Back, multi-angle checklist, recommendation boundary, one-question discipline, and fixed-summary forms.
+
+`devflow-core` owns routing for missing depth, exceptions, and non-unique artifacts. `devflow-spec` owns solution-space design contracts. `devflow-cut`, `devflow-plan`, `devflow-build`, `devflow-prove`, `devflow-pua`, and `devflow-docs-followup` retain their own responsibilities.
+
+## Entry And Stop Condition
+
+Enter only when `devflow-core` has identified a requirement, behavior, architecture, or ambiguity that needs clarification.
+
+After producing the fixed summary, present the A/B/C gate and wait for user selection. Start A at `devflow-spec` and B/C at `devflow-cut` only after the user chooses. Do not select Fast, Design-lite, a depth, an approach, or a method on the user's behalf. Do not create design sections, a design contract, documentation, or a visual artifact.
+
+## Clarification Depth
+
+Depth governs **analysis breadth only**. It never skips the echo-back, the confirm gates, the question discipline, or the recommendation duty.
+
+| Tier | Use when | Behavior |
+|---|---|---|
+| `deep` (default) | Every request, unless the user explicitly asks for a lighter pass. | Full multi-angle checklist with a per-angle report, gap/risk surfacing, direction options with trade-offs, and a recommendation. |
+| `standard` | Only on explicit user request for a lighter pass. | Run the fitting angles instead of the full checklist; every other duty unchanged. |
+
+There is no fast lane. A request that turns out clear after analysis simply ends with fewer questions — the analysis still ran and its findings still reach the summary.
+
+## Clarification Process
+
+1. **Read facts first.** Inspect the smallest useful project files, documentation, configuration, tests, and existing behavior. State facts instead of asking questions that those facts answer.
+2. **Semantic Echo-Back.** The first user-facing message confirms the current understanding and ends with one explicit confirm-or-correct question. Include all fields below, even when a field is `none`.
+
+   ```text
+   My understanding:
+   - Problem to solve: <one sentence in the user's language>
+   - Known facts/constraints: <facts read, or none>
+   - NOT what you want: <likely misreading ruled out, or none>
+   - My assumptions (that could be wrong): <inferences, or none>
+   - Understanding gaps: <specific ambiguity, or none>
+   Is this right? (correct me / confirm)
+   ```
+
+3. **Wait.** Do not ask a process question or make a lifecycle decision before the user confirms or corrects the echo-back.
+4. **Clarify one decision-impact gap at a time.** Ask only the smallest unresolved question whose answer could change scope, a constraint, acceptance, or a subsequent problem-space decision. Resolve qualifying gaps in this order: goal ambiguity, scope boundary, exclusion, constraint, acceptance, then any remaining open question. Do not ask merely because a category is unfilled: record a fact-backed `none` or non-blocking unknown instead. Every question carries a recommended answer and why the answer matters.
+
+   ```text
+   Question: <one question>
+   Recommended answer: <answer and rationale>
+   Why now: <risk or dependency resolved>
+   ```
+
+5. **Revalidate every answer.** Before asking the next question, compare the answer with confirmed facts and the current request. If it introduces a load-bearing assumption, exposes a contradiction, or changes goal, scope, exclusion, constraint, acceptance, terminology, or actor, apply the Understanding Revision Rule. Otherwise record the answer and continue only when another decision-impact gap remains.
+6. **Explore the problem.** Walk the multi-angle checklist from the reference and report what each angle found, including "nothing found here". Name gaps, risks, and blind spots in the user's request; offer directions with trade-offs and recommend one inside the problem space. If exploration exposes a new decision-impact gap, return to step 4 and resolve it one question at a time before finishing.
+7. **Finish.** When no decision-impact gap remains and every non-blocking unknown is recorded, output the fixed summary, present the A/B/C gate, and wait. On user selection, follow only the corresponding predefined direct branch.
+
+## Problem-Space Recommendation
+
+Brainstorming is active, not passive recording. Inside the problem space this skill must:
+
+- point out gaps, contradictions, risks, and missing stakeholders in the request;
+- lay out directions the user has not considered, with trade-offs;
+- recommend a direction and explain why;
+- record considered-and-rejected directions with their reasons.
+
+Stop line: when the discussion turns to **how to build** — technical selection, structure, contracts, or steps — record the need and hand it to `devflow-spec` through the summary. Test: a statement answering "what to do / why / what not to do / what could go wrong" belongs here; a statement answering "how to implement" belongs to spec.
+
+Brainstorm suggestions are disposable conversation material that helps the user decide what they want; a spec design contract commits to how it gets built.
+
+## Understanding Revision Rule
+
+A user correction is not permission to continue from the previous question chain. If the correction changes the goal, scope, exclusion, constraint, acceptance, terminology, actor, or any assumption that affects the request:
+
+1. stop the current clarification question;
+2. replace superseded facts and assumptions with the corrected understanding;
+3. send a complete updated Semantic Echo-Back, including any new gaps;
+4. wait for explicit confirmation or another correction; and
+5. only then resume one-at-a-time clarification or produce `Confirmed request`.
+
+A correction that changes nothing above may receive a direct one-line acknowledgement, but it must not be treated as a confirmed request. Do not silently merge a correction into the next question or the fixed summary.
+
+## Clarification Rules
+
+- One user question per message; wait for the answer before the next question.
+- Treat business intent, user-visible scope, and ambiguous terms as questions; do not infer them from code.
+- Ask no question whose answer is unambiguous in project facts.
+- Match the user's language and terminology. Name a new technical term only when precision needs it.
+- For vague quantifiers, implicit scope, pronouns, missing actors, unstated constraints, solution-as-goal language, missing context, and ambiguous boundaries, name the specific ambiguity in the echo-back or next question.
+- A request already clear after the echo-back needs no additional questions; the multi-angle exploration still runs and its findings still reach the summary.
+- Required formats (echo-back fields, question block, fixed summary) are mandatory. Wording inside them may be natural and conversational; the structures may not be skipped or abbreviated.
+
+## Fixed Output Contract
+
+```text
+Confirmed request:
+- Goal: <user outcome>
+- Scope: <included behavior and surfaces>
+- Out of scope: <explicit exclusions>
+- Constraints: <must-not-change conditions, or none>
+- Acceptance: <observable proof of success>
+- Identified gaps/risks: <holes, risks, and blind spots surfaced during exploration, or none>
+- Directions considered: <directions discussed with trade-offs, including rejected ones, or none>
+- Recommended direction: <recommendation and rationale within the problem space, or none>
+- Open questions: <none or unresolved blocker>
+- Status: clarified
+```
+
+The summary records the agreed request and the exploration findings only. It must not contain an implementation plan, solution-space design, lifecycle route, or handoff instruction. It is the factual basis that downstream skills — starting with `devflow-spec` — build on, so record findings faithfully rather than trimming them away.
+
+## A/B/C Gate
+
+After the fixed summary, present these choices and wait for one explicit user selection:
+
+On DeepSeek Harness (DSH), present the gate through the structured `ask_user_question` tool as one single-select question with options A / B / C.
+
+| Depth | User-selected outcome | Direct start after selection |
+|---|---|---|
+| A | Full design contract and implementation plan | `devflow-spec` |
+| B | Implementation plan without a saved Spec | `devflow-cut` |
+| C | Smallest approved change without a Plan Pack | `devflow-cut` |
+
+Record `Depth: A`, `Depth: B`, or `Depth: C` with the selected branch input. Do not infer depth from request size. A missing or changed selection returns the relevant facts to `devflow-core`.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|---|---|
+| "The request is obvious, so skip the echo-back." | Hidden assumptions cause changed-wrong work. Echo the understanding first. |
+| "The request looks simple, so skip the analysis." | Simple-looking requests hide the most assumptions. Walk the checklist; reporting "nothing found" is cheap. |
+| "I can choose the depth while clarifying." | Recommendations stop at the problem space. The user selects A/B/C; the selected branch starts directly. |
+| "Several questions save time." | One question at a time makes the answer unambiguous. |
+| "Code reveals business intent." | Code shows current behavior, not the desired outcome. Confirm intent. |
+| "A design contract is a better summary." | A design contract decides how; this skill records what plus exploration findings. |
+| "The user corrected one detail, so continue silently." | Re-echo the corrected understanding before proceeding. |
+| "Formats are optional when the conversation flows." | Optional formats are skipped formats. The structures are mandatory; only the wording is free. |
+| "Recommending a direction is route selection." | Problem-space recommendation is this skill's duty; lifecycle routing is Core's. |
+| "A recovery restart means I own recovery." | Recovery remains in `devflow-pua`; perform only the normal clarification process. |
+
+## Red Flags — Stop
+
+- Selecting a depth or branch on the user's behalf.
+- Recommending implementation approaches, technical selections, or producing solution-space design.
+- Creating a design contract, spec, plan, ADR, documentation landing, or visual expression.
+- Skipping or abbreviating the multi-angle exploration because the request looks simple.
+- Treating clarification depth as permission to skip the echo-back, a confirm gate, or the recommendation duty.
+- Combining several user questions into one message.
+- Starting a branch before the user selects A/B/C.
+
+## Verification
+
+Before leaving this skill, confirm:
+
+- [ ] Relevant facts were read or explicitly recorded as unknown.
+- [ ] The first user-facing message was a Semantic Echo-Back with all fields, including `none` entries.
+- [ ] The echo-back was confirmed or corrected before further clarification.
+- [ ] Each additional question resolved one real gap and used the `Question / Recommended answer / Why now` block.
+- [ ] The multi-angle exploration ran and its per-angle findings reached the summary fields.
+- [ ] Recommendations stayed inside the problem space.
+- [ ] Any changed understanding was re-echoed and confirmed.
+- [ ] The fixed `Confirmed request` summary contains every required field, including gaps/risks, directions, and recommendation.
+- [ ] The summary contains no implementation design or user-unselected branch.
+- [ ] A/B/C was presented after `Status: clarified`, and only the user-selected branch started.