flowjet 2.1.7__tar.gz → 2.1.9__tar.gz

{flowjet-2.1.7 → flowjet-2.1.9}/CHANGELOG.md

@@ -10,6 +10,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.9] — 2026-10-27
+
+### Changed
+
+- **Refreshed builtin skills bundle.** Shipped two new research skills and
+  retired a stale one: added `autoresearch` (an autonomous research loop with an
+  orchestrator, scoring, and a security checklist) and `oh-my-research` (a
+  structured evidence → synthesis pipeline with scripts and pattern presets),
+  and removed the superseded `research-bootstrap` skill. The `platonic-coding`
+  skill was reworked — its spec/IMPL/WORKFLOW references were tightened, a new
+  `specs-partition.md` reference added, and the old `coding-plan-template.md` /
+  `impl-guide-template.md` drafts dropped in favor of the consolidated template
+  namespace. The top-level `builtin_skills/README.md` (a stale pointer) was
+  removed; skills are still auto-registered via `register_builtin_skill_root`.
+
+## [2.1.8] — 2026-10-26
+
+### Fixed
+
+- **PostgreSQL checkpointer is now wired for the server surface.**
+  `Checkpointers.open()` (the `/v1/responses` + ACP server path) used to warn
+  “Checkpointer backend 'postgresql' is not wired for the flowjet server surface
+  yet” and yield `None`, so thread state never survived a turn — a deployment
+  whose `persistence.default_backend` is `postgresql` silently ran every turn as
+  a fresh conversation. It now builds an `AsyncPostgresSaver` on nano's shared
+  checkpoints pool (`resolve_checkpointer()` → `(None, pool)`), opens the pool,
+  and runs `setup()` once per process under nano's advisory lock
+  (`SharedCheckpointerPool.setup_checkpointer`), so concurrent workers cannot
+  race LangGraph's DDL. The shared pool is deliberately **not** closed on exit
+  (it is process-wide). Failure still degrades to “no persistence” with a
+  warning instead of failing startup; unknown backends keep the old behavior.
+
 ## [2.1.7] — 2026-10-25
 
 ### Added

{flowjet-2.1.7 → flowjet-2.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowjet
-Version: 2.1.7
+Version: 2.1.9
 Summary: FlowJet — a fast, open agent runtime for CLI and HTTP, powered by Soothe
 Project-URL: Homepage, https://github.com/caesar0301/flowjet
 Project-URL: Repository, https://github.com/caesar0301/flowjet

{flowjet-2.1.7 → flowjet-2.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flowjet"
-version = "2.1.7"
+version = "2.1.9"
 description = "FlowJet — a fast, open agent runtime for CLI and HTTP, powered by Soothe"
 readme = "README.md"
 license = { text = "MIT" }

flowjet-2.1.9/src/flowjet/builtin_skills/autoresearch/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Udit Goenka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flowjet-2.1.9/src/flowjet/builtin_skills/autoresearch/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: autoresearch
+description: "Autonomous iteration loop: modify, verify, keep/discard against any metric"
+version: 2.2.2
+---
+
+# Autoresearch — Autonomous Goal-directed Iteration
+
+## Safety Invariants (all subcommands)
+- Never push, publish, or deploy without explicit user approval.
+- Bounded by default. Override with `Iterations: unlimited`.
+- All results logged to `autoresearch/{subcommand}-{YYMMDD}-{HHMM}/` directory.
+- Chain handoff via `handoff.json`. Evals reads `*-results.tsv`.
+
+## Dispatch (bare `$autoresearch`)
+
+Parse the invocation in this order:
+
+| Condition | Mode |
+|---|---|
+| `Metric:` or `Verify:` present | **Classic** — existing metric loop, unchanged |
+| Free-form natural-language goal, no metric/verify | **Orchestrator** — see Orchestrator section |
+| Nothing | **Setup wizard** — interactive config builder |
+| `--classic` flag | Force Classic regardless of goal text |
+| `--auto` flag | Force Orchestrator regardless of goal text |
+
+Print a banner on every invocation: `[autoresearch] mode: classic | orchestrator | wizard`.
+
+## Subcommands
+
+| Command | Does | Default Iterations |
+|---|---|---|
+| `$autoresearch` | Iterate against a metric: modify → verify → keep/discard | 25 |
+| `$autoresearch plan` | Convert a goal into validated Scope, Metric, Verify config | N/A |
+| `$autoresearch debug` | Hunt bugs: hypothesize → test → falsify → repeat | 15 |
+| `$autoresearch fix` | Crush errors one-by-one until zero remain | 20 |
+| `$autoresearch security` | STRIDE + OWASP audit with red-team personas | 15 |
+| `$autoresearch ship` | Ship through 8 phases: checklist → dry-run → deploy → verify | N/A |
+| `$autoresearch scenario` | Generate edge cases across 12 dimensions | 20 |
+| `$autoresearch predict` | 5 expert personas debate before implementation | N/A |
+| `$autoresearch learn` | Scout codebase → generate docs or wiki → validate → fix loop | 10 |
+| `$autoresearch reason` | Adversarial debate with blind judges until convergence | 8 |
+| `$autoresearch probe` | 8 personas interrogate requirements until saturation | 15 |
+| `$autoresearch improve` | Research ICP challenges, discover improvements, generate PRDs | 15 |
+| `$autoresearch evals` | Analyze iteration results: trends, plateaus, regressions | N/A |
+| `$autoresearch regression` | Regression stability gate: baseline vs candidate, verdict STABLE/UNSTABLE | N/A |
+
+## Universal Flags
+
+| Flag | Applies To | Purpose |
+|---|---|---|
+| `Iterations: N` | All looping | Set iteration count |
+| `Iterations: unlimited` | All looping | Opt-in unbounded |
+| `--evals` | All looping | Mid-loop checkpoints + final summary |
+| `--evals-interval N` | All looping | Override checkpoint frequency |
+| `--chain <targets>` | All | Sequential handoff after completion |
+| `--<subcommand>` | All | Shorthand for `--chain <subcommand>` |
+| `--dry-run` | Orchestrator | Print derived config + planned pipeline; no execution |
+| `--max-cycles N` | Orchestrator | Hard ceiling on orchestration cycles (default 50) |
+| `--classic` | Bare `$autoresearch` | Force Classic metric-loop mode |
+| `--auto` | Bare `$autoresearch` | Force Orchestrator mode |
+
+## Orchestrator
+
+Activated when a plain-language goal is given without `Metric:`/`Verify:`. Classifies the goal into a **Goal archetype** — see `references/orchestrator-routing.md` for the archetype table and router decision table.
+
+Resolve every `scripts/...` path below relative to this installed skill directory, never relative to the caller's working directory.
+
+**Two modes based on archetype:**
+- **Orchestration loop** — predicate-bearing archetypes (ship-ready, optimize-metric, fix-broken, harden, build-feature, explore). Goal has a mechanical Success predicate; the loop runs until that predicate is met.
+- **Single-pass dispatch** — subjective/terminal archetypes (document, what-to-build, decide-design). Routes once to the fitting subcommand (learn / improve / reason), lets it self-terminate, then reports. No loop, no Plateau, no ship gate.
+
+### Orchestration Loop Steps
+
+Backed by `scripts/orchestrate.sh` (deterministic seam — all routing logic lives there). Subcommands exposed: `classify`, `next-hop`, `units`, `plateau`, `screen-cmd`, `verdict`, `validate-state`, `screen-state-predicate`.
+
+1. **Classify** — `scripts/orchestrate.sh classify "<goal>"` → archetype label + mode.
+2. **Derive predicate** — reuse `plan` logic to produce a concrete Success predicate: exact shell command + expected output. For `optimize-metric`, run the full plan/wizard derivation internally.
+3. **Confirm** — ONE `request_user_input` showing: archetype, mode, concrete predicate (command + expected output), terminal choice (stop-at-verified vs proceed-to-ship). Misclassifications are caught here, not mid-run.
+4. **Round-0 dry-run** — prove the predicate command runs and returns a value; safety-screen every derived command via `screen-cmd`; print projected cycle budget. Stop here if `--dry-run`.
+5. **Loop** until predicate satisfied:
+   a. Assess state via cheap signals (last `handoff.json`, regression verdict, error count) + affected-test verify.
+   b. `scripts/orchestrate.sh next-hop orchestrator-state.json` → next subcommand.
+   c. Run subcommand (its own bounded inner loop).
+   d. Record per-hop outcome ∈ {progressed, no-op, failed, blocked}.
+   e. Fold hop's `handoff.json` into `orchestrator-state.json`.
+   f. `scripts/orchestrate.sh units` → recompute **Units remaining**.
+6. **Stop conditions** (checked after each hop):
+   - Predicate met → ship gate (only if ship is in the pipeline) else `CONVERGED`.
+   - `scripts/orchestrate.sh plateau orchestrator-state.json` → true → stop + report `PLATEAU`.
+   - Cycles > ceiling (default 50, override `--max-cycles N`) → stop + report `CEILING`.
+   - Hop outcome `blocked`/`failed` with no alternative route → checkpoint + stop + report `BLOCKED`.
+
+### Orchestrator State
+
+`orchestrator-state.json` — orchestrator-owned, additive. Tracks: goal, archetype, predicate, terminal-choice, `units_remaining` history, cycle count, per-hop pipeline log with outcomes, current incumbent. Each hop's `handoff.json` is unchanged (single-hop bridge); the orchestrator reads it and folds it in. Two clearly-owned state objects, no overlap.
+
+### Orchestrator Safety Invariants
+
+- **Never auto-approve ship/deploy/push.** The orchestrator never passes `--auto` to `ship`; deploy always requires explicit user approval.
+- **Data-migration behind anchored DB-URL allowlist.** Reuses regression's allowlist — host must be `localhost`/`127.0.0.1`/container hostname, or database name carries `_test`/`_ci` suffix. Bare substring match does not qualify. Anything else refused.
+- **screen-cmd on every derived command** — run before the loop starts AND on every command read from a persisted state file on resume. Persisted commands are never trusted; resume re-screens the pinned predicate via `screen-state-predicate` and refuses on `refuse`.
+- **No un-screened commands mid-loop.** The autonomous loop cannot introduce new shell commands that bypass `screen-cmd`.
+- **Predicate pinned, not re-derived.** Round-0 writes the derived Success predicate verbatim into `orchestrator-state.json`; every cycle and every resume reuses that exact string so "done" is reproducible across runs.
+- **Validate the ledger before routing.** `validate-state` gates `orchestrator-state.json` (required fields + coarse types); a malformed ledger is not trusted to route from.
+- **Independent verify before convergence.** High-impact changes accepted on the working signal set `pending_verify`; `next-hop` routes to a `verify` hop (held-out / adversarial check) before `DONE` or ship. The verify hop never auto-approves ship.
+- **Unknown-units cycles excluded from Plateau counter.** A cycle where `units` returns `unknown` (e.g. runner crash) is not counted as zero-progress; repeated `unknown` routes to `BLOCKED`.

flowjet-2.1.9/src/flowjet/builtin_skills/autoresearch/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Autoresearch"
+  short_description: "Autonomous goal-directed iteration engine"
+  brand_color: "#7C3AED"
+  default_prompt: "Set a goal, define a metric, let Codex loop until done"
+
+policy:
+  allow_implicit_invocation: true

flowjet-2.1.9/src/flowjet/builtin_skills/autoresearch/autoresearch.md

@@ -0,0 +1,110 @@
+---
+name: autoresearch
+description: "Autonomous iteration loop: modify, verify, keep/discard against any metric"
+argument-hint: "[Goal: <text>] [Scope: <glob>] [Metric: <text>] [Verify: <cmd>] [Guard: <cmd>] [Iterations: N] [--evals]"
+---
+
+EXECUTE IMMEDIATELY — do not deliberate before reading this protocol.
+
+## Parse Arguments
+
+Extract from $ARGUMENTS:
+- `Goal:` — what to improve
+- `Scope:` or `--scope` — file globs
+- `Metric:` — what to measure
+- `Direction:` — higher_is_better (default) or lower_is_better
+- `Verify:` — shell command that outputs a number
+- `Guard:` — optional safety command (must always pass)
+- `Iterations:` or `--iterations` — integer N for bounded mode (default: 25). "unlimited" for unbounded.
+- `--evals` — enable mid-loop checkpoints
+- `--evals-interval N` — checkpoint frequency override
+- `--chain <targets>` — comma-separated downstream commands
+
+## Setup (if required context missing)
+
+If Goal, Scope, Metric, or Verify missing → use request_user_input (single batched call):
+  Q1 (Goal): "What do you want to improve?"
+  Q2 (Scope): "Which files?" — suggest globs from project
+  Q3 (Metric+Verify): "How to measure? Provide a shell command that outputs a number"
+  Q4 (Guard): "Safety command that must always pass?" — options: test cmd, build cmd, skip
+If ALL provided inline → skip setup, proceed directly.
+
+## Precondition Checks
+
+1. Verify git repo exists (`git rev-parse --git-dir`)
+2. Check clean working tree (`git status --porcelain`) — warn if dirty
+3. Check for stale lock files, detached HEAD
+4. If Guard set → run Guard to establish guard baseline
+5. Fail fast on any critical issue. Warn on non-critical.
+
+## Verify Safety Screen
+
+Before first dry-run, screen Verify command for: rm -rf, fork bombs, curl|sh, embedded credentials, outbound writes. Block dangerous commands.
+
+## Establish Baseline (Iteration 0)
+
+1. Run Verify command → extract numeric metric
+2. Record as iteration 0 in TSV: `0\t{timestamp}\t{commit}\t{metric}\t0.0\t{guard}\t-\tbaseline\tinitial state`
+3. Create output directory: `autoresearch/loop-{YYMMDD}-{HHMM}/`
+4. Write TSV header: `# metric_direction: {direction}\niteration\ttimestamp\tcommit\tmetric\tdelta\tguard\tguard-metric\tstatus\tdescription`
+
+## Iteration Loop
+
+For each iteration (1 to max_iterations, or unbounded):
+
+### Phase 1: Review (read git history as memory)
+- Read last 10-20 lines of results TSV
+- Run `git log --oneline -20` — see what worked/failed
+- If last iteration was "keep" → run `git diff HEAD~1` to see what improved metric
+- Identify: what worked, what failed, what's untried
+
+### Phase 2: Modify
+- Based on review, make ONE focused change to improve the metric
+- Change must be atomic — one logical unit of work
+
+### Phase 3: Commit
+- Stage and commit with `experiment: {description}` prefix
+- Record commit SHA
+
+### Phase 4: Verify
+- Run Verify command → extract new metric value
+- Calculate delta from previous iteration
+- Metric improved (correct direction) → candidate for keep
+
+### Phase 5: Guard (if configured)
+- Run Guard command. If fails → revert regardless of metric improvement
+
+### Phase 6: Decide
+- **keep** — metric improved, guard passed → commit stays
+- **discard** — metric worsened → `git revert HEAD --no-edit`
+- **crash** — verify/guard command failed → `git revert HEAD --no-edit`
+- **no-op** — no change made this iteration
+- **hook-blocked** — git hook blocked the commit
+- **metric-error** — verify output not a valid number → `git revert HEAD --no-edit`
+
+### Phase 7: Log
+Append row to TSV: iteration, timestamp, commit/-, metric, delta, guard status, guard-metric, status, description
+
+### Eval Checkpoint
+If --evals: check if current_iteration % interval == 0 → run checkpoint analysis.
+
+### Bounded Check
+If bounded: current_iteration >= max_iterations → exit loop, print summary.
+
+## Summary (after loop ends)
+
+Print: total iterations, kept/discarded counts, starting metric → final metric, improvement %, top 3 most effective changes.
+
+## Eval Checkpoint (--evals flag)
+
+If --evals present:
+- Compute interval: floor(max_iterations / 3), min 1. Fixed 10 if unbounded. Override: --evals-interval N.
+- Every {interval} iterations, pause and analyze current results TSV.
+- Print: `--- Eval Checkpoint (iterations {X}-{Y}) ---\nMetric: {start} → {end} ({delta}) | Kept: {n}/{total} | Trend: {up/flat/down}\n{one-line recommendation}\n---`
+- If plateau 3+ checkpoints → recommend early stop.
+- At loop end → full evals summary to evals-summary.md in output directory.
+
+## Chain Handoff
+
+After completion, write handoff.json to output directory: version "2.1.0", source "loop", timestamp, status (COMPLETE|USER_INTERRUPT|BOUNDED|ERROR), results_tsv path, findings[], config{goal, scope, metric, direction, verify}.
+Invoke next target in --chain order. Propagate --evals flag.

flowjet-2.1.9/src/flowjet/builtin_skills/autoresearch/debug.md

@@ -0,0 +1,97 @@
+---
+name: autoresearch:debug
+description: "Hunt bugs with scientific method: hypothesize, test, falsify, repeat"
+argument-hint: "[Scope: <glob>] [Symptom: <text>] [Iterations: N] [--fix] [--evals]"
+---
+
+EXECUTE IMMEDIATELY.
+
+## Parse Arguments
+
+Extract from $ARGUMENTS:
+- `Scope:` or `--scope` — file globs to investigate
+- `Symptom:` or `--symptom` — error message or behavior description
+- `Iterations:` or `--iterations` — default 15. "unlimited" for unbounded.
+- `--fix` — shorthand for `--chain fix`
+- `--severity` — filter: critical, high, medium, low
+- `--technique` — force specific technique
+- `--evals`, `--evals-interval N`, `--chain`
+
+## Setup (if required context missing)
+
+If Scope and Symptom both missing:
+1. Auto-scan: run tests, lint, typecheck to detect existing failures
+2. request_user_input (single batch):
+   Q1 (Issue): "What's the problem?" — hunt all bugs, specific error, failing tests, CI failure, performance
+   Q2 (Scope): "Which files?" — suggested globs + entire codebase
+   Q3 (Depth): "How deep?" — quick (5), standard (15), deep (30+), unlimited
+   Q4 (After): "When bugs found?" — report only, find and fix (--chain fix), chain to other, ask each time
+If all provided → skip.
+
+## Investigation Techniques
+
+| Technique | When to Use |
+|---|---|
+| Binary search | Know when it worked, find when it broke |
+| Differential | Compare working vs broken state |
+| Minimal reproduction | Simplify to smallest failing case |
+| Trace | Follow execution path through code |
+| Pattern search | Grep for known anti-patterns |
+| Working backwards | Start from error, trace to root cause |
+
+## Establish Baseline (before loop)
+
+1. Auto-scan for failures if no symptom provided
+2. Create output directory: `autoresearch/debug-{YYMMDD}-{HHMM}/`
+3. TSV header: `# metric_direction: higher_is_better\niteration\ttimestamp\thypothesis\tstatus\ttechnique\tevidence\tfile_line`
+4. Metric = cumulative confirmed findings count
+
+## Iteration Loop
+
+### Phase 1: Review Context
+- Read results TSV (past findings)
+- Assess: what's been tested, what vectors remain
+- If no hypotheses left → early stop
+
+### Phase 2: Hypothesize
+- Form ONE specific, falsifiable hypothesis
+- Format: "I hypothesize that {X} because {evidence}. Test by {Y}."
+- Hypothesis must be testable and different from all previous
+
+### Phase 3: Investigate
+- Apply appropriate technique for this hypothesis
+- Read relevant code, run targeted tests, check logs
+- Collect evidence (file:line references required)
+
+### Phase 4: Classify
+- **confirmed** — hypothesis correct, bug found with evidence
+- **disproven** — hypothesis wrong, evidence against it
+- **inconclusive** — can't prove or disprove, needs different approach
+
+### Phase 5: Log
+Append to TSV: iteration, timestamp, hypothesis, status, technique, evidence, file_line
+
+### Eval Checkpoint
+If --evals: check if current_iteration % interval == 0 → run checkpoint analysis.
+
+### Bounded Check
+If bounded: current_iteration >= max_iterations → exit loop, print summary.
+
+## Summary
+
+Print: total hypotheses tested, confirmed/disproven/inconclusive counts, all confirmed bugs with severity and file:line.
+
+## Eval Checkpoint (--evals flag)
+
+If --evals present:
+- Compute interval: floor(max_iterations / 3), min 1. Fixed 10 if unbounded. Override: --evals-interval N.
+- Every {interval} iterations, pause and analyze current results TSV.
+- Print: `--- Eval Checkpoint (iterations {X}-{Y}) ---\nFindings: {confirmed} confirmed | Trend: {up/flat/down}\n{one-line recommendation}\n---`
+- If plateau 3+ checkpoints (no new confirmed) → recommend early stop.
+- At loop end → full evals summary to evals-summary.md in output directory.
+
+## Chain Handoff
+
+After completion, write handoff.json to output directory: version "2.1.0", source "debug", timestamp, status (COMPLETE|USER_INTERRUPT|BOUNDED|ERROR), results_tsv path, findings = confirmed bugs with severity + file:line, config{scope, symptom}.
+If --fix flag → chain to fix automatically.
+Invoke next target in --chain order. Propagate --evals flag.

flowjet-2.1.9/src/flowjet/builtin_skills/autoresearch/evals.md

@@ -0,0 +1,118 @@
+---
+name: autoresearch:evals
+description: "Analyze iteration results: trends, plateaus, regressions, recommendations"
+argument-hint: "[path/to/results.tsv] [--format text|json|md]"
+---
+
+EXECUTE IMMEDIATELY.
+
+## Parse Arguments
+
+Extract from $ARGUMENTS:
+- Positional path to a specific TSV file
+- `--format` — output format: text (default console), json, md (markdown file)
+- `--compare <path>` — (v2.2.0 placeholder, not yet implemented)
+
+## Input Discovery
+
+1. If path provided → use that TSV directly
+2. If no path → scan current directory + `autoresearch/*/` for `*-results.tsv` files
+3. If multiple found → request_user_input: "Which results to analyze?" — list found files
+4. If none found → request_user_input: "Provide path to results TSV"
+5. Also scan project root for v2.0.03 legacy TSV files (backward compat)
+
+## Parse TSV
+
+1. Read line 1: extract `# metric_direction: higher_is_better|lower_is_better` comment
+   - If missing → infer from column names (metric/error_count → guess, or ask user)
+2. Read line 2: header row → detect available columns
+3. Read remaining lines: data rows
+4. Handle missing `timestamp` column gracefully (v2.0.03 compat)
+
+## Column Detection & Analysis
+
+Activate analysis based on columns present in header:
+
+| Column | Analysis |
+|---|---|
+| `metric` | Trend direction, plateau detection (3+ flat iterations), diminishing returns, biggest single-iteration jumps |
+| `delta` | Per-iteration efficiency, cumulative improvement, effort-to-gain ratio |
+| `status` | Keep/discard rate, crash frequency, success streaks, failure clusters, longest winning streak |
+| `guard` + `guard-metric` | Guard failure rate, metric-improved-but-guard-failed analysis |
+| `severity` | Severity distribution (critical/high/medium/low/info), critical discovery rate per iteration |
+| `hypothesis` + `status` | Confirmation rate, investigation efficiency, most productive techniques |
+| `commit` | File hotspot analysis (cross-ref with `git diff` for kept commits), change size correlation |
+| `technique` | Technique effectiveness ranking |
+| `dimension` | Dimension coverage completeness (X/12) |
+| `candidate_label` + `judge_verdict` | Convergence speed, oscillation count |
+| `error_type` | Error category distribution, fix rate per category |
+| `classification` | New vs extension vs duplicate ratio, saturation curve |
+| `convergence_count` | Convergence trajectory |
+
+Unknown columns: report presence but skip analysis. Forward-compatible with future subcommands.
+
+## Report Structure
+
+```
+## Evals Summary — {subcommand} ({N} iterations)
+
+### Key Metrics
+- Total iterations: N | Kept: X | Reverted: Y | Revert rate: Z%
+- Starting metric: A | Final metric: B | Improvement: C%
+
+### Trend Analysis
+- Metric progression: [description of trajectory]
+- Plateau detected at iteration N (metric stable for M iterations)
+- Biggest win: iteration X (+delta, description)
+- Biggest loss: iteration Y (-delta, description)
+- Diminishing returns: [after iteration N, average delta dropped below threshold]
+
+### Patterns
+- What types of changes succeeded: [extracted from descriptions of kept iterations]
+- What types of changes failed: [extracted from descriptions of discarded iterations]
+- File hotspots: [files changed most in kept iterations, if commit data available]
+- Technique effectiveness: [ranked by confirmation rate, if technique column present]
+
+### Recommendation
+- [continue / stop / change strategy — based on trend, plateau, revert rate]
+- [specific actionable suggestion based on pattern analysis]
+```
+
+## Output
+
+- Console: structured report (30-50 lines)
+- If `--format md` → write `evals-summary.md` in same directory as input TSV
+- If `--format json` → write `evals-summary.json` with structured data
+
+## Mid-Loop Checkpoint Protocol (for --evals flag in other commands)
+
+This section documents the checkpoint protocol that looping commands embed:
+
+- **Adaptive interval:** `floor(max_iterations / 3)`, minimum 1. Fixed 10 for unbounded. Override: `--evals-interval N`.
+- **Checkpoint format (5 lines max):**
+  ```
+  --- Eval Checkpoint (iterations {X}-{Y}) ---
+  Metric: {start} → {end} ({delta}) | Kept: {n}/{total} | Trend: {up/flat/down}
+  {one-line recommendation}
+  ---
+  ```
+- **Early stop recommendation:** if plateau detected for 3+ consecutive checkpoints
+- **Final summary:** at loop end, produce full evals report to console + evals-summary.md
+
+### Adaptive Interval Examples
+
+| Subcommand | Default Iterations | Interval | Checkpoints At |
+|---|---|---|---|
+| reason | 8 | 2 | 2, 4, 6, 8 |
+| learn | 10 | 3 | 3, 6, 9, final |
+| debug/security | 15 | 5 | 5, 10, 15 |
+| fix/scenario | 20 | 6 | 6, 12, 18, final |
+| core | 25 | 8 | 8, 16, 24, final |
+| unbounded | unlimited | 10 | every 10 |
+
+## Backward Compatibility
+
+- v2.0.03 TSV files: column names preserved, `timestamp` absence handled gracefully
+- Fuzzy column matching: `metric_value` → `metric`, `error_count` → `metric`
+- Files in project root (not `autoresearch/` subdirectory) → discovered during scan
+- v2.0.03 status values all supported: baseline, keep, keep (reworked), discard, crash, no-op, hook-blocked, metric-error

flowjet-2.1.9/src/flowjet/builtin_skills/autoresearch/fix.md

@@ -0,0 +1,102 @@
+---
+name: autoresearch:fix
+description: "Crush errors one-by-one until zero remain: tests, types, lint, build"
+argument-hint: "[Target: <cmd>] [Scope: <glob>] [Guard: <cmd>] [Iterations: N] [--evals] [--from-debug]"
+---
+
+EXECUTE IMMEDIATELY.
+
+## Parse Arguments
+
+Extract from $ARGUMENTS:
+- `Target:` or `--target` — command that shows errors (e.g., `npm test`, `tsc --noEmit`)
+- `Scope:` or `--scope` — file globs to modify
+- `Guard:` or `--guard` — safety command (must always pass)
+- `Iterations:` or `--iterations` — default 20. "unlimited" for unbounded.
+- `--from-debug` — read handoff.json from previous debug run
+- `--category` — filter: test, type, lint, build
+- `--evals`, `--evals-interval N`, `--chain`
+
+## Setup (if required context missing)
+
+If Target and Scope both missing:
+1. Auto-detect failures: run test suite, type checker, linter, build
+2. Present results via request_user_input (single batched call):
+   Q1 (Fix What): "Found [N] test failures, [M] type errors, [K] lint errors. Fix what?" — everything, only tests, only types, only lint
+   Q2 (Guard): "Safety command that must always pass?" — npm test, tsc, npm run build, skip
+   Q3 (Scope): "Which files can I modify?" — suggested globs from error locations + all
+   Q4 (Launch): "Ready?" — fix until zero, fix with limit, cancel
+If all provided → skip setup.
+If --from-debug → read handoff.json for scope and findings.
+
+## Precondition Checks
+
+Verify: git repo exists, clean working tree, no lock files, no detached HEAD. Fail fast on critical issues.
+
+## Establish Baseline (Iteration 0)
+
+1. Run Target command → count errors (metric = error count, direction = lower_is_better)
+2. Record baseline in TSV
+3. Create output directory: `autoresearch/fix-{YYMMDD}-{HHMM}/`
+4. TSV header: `# metric_direction: lower_is_better\niteration\ttimestamp\terror_type\terror_fixed\tcommit\tmetric\tdelta\tguard\tstatus\tdescription`
+
+## Iteration Loop (until zero errors or max_iterations)
+
+### Phase 1: Review
+- Read results TSV + git log
+- Run Target to get current error list
+- If error count == 0 → exit loop (SUCCESS)
+
+### Phase 2: Prioritize
+Order: crash/fatal → test failures → type errors → lint → warnings.
+Within category: easiest first (single-file fixes before cross-file).
+
+### Phase 3: Fix ONE Thing
+- Pick the highest-priority error
+- Make ONE focused fix (atomic — addresses exactly one error)
+- Record error type and which error was fixed
+
+### Phase 4: Commit
+- Stage and commit: `experiment: fix {error_type} — {description}`
+
+### Phase 5: Verify
+- Run Target → count errors → compute delta
+- Expected: error count decreased by 1 or more
+
+### Phase 6: Guard
+- If Guard set → run Guard. If fails → revert.
+
+### Phase 7: Decide
+- **keep** — error count decreased AND guard passes
+- **keep (reworked)** — fix needed adjustment, second attempt worked
+- **discard** — error count same/increased → `git revert HEAD --no-edit`
+- **crash** — target/guard command failed → revert
+- **hook-blocked** — git hook blocked the commit
+- **metric-error** — target output not parseable → revert
+
+### Phase 8: Log
+Append row: iteration, timestamp, error_type, error_fixed, commit/-, metric (error count), delta, guard, status, description
+
+### Eval Checkpoint
+If --evals: check if current_iteration % interval == 0 → run checkpoint analysis.
+
+### Bounded Check
+If bounded: current_iteration >= max_iterations → exit loop, print summary.
+
+## Summary
+
+Print: total errors fixed, remaining errors, error types distribution, fix success rate.
+
+## Eval Checkpoint (--evals flag)
+
+If --evals present:
+- Compute interval: floor(max_iterations / 3), min 1. Fixed 10 if unbounded. Override: --evals-interval N.
+- Every {interval} iterations, pause and analyze current results TSV.
+- Print: `--- Eval Checkpoint (iterations {X}-{Y}) ---\nErrors: {start} → {end} ({delta}) | Kept: {n}/{total} | Trend: {up/flat/down}\n{one-line recommendation}\n---`
+- If plateau 3+ checkpoints → recommend early stop.
+- At loop end → full evals summary to evals-summary.md in output directory.
+
+## Chain Handoff
+
+After completion, write handoff.json to output directory: version "2.1.0", source "fix", timestamp, status (COMPLETE|USER_INTERRUPT|BOUNDED|ERROR), results_tsv path, findings = unfixed errors, config{target, scope, guard}.
+Invoke next target in --chain order. Propagate --evals flag.