@hassangameryt/freeflow 0.2.0 → 0.4.0

package/plugins/freeflow/docs/adr/0003-release-boundary.md

@@ -1,21 +0,0 @@
-# ADR 0003: Release Boundary
-
-## Status
-
-Accepted.
-
-## Decision
-
-Freeflow ships as a marketplace repo with one plugin runtime under `plugins/freeflow/`.
-
-The plugin runtime includes skills, bundled references, context-loading runtime, public docs, eval sources/reports, command-surface metadata, Codex/Claude metadata, and Pi package metadata/extension.
-
-The runtime excludes generated eval run output, historical research notes, handoffs, enforcement hooks, CLI tools, and old Orchestra compatibility.
-
-## Rationale
-
-The public repo should be installable without generated artifacts or duplicate package copies. Eval definitions and concise reports stay near the skills they protect; generated run output stays ignored.
-
-## Consequences
-
-Release evidence is summarized in `release-evidence.md`. Generated eval run output remains ignored unless a future release intentionally publishes it.

package/plugins/freeflow/docs/adr/0004-research-replaces-shallow-discovery-skills.md

@@ -1,26 +0,0 @@
-# ADR 0004: Research Replaces Shallow Discovery Skills
-
-## Status
-
-Accepted.
-
-## Decision
-
-Freeflow uses one active `research` skill for discovery work before spec, plan, build, or durable memory.
-
-The previous active skills `research-brief`, `grill-context`, and `capture-decisions` are deprecated and moved to root `deprecated/skills/`. They are no longer part of the runtime skill surface or direct command surface.
-
-The active direct command is `/research`.
-
-## Rationale
-
-The three older skills were useful independently but shallow as a workflow module. In real use, research, brainstorming, targeted questions, and decision checkpointing need to interleave. Splitting them made the user or agent coordinate the sequence and made long grilling chains or uncaptured research decisions more likely.
-
-The `research` skill uses the same module/interface/depth/seam/leverage/locality language as architecture review so discovery can shape deep modules from the beginning, not only rescue shallow code later.
-
-## Consequences
-
-- `/research-brief`, `/grill-context`, and `/capture-decisions` are removed from the current command surface.
-- Historical evals and reports for the deprecated skills remain as development evidence.
-- Current discovery eval evidence lives in `plugins/freeflow/evals/reports/by-skill/research-1-report.md`.
-- Durable decisions now belong to the checkpoint destination chosen by `research`: spec, plan, handoff, decision note, ADR, domain memory, or chat.

package/plugins/freeflow/docs/adr/README.md

@@ -1,8 +0,0 @@
-# Freeflow ADRs
-
-Durable decisions for the public Freeflow package:
-
-- [ADR 0001: Three Workflow Modes](0001-three-modes.md)
-- [ADR 0002: Evals Before Enforcement Hooks](0002-evals-before-hooks.md)
-- [ADR 0003: Release Boundary](0003-release-boundary.md)
-- [ADR 0004: Research Replaces Shallow Discovery Skills](0004-research-replaces-shallow-discovery-skills.md)

package/plugins/freeflow/docs/architecture.md

@@ -1,86 +0,0 @@
-# Architecture
-
-Freeflow is a portable skill pack for coding agents.
-
-## Runtime Boundary
-
-Freeflow ships Markdown skills, bundled references, lightweight context-loading hooks, and a Pi extension. It does not ship a CLI, Codex/Claude native slash handlers, enforcement hooks, or a new agent runtime in this release.
-
-Host runtimes still control tools, sandboxing, approvals, and permissions. Freeflow controls workflow pressure:
-
-- how much clarification is needed
-- when artifacts are useful
-- when source-truth conflicts stop edits
-- when review and verification are required
-- when a handoff or durable decision is useful
-
-## Package Layout
-
-```text
-freeflow/
-  package.json
-  .agents/plugins/marketplace.json
-  .claude-plugin/marketplace.json
-  README.md
-  LICENSE
-  CHANGELOG.md
-  docs/
-  plugins/freeflow/
-    .codex-plugin/plugin.json
-    .claude-plugin/plugin.json
-    command-surface.json
-    hooks/
-    pi-extension/
-    skills/
-    docs/
-    evals/
-```
-
-The repository root is the marketplace and package-facing shell. Codex uses `.agents/plugins/marketplace.json`; Claude uses `.claude-plugin/marketplace.json`. Both point at `plugins/freeflow/`. Pi uses the root `package.json` `pi` manifest to load `plugins/freeflow/skills/` and `plugins/freeflow/pi-extension/index.js`.
-
-`plugins/freeflow/` is the single runtime source of truth. Skill edits, bundled references, eval metadata, and command-surface metadata live there to avoid generated package drift.
-
-## Progressive Disclosure
-
-Each skill keeps its active `SKILL.md` short. Stable details move into `references/` files only when they prevent bloat, reduce repeated work, or address measured failures.
-
-This keeps the model's first-loaded instructions focused on behavior:
-
-- trigger
-- loop
-- stop condition
-- failure prevention
-
-## Host Setup
-
-`setup-freeflow` installs a compact always-on contract into the host repo.
-
-The canonical setup contract lives in `skills/setup-freeflow/references/activation-contract.md`; setup docs, fixtures, and eval assertions should reference it or be checked against it.
-
-Codex setup targets `AGENTS.md` and `.freeflow/config.json`.
-
-Claude setup targets `CLAUDE.md`, `.claude/rules/freeflow-core.md`, and `.freeflow/config.json` when Claude is the selected host.
-
-Setup should not silently update both hosts or overwrite stronger repo-specific rules. Existing repo instructions are source truth.
-
-## Runtime Context Hooks
-
-The installed plugin owns `hooks/hooks.json`. Setup does not copy hook files into target repos.
-
-The hooks load the existing `workflow` skill, workflow map, and `interview-gate` skill:
-
-- at session start, including startup, resume, clear, and compact
-
-They also report whether the current repo appears set up, partially set up, or missing setup. They do not run after edit/write tools, block tools, grant permissions, enforce mode policy, or replace repo instructions.
-
-Setup handles the same-session case directly: after successful setup verification, it reads the workflow skill, workflow map, and interview-gate skill before its final response and only then says workflow and interview-gate context is loaded.
-
-Host runtimes may require plugin hooks to be reviewed and trusted after install. If the host skips untrusted hooks, setup still writes activation/config files, but future session-start runtime context will not load until hooks are trusted and the session is restarted, resumed, cleared, or compacted.
-
-Pi uses an extension instead of `hooks/hooks.json`. The Pi extension registers direct commands, reads `workflow/SKILL.md`, `workflow/references/workflow-map.md`, `interview-gate/SKILL.md`, `output-router/SKILL.md`, and `output-router/references/safety-policy.md`, refreshes that context on `session_start` and `session_compact`, and injects it during Pi's `before_agent_start` lifecycle event. The same extension registers `freeflow_retrieve` and `freeflow_run` and gives them compact/expanded TUI renderers so collapsed tool rows stay readable while `ctrl+o` shows structured evidence and recovery details. Pi `/workflow` commands set a session-scoped current-mode override, while `.freeflow/config.json` remains the default-mode source. It follows the same boundary as the Codex/Claude hooks: context loading only, no enforcement.
-
-## Deferred Enforcement
-
-Enforcement hooks and CLI checks are intentionally deferred. They are useful only after skill wording and evals prove a repeated behavior needs mechanical enforcement.
-
-For this release, commands are model-routed language such as `/write-spec` or `/verify-work`; they are not native registered slash handlers.

package/plugins/freeflow/docs/output-router.md

@@ -1,212 +0,0 @@
-# Output Router
-
-Freeflow Output Router keeps agent context focused while preserving exact evidence outside context.
-
-Use it when broad repo exploration, generated artifacts, large logs, or noisy command output would otherwise flood the model.
-
-For the full architecture, see [`docs/designs/freeflow-output-router-architecture.md`](../../../docs/designs/freeflow-output-router-architecture.md) in the repo root.
-
-## Core Idea
-
-```text
-smallest sufficient evidence in context
-+ exact raw recovery outside context
-+ no surprise native tool semantics
-```
-
-The router ships two explicit tools:
-
-- `freeflow_retrieve`: retrieve targeted repo/vault evidence.
-- `freeflow_run`: run likely-large/noisy commands, vault raw output, and return compact evidence.
-
-Native tools still matter:
-
-- use native `read` for known whole files,
-- use native `bash` for small/direct raw shell behavior,
-- use native `edit`/`write` for mutations.
-
-## Tiny Map
-
-```mermaid
-flowchart LR
-  Agent[agent]
-  Retrieve[freeflow_retrieve]
-  Run[freeflow_run]
-  Repo[repo files]
-  Vault[Freeflow vault]
-  Native[native read/bash]
-  Evidence[bounded evidence]
-  Raw[exact recovery]
-
-  Agent -->|existing info| Retrieve
-  Agent -->|noisy command| Run
-  Agent -->|direct/raw known output| Native
-  Retrieve --> Repo --> Evidence
-  Retrieve --> Vault --> Evidence
-  Run --> Vault
-  Run --> Evidence
-  Vault --> Raw
-```
-
-## Tool Choice
-
-| Need | Use |
-| --- | --- |
-| Find repo evidence before reading files | `freeflow_retrieve action=query` |
-| Get candidate paths first | `freeflow_retrieve action=locate` |
-| Retrieve exact repo/vault lines | `freeflow_retrieve action=retrieve` with `lineRange` |
-| Widen previous evidence | `freeflow_retrieve action=expand` |
-| Explain a previous routed decision/output | `freeflow_retrieve action=explain` |
-| Run noisy/large command output | `freeflow_run` |
-| Read a known whole file | native `read` |
-| Run small exact command | native `bash` |
-
-## `freeflow_retrieve`
-
-Sources:
-
-- `repo`: local repo files.
-- `vault`: previous routed command/native output.
-
-Actions:
-
-- `query`: returns best evidence packets; default `topK=1`.
-- `locate`: returns candidate locations; default `topK=5`.
-- `retrieve`: returns explicit path/line range evidence.
-- `expand`: expands a previous evidence packet to `lines_30`, `lines_80`, or `full`.
-- `explain`: explains a route decision or vault output.
-
-Example:
-
-```json
-{
-  "action": "query",
-  "source": { "kind": "repo" },
-  "query": "Sandbox Permissions UseDefault RequireEscalated WithAdditionalPermissions",
-  "preserve": "important"
-}
-```
-
-Evidence packets include:
-
-- source/path,
-- line range,
-- exact excerpt,
-- why the router selected it,
-- expansion/recovery guidance.
-
-Repo retrieval uses deterministic scanner ranking by default. Broad scans skip generated/dependency/cache paths such as `graphify-out/**`, but explicit path retrieval remains available.
-
-## `freeflow_run`
-
-`freeflow_run` executes once through the host-approved runner, stores exact raw output in the vault, then returns useful command evidence.
-
-Example:
-
-```json
-{
-  "command": "npm test",
-  "goal": "verification",
-  "preserve": "important"
-}
-```
-
-Returned results include:
-
-- `outputId`,
-- `execution.status` and `exitCode`,
-- parser metadata,
-- important lines,
-- exact recovery instructions.
-
-Command parsers currently cover:
-
-- test runner output,
-- TypeScript/lint diagnostics,
-- git status/diffstat,
-- build/toolchain errors,
-- generic fallback,
-- duplicate output detection.
-
-## Vault Recovery
-
-Recover exact command output with:
-
-```json
-{
-  "action": "retrieve",
-  "source": { "kind": "vault", "outputId": "ffout_...", "stream": "combined" },
-  "lineRange": { "start": 1, "end": 40 },
-  "preserve": "full"
-}
-```
-
-Streams:
-
-- command output: `stdout`, `stderr`, `combined`,
-- native safety-net output: `raw`.
-
-Default vault root:
-
-```text
-~/.cache/freeflow-router/vault
-```
-
-## Config
-
-The router works with built-in defaults. Minimal `/setup-freeflow` writes only `defaultMode`.
-
-Optional repo config lives in `.freeflow/config.json` only when explicitly requested:
-
-```json
-{
-  "defaultMode": "workflow",
-  "outputRouter": {
-    "postToolRouting": "off",
-    "largeOutputBytes": 64000,
-    "largeOutputLines": 1000,
-    "vaultRoot": "~/.cache/freeflow-router/vault",
-    "vaultRetentionDays": 7,
-    "generatedPaths": ["graphify-out/**"],
-    "noisyCommandHints": ["npm test"]
-  }
-}
-```
-
-Rules:
-
-- `postToolRouting` defaults to `off`.
-- `safety-net` is opt-in.
-- `strict` is reserved.
-- Do not dump defaults into config.
-- Write only requested keys.
-
-## Native Safety Net
-
-Pi can optionally route large native `read`/`bash` results after the tool runs.
-
-Default: off.
-
-When enabled, a routed native result is labeled, vaulted, and includes an `outputId`. If safety-net routing fails, Freeflow fails open and returns native output with a warning.
-
-## Defaults And Experiments
-
-Current adoption decisions:
-
-- Scanner retrieval is the default backend.
-- The no-dependency local index is experimental and not adopted by default.
-- SQLite/FTS is not adopted.
-- Model-assisted routing is not default.
-- Graphify, Claude Context, RTK, and Squeez are optional references/comparators, not dependencies.
-
-## Evidence
-
-Current release evidence:
-
-- Retrieval benchmark: improved router passed 7/7 fixtures.
-- Command benchmark: `freeflow_run` passed 8/8 fixtures with exact recovery.
-- Optional index benchmark: scanner remains default; index not adopted.
-- Codex Structured Q&A benchmark: improved router passed the Sandbox Permissions fixture where native broad search selected `graphify-out/graph.html`.
-- Setup eval: optional `outputRouter` config is opt-in; minimal setup remains only `defaultMode`.
-
-See `release-evidence.md` and runtime reports under `plugins/freeflow/evals/reports/runtime/`.

package/plugins/freeflow/docs/release-evidence.md

@@ -1,69 +0,0 @@
-# Release Evidence
-
-Freeflow v0.2.0 is based on the v0.1 local acceptance suite plus targeted runtime, setup, and output-router evidence from the development repository.
-
-## Acceptance Summary
-
-The local v0.1 acceptance suite passed after measured fixes and was rerun during prepublish verification on 2026-05-26.
-
-High-signal behaviors covered:
-
-- Source-truth conflicts stop before edits.
-- Strict public API specs ask for owner decisions.
-- Execution stops when verification reveals a bad plan.
-- Commit flow refuses mixed staged sensitive changes.
-- Research checkpoints replace separate research, grilling, and decision-capture commands for discovery work.
-- Bypass skips ceremony, not judgment.
-
-## Command Surface
-
-The development registry covers:
-
-- 4 mode commands.
-- 11 direct workflow skill calls.
-- 2 contributor skill calls.
-
-Codex/Claude native slash handlers are not shipped in this release. In those hosts, commands are model-routed through natural language and skill activation. Pi registers direct Freeflow commands through its extension.
-
-## Runtime Context
-
-Freeflow ships plugin-bundled context hooks that load the existing `workflow` skill, workflow map, and `interview-gate` skill at session start. The Pi extension also loads output-router context, including its safety-policy reference, when the routed tools are available. These hooks do not run after edit/write tools, enforce behavior, block tools, or create repo-local hook files.
-
-For the same session that runs setup, `setup-freeflow` reads the workflow skill, workflow map, and interview-gate skill after successful setup verification before saying workflow and interview-gate context is loaded.
-
-Host trust prompts for plugin hooks are expected host behavior. Local metadata validation checks hook packaging and deterministic output, not end-to-end host trust UI.
-
-## Output Router Evidence
-
-Output-router behavior is backed by deterministic runtime reports under `plugins/freeflow/evals/reports/runtime/`.
-
-Verified in the development repo:
-
-- Retrieval benchmark: improved router passed 7/7 gated fixtures and fixed the generated-artifact Sandbox Permissions false-positive shape.
-- Command-output benchmark: `freeflow_run` passed 8/8 fixtures, preserved exact facts, and verified raw vault recovery.
-- Optional local index benchmark: scanner remains default, index is not adopted by default, and the no-dependency index remains experimental.
-- Codex Structured Q&A macro benchmark: improved router passed the first Sandbox Permissions Q&A fixture while the native broad-search proxy selected `graphify-out/graph.html`.
-- Large Codex scanner benchmark: scanner remains the retrieval backend; latest recorded report-refresh evidence kept scanner at 6/8 strict fixtures with bounded context.
-- Setup/config eval: `setup-freeflow` supports optional `outputRouter` repo config only when explicitly requested; minimal setup still writes only `defaultMode`.
-
-Adoption decisions:
-
-- Scanner improvements ship as default behavior.
-- Native post-tool safety-net routing remains off unless explicitly configured.
-- The no-dependency local index stays experimental.
-- SQLite/FTS, model-assisted routing, Graphify, and Claude Context remain optional/non-default comparison paths, not product dependencies.
-
-## Release Metadata
-
-Run `plugins/freeflow/evals/scripts/validate-release-metadata.sh` for local prepublish checks across marketplace metadata, host manifests, command-surface routing, release-boundary docs, package cleanliness, and deferred install-smoke status.
-
-Run `plugins/freeflow/evals/scripts/check-runtime-context-hook.sh` after changing lifecycle context hooks.
-
-## Known Deferred Work
-
-- Live Claude smoke evals after Hassan confirms Claude testing is available again.
-- GitHub-install smoke tests in separate Codex, Claude, and fresh Pi environments.
-- Enforcement hooks or CLI checks only after repeated behavior failures justify them.
-- Public marketplace submission only after GitHub install works for required hosts.
-
-Full eval reports are development evidence and are not included in the runtime package.

package/plugins/freeflow/docs/skills.md

@@ -1,43 +0,0 @@
-# Skills
-
-Freeflow ships a small workflow skill pack. Natural language is the preferred interface. In Codex/Claude, slash-style phrases work as model-routed skill hints; in Pi, the extension registers direct Freeflow commands.
-
-## Core
-
-| Skill | Use When |
-| --- | --- |
-| `workflow` | Choosing the next workflow entry point or explaining the full flow. |
-| `mode-contract` | Inferring or switching `conversation`, `workflow`, or `strict-workflow`. |
-| `interview-gate` | Ambiguity or a user-owned decision would change the next action. |
-| `output-router` | Choosing routed tools for large/noisy output, vault recovery, or output-router configuration. |
-| `bypass` | Skipping unnecessary ceremony without skipping judgment. |
-
-## Discovery And Artifacts
-
-| Skill | Use When |
-| --- | --- |
-| `research` | An idea, feature, architecture direction, vague task, or consequential question needs evidence, brainstorming, targeted questions, and a checkpoint before spec, plan, build, or durable memory. |
-| `write-spec` | Agreed requirements or decisions need a durable spec. |
-| `review-artifact` | A spec, plan, handoff, research checkpoint, or decision note must guide future work. |
-| `write-plan` | An approved spec or explicit task context needs executable slices. |
-
-## Execution And Closeout
-
-| Skill | Use When |
-| --- | --- |
-| `execute-plan` | An approved plan exists and should be implemented in checked slices, especially multi-slice/TDD work with verification, review, commit, or handoff checkpoints. |
-| `diagnose-failure` | Behavior is broken, failing, flaky, slow, or unclear. |
-| `review-work` | A completed diff or review feedback needs bug/risk-focused review or adjudication before fixes. |
-| `verify-work` | Fresh evidence is needed before claiming completion. |
-| `commit-work` | Reviewed, verified, intended work is ready to commit. |
-| `handoff` | Pausing, compacting, transferring context, or preserving continuation memory. |
-
-## Contributor Skills
-
-| Skill | Use When |
-| --- | --- |
-| `setup-freeflow` | Installing the compact always-on Freeflow contract into a repo. |
-| `write-skill` | Creating or revising concise behavior-shaping skills. |
-| `evaluate-skill` | Turning failures into baseline-vs-with-skill evals and revising from evidence. |
-
-These contributor skills are shipped because teams may use Freeflow to install or adapt workflow behavior, but they are not normal workflow states for ordinary feature work.

package/plugins/freeflow/docs/workflow.md

@@ -1,57 +0,0 @@
-# Workflow
-
-Freeflow is a workflow layer, not a new agent. It helps the agent choose the right amount of process for the task.
-
-## Modes
-
-- `conversation`: answer, explain, critique, or explore without workflow pressure.
-- `workflow`: default for consequential work; use the workflow spine and scale detail to risk.
-- `strict-workflow`: high-risk or hard-to-reverse work with stronger gates.
-
-Use strict-workflow for security, privacy, billing, public APIs, migrations, data loss, compatibility, permissions, deployment, or irreversible architecture.
-
-## Map
-
-```mermaid
-flowchart LR
-  Request{request}
-  Talk[conversation<br/>answer directly]
-  Discover[discover<br/>research checkpoint]
-  Spec[spec]
-  Plan[plan]
-  Build[build<br/>execute / diagnose]
-  Check[review + verify]
-  Close[commit / handoff]
-
-  Request -->|question| Talk
-  Request -->|work| Discover
-  Discover --> Spec --> Plan --> Build --> Check --> Close
-  Check -. new evidence or failed check .-> Discover
-```
-
-The map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates.
-
-## Backward Edge
-
-Loop back when new evidence changes the path:
-
-```mermaid
-flowchart LR
-  Trigger{new evidence<br/>conflict<br/>failed check<br/>owner decision}
-  Decide{changes<br/>next action?}
-  Continue[continue]
-  Reenter[clarify / research<br/>revise spec or plan<br/>diagnose / split / stop]
-
-  Trigger --> Decide
-  Decide -->|no| Continue
-  Decide -->|yes| Reenter
-  Reenter -. resume .-> Decide
-```
-
-The agent should not silently choose the backward destination when the choice changes product behavior, scope, compatibility, public APIs, security, privacy, billing, data loss, permissions, or irreversible architecture.
-
-## Bypass
-
-Bypass skips ceremony, not judgment.
-
-Use `bypass` only to skip an unnecessary gate. It does not skip user-owned decisions, source-truth conflicts, risky checks, or fresh verification before completion claims.