@paradigma-inc/flywheel 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [

package/skills/flywheel-lookahead/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flywheel-lookahead
-description: Stage next-step frontier nodes from existing Flywheel graph state with Flywheel MCP up to depth `n` and width `k` without execution or compute acquisition. Use for planning what to do next, not claim validation, source-to-graph authoring, or autonomous execution.
+description: Stage a single-path next-step frontier from existing Flywheel graph state with Flywheel MCP using lookahead depth `n` and per-hop option width `k`, without execution or compute acquisition. Use for planning what to do next, not claim validation, source-to-graph authoring, or autonomous execution.
 ---
 
 # flywheel-lookahead
@@ -15,14 +15,14 @@ If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool
 
 Before planning, recover or establish these inputs:
 
-- Required before planning: start nodes, objective, lookahead depth `n`, frontier width `k`, and an explicit terminal condition.
+- Required before planning: start nodes, objective, lookahead depth `n`, step option width `k`, and an explicit terminal condition.
 - Optional: budget ceiling and budget unit, but only when the user already supplied them or wants them tracked for later execution.
-- Defaults: `lookahead_depth` defaults to `n=1`; `frontier_width` defaults to `k=1`.
+- Defaults: `lookahead_depth` defaults to `n=1`; `step_option_width` defaults to `k=1`.
 - Recovery rules:
   - Ask only when a required planning input cannot be recovered from explicit user instructions, current conversational context, or recent graph state.
   - If start nodes cannot be recovered from explicit ids/slugs, named current context, or recent graph context, ask once.
   - If the objective is missing, ask once; if the user refuses, infer it from graph context and persist it before planning.
-  - If the terminal condition is missing, ask once; if it remains unspecified, persist a planning-local terminal condition such as stopping after staging this lookahead pass through the requested `n` hops and `k` branches.
+  - If the terminal condition is missing, ask once; if it remains unspecified, persist a planning-local terminal condition such as stopping after staging this lookahead pass through the requested `n` hops with at most `k` considered options per hop and one selected continuation per hop.
 
 ## Working Terms
 
@@ -31,6 +31,19 @@ Before planning, recover or establish these inputs:
 - `control node`: the dedicated `insight` node that stores the canonical planning contract for the current frontier.
 - `terminal condition`: the explicit condition that tells this planning pass when to stop staging additional frontier nodes.
 - `expected_revision`: the node's current revision token used for optimistic-locking writes.
+- `lookahead depth (n)`: the number of sequential hops in one planned path.
+- `step option width (k)`: the number of candidate directions evaluated at each hop before choosing one continuation.
+
+## Width Semantics (Unambiguous)
+
+- Lookahead depth `n`: number of sequential hops in one plan path.
+- Step option width `k`: number of candidate directions to evaluate at each hop.
+- Expansion rule: at hop `i`, generate up to `k` non-redundant options, select exactly 1 winner, and only that winner continues to hop `i+1`.
+- Graph shape for this mode: a single chain of `n` staged nodes (not `k` parallel branches).
+- Each step node must record:
+  - the `k` considered options,
+  - the selection criterion,
+  - the chosen continuation.
 
 ## Core Rules
 
@@ -51,7 +64,7 @@ Before planning, recover or establish these inputs:
    - The flywheel-lookahead skill requires a measurable objective. Ask once if it is missing; if the user refuses to specify one, infer it from the available graph context and state it explicitly before continuing.
    - Default `n=1` and `k=1` unless the user specified otherwise.
    - Persist the planning contract in a dedicated `insight` control node for this frontier. Put the canonical contract in node `content`, keep a one-line synopsis in `summary`, and keep brief planning rationale in `insights` so the commit contract stays valid.
-   - The control contract must name: objective, decision criterion, start nodes, lookahead depth `n`, frontier width `k`, and an explicit terminal condition. Only persist a budget ceiling and unit when the user already supplied one or wants them tracked for later execution.
+   - The control contract must name: objective, decision criterion, start nodes, lookahead depth `n`, step option width `k`, and an explicit terminal condition. Only persist a budget ceiling and unit when the user already supplied one or wants them tracked for later execution.
    - Later lookahead passes must read the control node `content` first and continue from that persisted contract rather than from chat memory.
 3. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
@@ -69,12 +82,14 @@ Before planning, recover or establish these inputs:
 6. Add graph structure sparingly.
    - Promote only decision-relevant relationships to edges.
    - Leave ordinary cross-links inside the markdown body.
-7. Expand the frontier deliberately.
+7. Expand the frontier as a single selected path.
    - Expand from the resolved frontier rather than mirroring the source corpus again.
-   - Depth `n` means plan `n` hops ahead from the currently resolved frontier. Default `n=1`.
-   - Width `k` means plan up to `k` distinct non-redundant frontier directions. Default `k=1`.
-   - Avoid redundant siblings that only restate the same branch with different wording.
-   - Keep unresolved plan nodes staged until the corresponding work is resolved.
+   - Depth `n` means plan `n` sequential hops ahead from the currently resolved frontier. Default `n=1`.
+   - Width `k` means evaluate up to `k` distinct non-redundant candidate directions at each hop. Default `k=1`.
+   - At each hop, stage the considered options in the step record, apply the selection criterion, and choose exactly one continuation.
+   - Only the chosen continuation advances to hop `i+1`; do not stage `k` parallel continuation branches for this mode.
+   - The staged graph shape for this mode is a single chain of up to `n` unresolved step nodes (shorter only when the terminal condition is met early).
+   - Each step node must record: the `k` considered options, the selection criterion used, and the chosen continuation.
 8. Commit after the node snapshot is coherent with `flywheel_commit_node`.
    - Commit resolved insight nodes only when they have non-empty `insights`.
    - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
@@ -85,7 +100,7 @@ Before planning, recover or establish these inputs:
 When the skill completes a pass, it should leave behind:
 
 - One persisted `insight` control node containing the canonical planning contract.
-- Zero or more staged next-step frontier nodes up to the current `n` and `k` limits.
+- A single staged next-step chain up to the current `n` limit where each hop records up to `k` considered options and one selected continuation.
 - Updated node summaries, rationale, and edges only where the current planning pass justifies them.
 - No hidden execution, no compute approval, and no managed compute acquisition.
 
@@ -114,7 +129,7 @@ Canonical contract shape:
 - Decision criterion:
 - Start nodes:
 - Lookahead depth:
-- Frontier width:
+- Step option width:
 - Terminal condition:
 - Budget ceiling: optional
 - Budget unit: optional

package/skills/flywheel-lookahead/evals/evals.json

@@ -13,8 +13,8 @@
   },
   {
     "id": "planning-only-with-explicit-depth-and-width",
-    "prompt": "Use $flywheel-lookahead to stage two hops of next-step work across three non-redundant branches from the current Flywheel frontier. Plan only for later work and do not execute anything.",
-    "expected_output": "Persist `n=2` and `k=3` in the planning contract, stage non-redundant frontier nodes up to those limits, and avoid compute approval, managed compute acquisition, or execution launch.",
+    "prompt": "Use $flywheel-lookahead to stage two sequential hops of next-step work while evaluating up to three non-redundant options at each hop from the current Flywheel frontier. Plan only for later work and do not execute anything.",
+    "expected_output": "Persist `n=2` and `k=3` in the planning contract, evaluate up to three non-redundant options at each hop, record the considered options plus selection criterion plus chosen continuation for each step node, continue only along the single chosen path, and avoid compute approval, managed compute acquisition, or execution launch.",
     "files": []
   }
 ]