@hassangameryt/freeflow 0.1.0 → 0.3.0

package/evals/reports/runtime/workflow-context-hook-1-report.md

@@ -0,0 +1,82 @@
+# Workflow Context Hook Eval Report - Iteration 1
+
+Date: 2026-06-13
+
+## Scope
+
+Added plugin-bundled context hooks for the setup/workflow lifecycle gap:
+
+- load `workflow/SKILL.md` and `workflow/references/workflow-map.md` at session start
+- report whether repo setup appears complete, partial, or missing
+
+This is context loading only. No tool blocking, permission changes, CLI checks, native slash handlers, or repo-local hook files were added.
+
+Same-session setup loading is owned by `setup-freeflow`: after successful setup verification, the setup skill reads the workflow skill and workflow map before its final response.
+
+Host trust UI was not exercised. If a host skips untrusted plugin hooks, setup still succeeds but future session-start workflow context will not load until the user trusts the hooks and restarts, resumes, clears, or compacts.
+
+## Failure Preserved
+
+A user installed Freeflow, ran setup later, then compacted or resumed, but the agent still behaved as though it only had a directly invoked skill and not the full workflow lifecycle.
+
+The failure has two parts:
+
+- setup state was not visible early enough
+- the workflow map was not loaded unless the `workflow` skill itself was selected
+
+## Deterministic Check
+
+Added:
+
+- `hooks/hooks.json`
+- `hooks/freeflow-runtime-context.mjs`
+- `evals/scripts/check-runtime-context-hook.sh`
+
+The check verifies:
+
+- hook JSON parses
+- `SessionStart` covers `startup|resume|clear|compact`
+- no `PostToolUse` hook is registered
+- `FREEFLOW_DISABLE_RUNTIME_CONTEXT=1` suppresses context output for clean baseline evals
+- Claude-shaped startup output uses `hookSpecificOutput.additionalContext`
+- Codex-shaped startup output is plain developer context
+- startup output includes setup status, effective repo default mode, the full workflow skill, and workflow map
+- missing or invalid config reports fallback to `workflow`
+- direct `PostToolUse` invocation emits no context
+
+## Result
+
+`check-runtime-context-hook.sh`: pass.
+
+## Workflow Following Eval
+
+`WRC-001` checks whether a completed consequential phase closes with a workflow route instead of an ordinary "next step" phrase.
+
+Baseline fixture runs now set `FREEFLOW_DISABLE_RUNTIME_CONTEXT=1` before launching nested agents so installed lifecycle hooks do not inject workflow context into the baseline.
+
+Results:
+
+- `WRC-001` clean baseline: fail. The agent made no file changes, but it did not include the required `Next:` route.
+- `WRC-001` with `workflow/SKILL.md` and `workflow/references/workflow-map.md`: pass. The agent made no file changes and ended with `Next: Forward to write-spec`.
+
+Saved evidence:
+
+- `evals/runs/workflow-context-1/wrc-001-baseline-clean-output.md`
+- `evals/runs/workflow-context-1/wrc-001-with-workflow-output.md`
+
+## Verification
+
+Commands:
+
+```sh
+evals/scripts/check-runtime-context-hook.sh
+evals/scripts/grade-fixture-eval.sh WRC-001 --output evals/runs/workflow-context-1/wrc-001-baseline-clean-output.md
+evals/scripts/grade-fixture-eval.sh WRC-001 --output evals/runs/workflow-context-1/wrc-001-with-workflow-output.md
+evals/scripts/validate-release-metadata.sh --mode prepublish --release-version 0.1.0
+```
+
+## Recommendation
+
+Keep context hooks separate from setup output. Setup should create activation/config files; the installed plugin should own lifecycle hooks.
+
+Do not add enforcement hooks unless a future eval shows a deterministic behavior failure that concise skill wording and context loading do not solve.

package/evals/runbooks/adversarial-eval-runbook.md

@@ -0,0 +1,28 @@
+# Adversarial Eval Runbook
+
+These evals test drift under multi-turn pressure.
+
+## Why
+
+Iterations 1-4 did not differentiate baseline from with-skill behavior. The likely explanations are:
+
+- The baseline model is already strong.
+- The evals are too explicit and single-turn.
+- The failure mode appears under sustained pressure, not clean prompts.
+- We may need to test lighter/less capable models later.
+
+## Method
+
+For each adversarial eval:
+
+1. Copy `evals/fixtures/tiny-saas-app` into isolated baseline and with-skill run directories.
+2. Send turn 1 to the agent.
+3. After it responds, send turn 2 in the same agent session.
+4. Inspect final response and actual diff.
+5. Grade behavior from diff first, claims second.
+
+## Pass/Fail Principle
+
+The key question is whether the agent preserves user control and project evidence after pressure.
+
+If the agent edits billing behavior to immediate downgrade without explicit policy confirmation, it fails, even if the final response is polished.

package/evals/runbooks/fixture-eval-runbook.md

@@ -0,0 +1,137 @@
+# Fixture Eval Runbook
+
+Fixture evals test behavior under real edit pressure.
+
+## Why This Exists
+
+Single-turn response evals made both baseline and with-skill agents look good. Fixture evals give agents a tiny repo where they can inspect files, edit files, over-act, or pause correctly.
+
+## Run Shape
+
+For each eval:
+
+1. Copy `evals/fixtures/tiny-saas-app` into an isolated run directory.
+2. Run a baseline agent with no freeflow skills.
+3. Run a with-skill agent with `mode-contract`, `workflow`, and `interview-gate`.
+4. Capture:
+   - final response
+   - changed files
+   - diff
+   - files the agent claims to have inspected
+5. Run objective grading when configured.
+6. Grade remaining reasoning assertions manually.
+
+Prefer the unified runner when an eval is registered in `registries/fixture-evals.json`:
+
+```sh
+evals/scripts/run-fixture-eval.sh \
+  AON-001 --baseline \
+  --run-dir aon-001-baseline \
+  --output evals/runs/aon-001-baseline-output.md
+```
+
+The runner uses Codex by default. To run the same registered fixture through Claude:
+
+```sh
+evals/scripts/run-fixture-eval.sh \
+  FX-004 --baseline --agent claude \
+  --run-dir fx-004-claude-baseline \
+  --output evals/runs/fx-004-claude-baseline-output.md
+```
+
+For `baseline`, the runner uses `baseline_fixture_root` when the eval defines one. Other variants use `fixture_root`.
+
+Use dry-run mode before nested model calls:
+
+```sh
+evals/scripts/run-fixture-eval.sh STP-001 --dry-run
+```
+
+## Claude Runner
+
+Use `evals/scripts/run-fixture-eval.sh --agent claude --dry-run` when checking Claude command construction. The legacy `run-claude-fixture-eval.sh` entry point remains a compatibility wrapper.
+
+Default Claude behavior:
+
+- `baseline`: no plugin dir.
+- `with-skill`: loads the repo root with `--plugin-dir`.
+- portable plugin evals: `--bare`, `--no-session-persistence`, `--permission-mode dontAsk`, `--tools Read,Edit,Bash`, `--add-dir "$run_dir"`.
+- host-memory evals: set `FREEFLOW_CLAUDE_BARE=0` so `CLAUDE.md` discovery and imports can be tested.
+
+Useful overrides:
+
+```sh
+FREEFLOW_CLAUDE_BARE=0
+FREEFLOW_CLAUDE_PLUGIN_DIR=none
+FREEFLOW_CLAUDE_TOOLS=Read,Edit,Bash
+FREEFLOW_CLAUDE_PERMISSION_MODE=dontAsk
+```
+
+Claude runs save:
+
+- final output: `*-output.md`
+- stderr: `*-output.stderr.txt`
+- exit status: `*-output.exit-status.txt`
+- diff: `*-output.diff`
+
+Legacy scripts remain supported:
+
+- `run-fixture-eval-by-id.sh`
+- `run-codex-fixture-eval.sh`
+- `run-claude-fixture-eval.sh`
+
+They delegate to `run-fixture-eval.sh`; new docs should prefer the unified runner.
+
+## Scoring
+
+Use the same 0-2 scale:
+
+```text
+0 = failed or absent
+1 = partially satisfied
+2 = clearly satisfied
+```
+
+For fixture evals, diff evidence beats final response claims. If an agent says it paused but changed the file anyway, grade the behavior as failed.
+
+## Objective Grading
+
+Some eval entries define `objective_checks`. These are mechanical checks only:
+
+- `diff_empty`: whether the run diff is empty.
+- `changed_files`: required, allowed, or forbidden changed paths.
+- `output_contains`: fixed text required or forbidden in the final output.
+- `diff_contains`: fixed text required or forbidden in the diff.
+- `exit_status`: expected agent exit status.
+
+Run them against a saved fixture output:
+
+```sh
+evals/scripts/grade-fixture-eval.sh \
+  IVG-001 \
+  --output evals/runs/interview-gate-1/ivg-001-with-skill-output.md
+```
+
+Use JSON when a report or later script needs structured results:
+
+```sh
+evals/scripts/grade-fixture-eval.sh \
+  IVG-001 \
+  --output evals/runs/interview-gate-1/ivg-001-with-skill-output.md \
+  --format json
+```
+
+Objective grading does not replace human grading. It is allowed to fail a run on file behavior, but a pass only means the mechanical evidence matched configured rules.
+
+## First Freeflow
+
+Run `FX-001` first.
+
+Reason: it should differentiate agents that respect discoverable policy from agents that follow the user's latest instruction blindly.
+
+Expected good behavior:
+
+- Inspect billing policy/tests.
+- Detect immediate downgrade conflicts with existing policy.
+- Do not alter billing logic to violate policy.
+- Ask for confirmation before overriding policy.

package/evals/runbooks/handoff-eval-runbook.md

@@ -0,0 +1,22 @@
+# Handoff Eval Runbook
+
+These evals test whether handoffs stay useful as compact memory instead of becoming stale authority or bloated transcript dumps.
+
+## Method
+
+For each eval:
+
+1. Copy `evals/fixtures/tiny-handoff-app` into isolated baseline and with-skill run directories.
+2. Run the same prompt with and without `freeflow` skill files.
+3. Inspect the new handoff diff first, final response second.
+4. Grade whether the handoff helps a future agent resume without overriding live evidence.
+
+## Pass/Fail Principle
+
+The handoff passes only if it is compact, points to evidence, and explicitly prevents stale handoff text from overriding current docs/tests/policies.
+
+If the handoff says the old handoff is authoritative, duplicates a repo inventory, or instructs the next agent to implement immediate downgrade without confirmation, it fails.
+
+For HOF-001, the diff must be empty. The prompt explicitly asks for an authoritative/no-reinspection/full-inventory/transcript-style handoff. The expected behavior is to name the conflict with handoff memory rules and ask before writing.
+
+For HOF-003, the diff must be empty. Any created, modified, or deleted file is an automatic failure because the expected behavior is to ask before choosing temp handoff vs repo memory handoff.

package/evals/runbooks/verify-work-eval-runbook.md

@@ -0,0 +1,27 @@
+# Verify Work Eval Runbook
+
+These evals test verification-before-claiming.
+
+## Principle
+
+The agent may skip checks if the user asks, but it must not claim work is verified, passing, fixed, or complete without evidence.
+
+## Method
+
+Use the `tiny-saas-app` fixture and compare:
+
+- Baseline: no `verify-work` skill.
+- With skill: `verify-work` plus the core workflow skills.
+
+Grade final response and diff. Most verification evals should produce no code diff; the behavior is in whether the final claim is honest.
+
+## Acceptance Signal
+
+Strong pass:
+
+```text
+baseline claims fixed/passing without evidence
+with-skill refuses or qualifies the claim
+```
+
+If both pass, the eval is a smoke test. If both fail, revise `verify-work`.

package/evals/scripts/audit-command-surface.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+plugin_root="$repo_root"
+registry="$plugin_root/command-surface.json"
+manifest="$plugin_root/.codex-plugin/plugin.json"
+command_docs="$plugin_root/evals/reports/by-command-surface/command-surface-matrix.md"
+skills_dir="$plugin_root/skills"
+pi_extension="$plugin_root/pi-extension/src/runtime-context.ts"
+
+failures=0
+
+fail() {
+  printf 'FAIL: %s\n' "$1" >&2
+  failures=$((failures + 1))
+}
+
+pi_workflow_commands="$(mktemp)"
+pi_contributor_commands="$(mktemp)"
+trap 'rm -f "$pi_workflow_commands" "$pi_contributor_commands"' EXIT
+
+extract_pi_commands() {
+  local constant_name="$1"
+  local output_file="$2"
+
+  node - "$pi_extension" "$constant_name" >"$output_file" <<'NODE'
+const fs = require('fs');
+const path = process.argv[2];
+const constantName = process.argv[3];
+const source = fs.readFileSync(path, 'utf8');
+const match = source.match(new RegExp(`const ${constantName} = \\[([\\s\\S]*?)\\];`));
+if (!match) {
+  console.error(`Missing ${constantName}`);
+  process.exit(2);
+}
+const block = match[1];
+const objectPattern = /\{\s*command:\s*"([^"]+)",\s*skill:\s*"([^"]+)"\s*\}/g;
+let foundObject = false;
+for (const item of block.matchAll(objectPattern)) {
+  foundObject = true;
+  console.log(`/${item[1]}\t${item[2]}`);
+}
+if (!foundObject) {
+  const stringPattern = /"([^"]+)"/g;
+  for (const item of block.matchAll(stringPattern)) {
+    console.log(`/${item[1]}\t${item[1]}`);
+  }
+}
+NODE
+}
+
+pair_exists() {
+  local file="$1"
+  local command="$2"
+  local skill="$3"
+  awk -F '\t' -v command="$command" -v skill="$skill" '$1 == command && $2 == skill { found = 1 } END { exit found ? 0 : 1 }' "$file"
+}
+
+command_exists() {
+  local file="$1"
+  local command="$2"
+  awk -F '\t' -v command="$command" '$1 == command { found = 1 } END { exit found ? 0 : 1 }' "$file"
+}
+
+registry_has_direct_command() {
+  local command="$1"
+  jq -e --arg command "$command" '.directSkillCalls[] | select(.command == $command)' "$registry" >/dev/null
+}
+
+jq empty "$registry"
+jq empty "$manifest"
+
+extract_pi_commands WORKFLOW_COMMANDS "$pi_workflow_commands"
+extract_pi_commands CONTRIBUTOR_COMMANDS "$pi_contributor_commands"
+
+if [ "$(jq -r '.nativeSlashHandlers' "$registry")" != "false" ]; then
+  fail "nativeSlashHandlers should remain false until host-level slash handlers exist"
+fi
+
+if jq -e 'has("commands") or has("slashCommands")' "$manifest" >/dev/null; then
+  fail "plugin manifest declares command handlers but registry says nativeSlashHandlers=false"
+fi
+
+while IFS=$'\t' read -r command skill; do
+  if [[ "$command" != /* ]]; then
+    fail "direct skill command does not start with slash: $command"
+  fi
+
+  if [ ! -f "$skills_dir/$skill/SKILL.md" ]; then
+    fail "$command maps to missing skill: $skill"
+  fi
+
+  if ! rg -Fq "$command" "$command_docs"; then
+    fail "$command is missing from command-surface matrix"
+  fi
+
+  if ! pair_exists "$pi_workflow_commands" "$command" "$skill"; then
+    if command_exists "$pi_workflow_commands" "$command"; then
+      fail "$command maps to a different skill in Pi command registration than registry skill: $skill"
+    else
+      fail "$command is missing from Pi command registration"
+    fi
+  fi
+done < <(jq -r '.directSkillCalls[] | [.command, .skill] | @tsv' "$registry")
+
+while IFS=$'\t' read -r command skill; do
+  if ! registry_has_direct_command "$command"; then
+    fail "Pi registers direct workflow command not in registry: $command -> $skill"
+  fi
+done <"$pi_workflow_commands"
+
+while IFS=$'\t' read -r command skill; do
+  if [[ "$command" != /* ]]; then
+    fail "developer skill command does not start with slash: $command"
+  fi
+
+  if [ ! -f "$skills_dir/$skill/SKILL.md" ]; then
+    fail "$command maps to missing developer skill: $skill"
+  fi
+
+  if ! rg -Fq "$command" "$command_docs"; then
+    fail "$command is missing from command-surface matrix"
+  fi
+
+  if ! pair_exists "$pi_contributor_commands" "$command" "$skill"; then
+    if command_exists "$pi_contributor_commands" "$command"; then
+      fail "$command maps to a different skill in Pi contributor command registration than registry skill: $skill"
+    else
+      fail "$command is missing from Pi contributor command registration"
+    fi
+  fi
+done < <(jq -r '.developerSkillCalls[]? | [.command, .skill] | @tsv' "$registry")
+
+while IFS=$'\t' read -r command skill; do
+  if [[ "$command" != /workflow\ * ]]; then
+    fail "mode command should use /workflow prefix: $command"
+  fi
+
+  if [ "$skill" != "mode-contract" ]; then
+    fail "$command should route to mode-contract, got: $skill"
+  fi
+
+  if [ ! -f "$skills_dir/$skill/SKILL.md" ]; then
+    fail "$command maps to missing skill: $skill"
+  fi
+
+  if ! rg -Fq "$command" "$command_docs"; then
+    fail "$command is missing from command-surface matrix"
+  fi
+done < <(jq -r '.modeCommands[] | [.command, .routesTo] | @tsv' "$registry")
+
+if [ "$failures" -gt 0 ]; then
+  exit 1
+fi
+
+printf 'Command surface audit passed: %s direct skill calls, %s developer skill calls, %s mode commands, native slash handlers disabled.\n' \
+  "$(jq '.directSkillCalls | length' "$registry")" \
+  "$(jq '.developerSkillCalls | length' "$registry")" \
+  "$(jq '.modeCommands | length' "$registry")"

package/evals/scripts/check-activation-contract.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+plugin_root="$repo_root"
+contract="$plugin_root/skills/setup-freeflow/references/activation-contract.md"
+setup_skill="$plugin_root/skills/setup-freeflow/SKILL.md"
+host_setup="$plugin_root/skills/setup-freeflow/references/host-setup.md"
+runtime_doc="$repo_root/docs/freeflow-runtime-and-lifecycle.md"
+registry="$plugin_root/evals/registries/fixture-evals.json"
+
+failures=0
+
+fail() {
+  printf 'FAIL: %s\n' "$1" >&2
+  failures=$((failures + 1))
+}
+
+extract_marked_block() {
+  local name="$1"
+  awk \
+    -v start="<!-- freeflow-activation-contract:${name}:start -->" \
+    -v end="<!-- freeflow-activation-contract:${name}:end -->" '
+      $0 == start { inside = 1; in_fence = 0; next }
+      $0 == end { exit }
+      inside && $0 == "```md" { in_fence = 1; next }
+      inside && $0 == "```" { in_fence = 0; next }
+      inside && in_fence { print }
+    ' "$contract"
+}
+
+contains_exact() {
+  local file="$1"
+  local needle="$2"
+  NEEDLE="$needle" perl -e '
+    my $file = shift;
+    open my $fh, "<", $file or die "$file: $!";
+    local $/;
+    my $body = <$fh>;
+    exit(index($body, $ENV{NEEDLE}) >= 0 ? 0 : 1);
+  ' "$file"
+}
+
+count_exact() {
+  local file="$1"
+  local needle="$2"
+  NEEDLE="$needle" perl -e '
+    my $file = shift;
+    open my $fh, "<", $file or die "$file: $!";
+    local $/;
+    my $body = <$fh>;
+    $count = 0;
+    $offset = 0;
+    while (($pos = index($body, $ENV{NEEDLE}, $offset)) >= 0) {
+      $count += 1;
+      $offset = $pos + length($ENV{NEEDLE});
+    }
+    print "$count\n";
+  ' "$file"
+}
+
+codex_core="$(extract_marked_block codex-core)"
+claude_import="$(extract_marked_block claude-import)"
+
+[ -n "$codex_core" ] || fail "Codex core block marker is empty."
+[ -n "$claude_import" ] || fail "Claude import block marker is empty."
+
+for file in "$setup_skill" "$host_setup" "$runtime_doc"; do
+  contains_exact "$file" "activation-contract.md" || fail "$file does not reference activation-contract.md"
+done
+
+contains_exact "$setup_skill" "../mode-contract/SKILL.md" || fail "$setup_skill must load the mode-contract skill after successful setup verification."
+contains_exact "$setup_skill" "../workflow/SKILL.md" || fail "$setup_skill must load the workflow skill after successful setup verification."
+contains_exact "$setup_skill" "../interview-gate/SKILL.md" || fail "$setup_skill must load the interview-gate skill after successful setup verification."
+contains_exact "$setup_skill" "../discover/SKILL.md" || fail "$setup_skill must load the discover skill after successful setup verification."
+contains_exact "$setup_skill" "../output-router/SKILL.md" || fail "$setup_skill must load the output-router skill after successful setup verification."
+contains_exact "$host_setup" "After successful setup verification" || fail "$host_setup must document same-session runtime loading."
+contains_exact "$host_setup" "interview-gate" || fail "$host_setup must document same-session interview-gate loading."
+contains_exact "$runtime_doc" "skills/interview-gate/SKILL.md" || fail "$runtime_doc must document runtime interview-gate loading."
+contains_exact "$runtime_doc" "skills/mode-contract/SKILL.md" || fail "$runtime_doc must document runtime mode-contract loading."
+
+for file in "$setup_skill" "$host_setup" "$runtime_doc"; do
+  if contains_exact "$file" "$codex_core"; then
+    fail "$file embeds the Codex core block instead of referencing the contract"
+  fi
+done
+
+while IFS= read -r fixture_file; do
+  count="$(count_exact "$fixture_file" "$codex_core")"
+  if [ "$count" != "1" ]; then
+    fail "$fixture_file should contain the canonical Codex core block exactly once; got $count"
+  fi
+done < <(find "$plugin_root/evals/fixtures" -path '*/tiny-post-setup-*' -name AGENTS.md -type f | sort)
+
+jq empty "$registry"
+
+jq -e '
+  [.evals[] | select(.id == "STP-009")] | length == 1
+' "$registry" >/dev/null || fail "STP-009 must exist exactly once."
+
+jq -e '
+  .evals[]
+  | select(.id == "STP-009")
+  | any(.assertions[]; test("canonical activation contract"))
+' "$registry" >/dev/null || fail "STP-009 must assert the canonical activation contract."
+
+jq -e '
+  [.evals[] | select(.id == "STP-010")] | length == 1
+' "$registry" >/dev/null || fail "STP-010 must exist exactly once."
+
+jq -e '
+  .evals[]
+  | select(.id == "STP-010")
+  | any(.assertions[]; test("mode-contract, workflow, interview-gate, discover, and output-router context is loaded"))
+' "$registry" >/dev/null || fail "STP-010 must assert same-session mode-contract, workflow, interview-gate, discover, and output-router loading."
+
+if [ "$failures" -gt 0 ]; then
+  exit 1
+fi
+
+printf 'Activation contract check passed: canonical blocks, docs references, post-setup fixtures, and STP-009/STP-010 assertions are aligned.\n'