@widnyana/design-thinking 0.0.1 → 0.0.5

package/README.md

@@ -1,3 +1,4 @@
+
 # design-thinking — a pi package
 
 AI coding agents ship code before asking what breaks. This extension flips the
@@ -12,12 +13,35 @@ gist](https://gist.github.com/r17x/90eb2f7be93932b5693753aedb09c01a),
 originally Effect-TS), generalized into this stack-agnostic pi package.
 Licensed MIT — see [LICENSE](LICENSE).
 
+## Why
+
+A prose plan doesn't survive contact with review. An agent proposes "add
+rate limiting, handle errors," the plan reads fine, and the diff either
+matches it or it doesn't — prose gives no way to check which. Two failure
+modes follow from that: the agent picks an unstated failure path (swallow
+the error, retry silently, drop the request) nobody agreed to, or the
+reviewer approves a plan that was never specific enough to catch the
+mismatch once the code lands.
+
+Design Graph replaces the prose plan with something that can be diffed.
+Nodes are functions, edges are data and error/escape paths, boundaries are
+named — fixed before code exists. `/cg-review` then reconstructs the graph
+the code actually implements and diffs it against the one that was planned,
+finding by finding, ending in a VERDICT. The notation is the same shape in
+Go, Rust, Python, or TypeScript, so the check doesn't depend on the stack.
+
+Skip it for a one-line fix — prose is fine there. Reach for `/dt` when the
+change has a failure path worth agreeing on before it's written.
+
 ## Install
 
 ```bash
 # from npm
 pi install npm:@widnyana/design-thinking
 
+# via OMP
+omp install npm:@widnyana/design-thinking
+
 # pinned version
 pi install npm:@widnyana/design-thinking@0.0.1
 

package/extensions/design-thinking.ts

@@ -61,28 +61,50 @@ Pipeline: shapes → graph(A) → cardinality → E(⟳retry ↯escape ☠die)
 🔒 parse at boundaries → ⛈ orthogonal behavior → scope → test-R → verdict.
 
 Rules:
-- Design, plan, and review answers must render a Design Graph in Graph Protocol
-  form — fixed sections: PROBLEM, SHAPES, GRAPH, CARDINALITY, BOUNDARIES,
-  BEHAVIOR, SCOPE, TEST LAYERS, VERDICT.
+- ANY turn that will end in code or file edits (feature, change, fix,
+  refactor — the model does NOT get to reclassify the request): render the
+  Design Graph in Graph Protocol form and any clarifying questions FIRST;
+  ZERO file edits until the user approves the design. Reading/exploring code
+  first is fine; the FIRST edit is not allowed before the graph.
+- Design, plan, and review answers must render a Design Graph — fixed
+  sections: PROBLEM, SHAPES, GRAPH, CARDINALITY, BOUNDARIES, BEHAVIOR, SCOPE,
+  TEST LAYERS, VERDICT.
 - The happy path (A) stays readable; failure handling lives at defined join points.
 - Each layer scopes its own E; inner errors never leak through.
 - If the code doesn't match the call graph, the implementation is wrong.
-- For build/fix/refactor tasks: present the Design Graph and any clarifying
-  questions FIRST; implement only after the user approves the design.
 - Adapt vocabulary to the current language/stack; never the discipline.
 
 Full specs — read these when a section needs detail:
 - ${REF_DIR}/protocol.md      (Graph Protocol: notation spec + worked example)
 - ${REF_DIR}/method.md        (the §1–§10 method, generalized)
 - ${REF_DIR}/design-graph.md  (the artifact spec + completeness checklist)
+Skills load BY NAME into the agent (/skill:<name>); the files above are named
+by stem, NOT by skill name. Exact mapping:
+  /skill:graph-protocol → protocol.md   /skill:design-method → method.md
+  /skill:design-graph → design-graph.md
+  Zero file edits are possible until the user runs /dt approve for the turn —
+  the extension blocks write/edit tools mechanically. Present the graph first.
+NEVER read references/<skill-name>.md — no such files exist.
 `.trim();
 
+const MUTATING_TOOLS: Record<string, true> = {
+	write: true,
+	edit: true,
+	apply_patch: true,
+	multiedit: true,
+};
+
 interface DtState {
 	enabled: boolean;
 }
 
+const GATE_REASON =
+	"Design Thinking mode is ON: present the Design Graph (Graph Protocol) and wait for user approval before file edits. The user can unlock this turn with /dt approve.";
+
 export default function designThinkingExtension(pi: ExtensionAPI) {
 	let enabled = false;
+	// Per-turn approval flag: set by /dt approve, reset on every user turn.
+	let approvedForTurn = false;
 
 	function applyStatus(ctx: ExtensionContext) {
 		ctx.ui.setStatus(
@@ -123,13 +145,27 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 
 	// /dt — the Design Thinking tool. Toggles mode, or /dt on|off|status.
 	pi.registerCommand("dt", {
-		description: "Design Thinking mode: /dt toggles, on|off|status set/query, anything else runs as a prompt with mode on",
+		description: "Design Thinking mode: /dt toggles, on|off|status set/query, approve|deny unlock/lock file edits for this turn, anything else runs as a prompt with mode on",
 		handler: async (args, ctx) => {
 			const arg = (args ?? "").trim();
 			const lower = arg.toLowerCase();
 
 			if (lower === "status") {
-				ctx.ui.notify(`Design Thinking mode: ${enabled ? "on" : "off"}`, "info");
+				ctx.ui.notify(`Design Thinking mode: ${enabled ? "on" : "off"}${approvedForTurn ? " (edits approved for this turn)" : ""}`, "info");
+				return;
+			}
+
+			// /dt approve|deny — explicit user unlock/lock for the CURRENT turn.
+			if (lower === "approve") {
+				approvedForTurn = enabled;
+				ctx.ui.notify(
+					enabled ? "Design Thinking: file edits approved for this turn" : "Design Thinking is OFF — nothing to approve",
+					"info",
+				);
+			}
+			if (lower === "deny") {
+				approvedForTurn = false;
+				ctx.ui.notify("Design Thinking: file edits blocked again", "info");
 				return;
 			}
 
@@ -137,6 +173,7 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 			// mode and always turns the mode ON (never toggles it off); bare /dt toggles.
 			const prompt = /^(on|off|status)$/.test(lower) ? "" : arg;
 			enabled = lower === "on" || prompt ? true : lower === "off" ? false : !enabled;
+			if (!enabled) approvedForTurn = false;
 			persist();
 			applyStatus(ctx);
 			ctx.ui.notify(
@@ -158,9 +195,21 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 
 	// While active, append the distilled block to the system prompt every turn.
 	pi.on("before_agent_start", async (event) => {
+		// A new user turn starts a fresh agent run: the approval from the
+		// previous turn does not carry over.
+		approvedForTurn = false;
 		if (!enabled) return undefined;
 		return {
 			systemPrompt: event.systemPrompt + "\n\n" + DISTILLED + "\n",
 		};
 	});
+
+	// Hard gate: while enabled, mutating tools are blocked until the user
+	// approves the design for this turn (/dt approve). Prompt-level rules
+	// alone proved insufficient — this is the mechanical backstop.
+	pi.on("tool_call", async (event) => {
+		if (!enabled || approvedForTurn) return undefined;
+		if (!MUTATING_TOOLS[event.toolName]) return undefined;
+		return { block: true, reason: GATE_REASON };
+	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@widnyana/design-thinking",
-  "version": "0.0.1",
+  "version": "0.0.5",
   "type": "module",
   "description": "Design Thinking · Design Graph · Graph Protocol — a stack-agnostic design methodology for pi. Turns every plan, review, and refactor into an annotated call graph. Method originally by r17x; generalized to a pi package by widnyana.",
   "author": {
@@ -35,8 +35,11 @@
     "methodology",
     "call-graph"
   ],
+  "omp": {
+    "extensions": ["./extensions/design-thinking.ts"]
+  },
   "pi": {
-    "extensions": ["./extensions"],
+    "extensions": ["./extensions/design-thinking.ts"],
     "prompts": ["./prompts"],
     "skills": ["./skills"]
   },

package/references/design-graph.md

@@ -13,6 +13,9 @@ A Design Graph is not documentation written after the fact. It is drawn
 **before** implementation (planning), **reconstructed** from implementation
 (review), and **compared** against implementation (verdict). The graph is the
 contract; the code is one instantiation of it.
+**Hard gate:** when a turn will produce code or file edits, the graph comes
+first — render it (and any clarifying questions), get the user's approval,
+and only then write code that matches it.
 
 ---
 

package/references/method.md

@@ -8,6 +8,13 @@ The method is language-neutral. Where it says "Effect", "gen", or "pipe" in the
 Effect-TS appendix (`effect-ts.md`), substitute your stack's equivalent: Result
 types, exceptions at layer joins, middleware, RAII, constructor injection —
 whatever your language provides. The discipline never changes, only the vocabulary.
+**Hard gate — applies in every harness (pi, omp, Claude Code, any agent):**
+When the user asks for a feature, change, fix, or refactor — or when any turn
+will end in proposed code or file edits — you MUST render the Design Graph
+(Graph Protocol) and any clarifying questions BEFORE touching any file, and
+implement only after the user approves the design. Reading and exploring code
+first is fine; the FIRST edit is not allowed before the graph. This rule is
+not optional and not stack-dependent.
 
 Render every result in [Graph Protocol](protocol.md) format.
 

package/skills/design-graph/SKILL.md

@@ -11,8 +11,8 @@ description: >
 # Design Graph — The Artifact
 
 A **Design Graph** is the annotated call graph of a concrete problem. It is
-what you produce when you apply [Design Thinking](/skill:design-method) to
-something, and it is written in [Graph Protocol](/skill:graph-protocol) notation.
+what you produce when you apply Design Thinking (see the `design-method` skill) to
+something, and it is written in Graph Protocol notation (see the `graph-protocol` skill).
 
 Nodes are functions. Edges are data flow. The annotations answer, for every
 node: what flows through it (A), how many times it runs (cardinality), where
@@ -23,6 +23,9 @@ A Design Graph is not documentation written after the fact. It is drawn
 **before** implementation (planning), **reconstructed** from implementation
 (review), and **compared** against implementation (verdict). The graph is the
 contract; the code is one instantiation of it.
+**Hard gate:** when a turn will produce code or file edits, the graph comes
+first — render it (and any clarifying questions), get the user's approval,
+and only then write code that matches it.
 
 ---
 
@@ -94,5 +97,5 @@ VERDICT line.
 
 ## Worked example
 
-See the end of [Graph Protocol](/skill:graph-protocol) for a complete, non-TS worked
+See the end of the `graph-protocol` skill for a complete, non-TS worked
 example (a resumable URL-sync CLI in Python) with all sections filled.

package/skills/design-method/SKILL.md

@@ -17,8 +17,15 @@ The method is language-neutral. Where it says "Effect", "gen", or "pipe" in the
 Effect-TS appendix (`effect-ts.md`), substitute your stack's equivalent: Result
 types, exceptions at layer joins, middleware, RAII, constructor injection —
 whatever your language provides. The discipline never changes, only the vocabulary.
-
-Render every result in [Graph Protocol](/skill:graph-protocol) format.
+**Hard gate — applies in every harness (pi, omp, Claude Code, any agent):**
+When the user asks for a feature, change, fix, or refactor — or when any turn
+will end in proposed code or file edits — you MUST render the Design Graph
+(Graph Protocol) and any clarifying questions BEFORE touching any file, and
+implement only after the user approves the design. Reading and exploring code
+first is fine; the FIRST edit is not allowed before the graph. This rule is
+not optional and not stack-dependent.
+
+Render every result in Graph Protocol format (see the `graph-protocol` skill).
 
 ```
 X → DesignGraph<A, E, R>