@hassangameryt/freeflow 0.3.0 → 0.5.0

package/capabilities/output-router/references/setup.md

@@ -0,0 +1,110 @@
+# Output Router Setup
+
+Use this only when repository setup or repair explicitly includes Output Router, observed routing, generated-path hints, native safety-net routing, vault, thresholds, script-transform adapters, or script-transform repository config.
+
+## Defaults
+
+- Minimal `/setup-freeflow` writes only repository `defaultMode`. `.freeflow/config.json` remains required for activation; a local override cannot activate Freeflow.
+- Output Router is repository-owned and disabled by default.
+- Missing optional sections mean built-in defaults, not setup failure.
+- Normal setup does not ask a generic capability question. If Output Router was not explicitly requested, do not write `outputRouter` config or install script adapters.
+- If the user explicitly opts into Output Router during setup, write `outputRouter.enabled: true` directly. Do not make them run another command afterward.
+- Observed routing is opt-in per producer/server. The user must choose persistence for each enabled entry before setup writes config.
+- Preserve unrelated valid repository and personal settings. Do not copy Output Router config into `.freeflow/local.json`; only documented local-only processing settings belong there.
+- Do not create a separate `setup-output-router` skill.
+
+If the user says only “set up the output router” with no requested knobs, explain that enabling Output Router is enough for the router tools/guidance, then ask which optional subfeatures, if any, they want persisted. Recommend no subfeature config unless they need observed routing, repo-specific hints, script transform setup, or native safety-net behavior.
+
+## Config Shape
+
+Write only keys the user explicitly requests. Do not dump defaults and do not create empty optional objects. Output-router-related config lives under `outputRouter`. Do not write removed `capture` or `providers` config.
+
+Supported shape:
+
+```json
+{
+  "defaultMode": "workflow",
+  "outputRouter": {
+    "enabled": true,
+    "postToolRouting": "safety-net",
+    "thresholds": {
+      "largeOutputBytes": 64000,
+      "largeOutputLines": 2000
+    },
+    "vault": {
+      "root": "~/.cache/freeflow-router/vault",
+      "retention": { "strategy": "ttl", "ttlDays": 7 }
+    },
+    "hints": {
+      "generatedPathGlobs": ["graphify-out/**"],
+      "noisyCommandPatterns": ["npm test"]
+    },
+    "observedRouting": {
+      "enabled": true,
+      "onRoutingFailure": "fail-open",
+      "mcp": {
+        "servers": {
+          "github": { "enabled": true, "persistence": "exact" },
+          "gmail": { "enabled": true, "persistence": "metadata-only" }
+        }
+      },
+      "web": { "enabled": true, "persistence": "exact" },
+      "fetch": { "enabled": true, "persistence": "exact" },
+      "codeSearch": { "enabled": true, "persistence": "exact" }
+    },
+    "scriptTransform": {
+      "enabled": true,
+      "sandbox": "auto",
+      "languages": ["javascript", "python", "jq"],
+      "network": "off",
+      "limits": {
+        "timeoutMs": 5000,
+        "maxInputBytes": 1048576,
+        "maxOutputBytes": 65536
+      },
+      "rawScriptPersistence": "disabled"
+    }
+  }
+}
+```
+
+Rules:
+
+- Top-level `enabled` and `skills.enabled` default to true after setup; write them only when the user explicitly wants to disable Freeflow or the skills layer.
+- `outputRouter.enabled` defaults to `false`; write `true` only when the user chooses Output Router.
+- `postToolRouting` defaults to `off`. Do not write `off`; use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
+- `thresholds.largeOutputBytes`, `thresholds.largeOutputLines`, and `vault.retention.ttlDays` must be positive integers.
+- `vault.root` must be a non-empty string. Repo-local storage requires explicit user choice.
+- `hints.generatedPathGlobs` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
+- `hints.noisyCommandPatterns` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
+- `observedRouting.enabled` defaults to `false`; write it only when the user chooses observed routing.
+- `observedRouting.onRoutingFailure` currently supports `fail-open`; omit it unless a caller needs an explicit non-default once supported.
+- `observedRouting.mcp.servers` must contain explicit server entries only. Setup may discover configured servers for selection, but must not persist a volatile inventory of every installed tool.
+- `observedRouting.web`, `observedRouting.fetch`, and `observedRouting.codeSearch` are Pi observed-routing producers. Enable only the producers the user chose.
+- Every enabled observed-routing entry needs a user-chosen persistence mode: `exact`, `metadata-only`, or `none`.
+- Recommend `exact` for public-ish evidence producers such as GitHub, web, fetch, and code search. Recommend `metadata-only` for sensitive or unknown producers such as Gmail, Slack, private customer systems, or likely-secret outputs.
+- Do not offer or write `redacted`; it is reserved for future work and currently falls back to `metadata-only` with a warning if hand-edited.
+- Pi public `freeflow_capture` and the separate `providers` setup surface have been removed. Do not write removed `capture` or `providers` config.
+- `scriptTransform.enabled` defaults to `false`; write `true` only after an explicit script-execution opt-in.
+- If the user opts into script transform setup and adapters are missing or unavailable, recommend installing global adapters. On consent, run `node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json`.
+- The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs `quickjs-wasi@3.0.1`, `jq-wasm@1.2.0-jq-1.8.2`, `@bsull/eryx@0.5.0`, and `node@24` for the Python JSPI child runner, writes `freeflow-adapter-env.sh`, probes sandbox proofs, and updates `outputRouter.scriptTransform.languages` with only proof-passing languages.
+- Freeflow auto-discovers adapters from that global cache. The explicit roots `FREEFLOW_QUICKJS_WASI_ROOT`, `FREEFLOW_JQ_WASM_ROOT`, and `FREEFLOW_ERYX_ROOT` remain overrides for custom installs.
+- Python/Eryx is installed by setup and uses the setup-installed child Node process launched with `--experimental-wasm-jspi` when the host process lacks JSPI. It must not be marked available unless that child runner passes the required sandbox probes.
+- `scriptTransform.languages` supports `javascript`, `python`, and `jq`; enable only languages whose adapters passed sandbox proofs.
+- `scriptTransform.sandbox` currently supports `auto`, `network` supports only `off`, and `rawScriptPersistence` supports only `disabled`.
+- `scriptTransform.limits.timeoutMs`, `maxInputBytes`, and `maxOutputBytes` must be positive integers within product caps. Per-call script limits may only tighten configured values.
+
+## Verify
+
+After writing optional capability config, use `freeflow_status` or equivalent direct inspection to verify:
+
+- JSON parses.
+- `defaultMode` is valid.
+- A minimal shared setup with no optional settings contains only `defaultMode`.
+- Newly added `enabled`, `interactionContract`, `skills.enabled`, `outputRouter`, `outputRouter.observedRouting`, and `outputRouter.scriptTransform` keys were requested; preserved valid settings remain unchanged.
+- Invalid router, observed-routing, or script-transform values are not written.
+- Output Router, observed routing, native safety-net routing, and script transform are not enabled unless explicitly requested.
+- If script transform setup was accepted, global adapter install completed or a clear install/probe failure was reported, and enabled languages match proof-passing adapters.
+- No observed-routing entry uses `redacted`, and every enabled entry has explicit persistence.
+- `freeflow_status` shows effective defaults and migration recommendations without rewriting config.
+- No repo-local hooks, skill files, setup-output-router skill, docs inventories, or repo-local storage directories were created.

package/command-surface.json

@@ -1,27 +1,48 @@
 {
   "nativeSlashHandlers": false,
+  "hostNativeSkillInvocation": {
+    "claude": "namespaced-slash-skill",
+    "codex": "skill-mention",
+    "pi": "registered-command"
+  },
+  "sessionModeControls": {
+    "claude": "/freeflow:mode-contract <mode|reset>",
+    "codex": "$mode-contract <mode|reset>",
+    "pi": "/freeflow mode <mode|reset>",
+    "naturalLanguage": true
+  },
   "modeCommands": [
     {
-      "command": "/workflow conversation",
+      "command": "/freeflow mode conversation",
       "routesTo": "mode-contract"
     },
     {
-      "command": "/workflow workflow",
+      "command": "/freeflow mode workflow",
       "routesTo": "mode-contract"
     },
     {
-      "command": "/workflow strict-workflow",
+      "command": "/freeflow mode strict-workflow",
       "routesTo": "mode-contract"
     },
     {
-      "command": "/workflow reset",
+      "command": "/freeflow mode reset",
       "routesTo": "mode-contract"
     }
   ],
   "directSkillCalls": [
+    {
+      "command": "/discuss",
+      "skill": "discuss"
+    },
     {
       "command": "/discover",
-      "skill": "discover"
+      "skill": "discuss",
+      "aliasFor": "/discuss",
+      "piOnly": true
+    },
+    {
+      "command": "/track-work",
+      "skill": "track-work"
     },
     {
       "command": "/write-spec",
@@ -35,9 +56,23 @@
       "command": "/write-plan",
       "skill": "write-plan"
     },
+    {
+      "command": "/execute-work",
+      "skill": "execute-work"
+    },
     {
       "command": "/execute-plan",
-      "skill": "execute-plan"
+      "skill": "execute-work",
+      "aliasFor": "/execute-work",
+      "piOnly": true
+    },
+    {
+      "command": "/simplify-code",
+      "skill": "simplify-code"
+    },
+    {
+      "command": "/migration-work",
+      "skill": "migration-work"
     },
     {
       "command": "/diagnose-failure",
@@ -59,13 +94,33 @@
       "command": "/handoff",
       "skill": "handoff"
     },
+    {
+      "command": "/finish-branch",
+      "skill": "finish-branch"
+    },
+    {
+      "command": "/release-work",
+      "skill": "release-work"
+    },
+    {
+      "command": "/launch-work",
+      "skill": "launch-work"
+    },
     {
       "command": "/bypass",
       "skill": "bypass"
+    }
+  ],
+  "piNativeCommands": [
+    {
+      "command": "/freeflow",
+      "handler": "freeflow",
+      "kind": "settings"
     },
     {
       "command": "/output-router",
-      "skill": "output-router"
+      "handler": "output-router",
+      "kind": "settings"
     }
   ],
   "developerSkillCalls": [