fak

Perform a full versioned release — bump version, draft release notes, commit, tag, push, and create the GitHub release page. Reads `.claude/project.yaml` for the project's release-context and version-bump helpers; the skill text is universal, the helpers are project-supplied. Use when the user says "cut a release", "ship vX.Y.Z", "release", or after a shippable phase.

One repeatable pass that keeps fak's growing namespace CRYSTAL-CLEAR - each similar-sounding concept (cache / vCache / KV cache / cachemeta / the provider prompt-cache; guard vs gate; the two witnesses) given one canonical name, a written definition, and an explicit line drawn against the siblings it is confused with. Runs the concept-disambiguation scorecard (tools/concept_disambiguation_scorecard.py) over a data dir of confusable-concept rows cross-checked against the tree (the grounding token must appear in the production corpus; the glossary anchor must exist; a distinct_from reference must resolve), turns each HARD defect into a required fix (rename a true canonical collision, write a missing definition, draw + anchor a missing distinction, replace a fabricated grounding) and each uncovered tree token into a coverage row to ADD, retires disambiguation-debt worst-first, re-measures to PROVE the debt dropped, and commits only the scorecard lane by explicit path. The NAMING-clarity counterpart of conflation

One repeatable pass over README.md — the front door — that keeps ONLY the most important points current and honestly framed. Runs the freshness auditor (tools/readme_freshness_audit.py), turns each FAIL into a required edit and each WARN into a judgment call, applies the three front-page laws (SOTA-vs-us-never-naive, 6th-grade/Feynman-but-accurate, wide-audience), re-stamps the readme-verified marker, and commits ONLY README.md (+ the tool) by explicit path. Use after a release / version bump, after a headline number changes, when a link dies, or on a /loop cadence to keep the front page from rotting. The README's checking layer, the way curate-cluster is the index's.

Commit finished work cleanly on the shared trunk — lint the subject with `fak commit --preview`, then stage-and-commit EXACTLY your paths in one locked step via `fak commit --path … -m "…"`, verify the landed path-set and message are yours, and push when asked. Mechanizes the repo's "commit clean by default" mantra (trunk-only, explicit pathspec, DCO sign-off, Conventional-Commits subject with a bindable `(fak <leaf>)` stamp). Use when the user says "commit this", "ship my work", "commit cleanly", "land my change", or when green work is finished and ready to land on the shared trunk.

Flag content-redundant SKILL.md pairs as merge candidates — pairwise body cosine similarity over the skill pack, sorted highest-first. Use when the pack feels bloated or two skills seem to overlap, to find "skills A and B are N% token-similar — consider merging" candidates before a skill-lifecycle archive pass. Proposal only — never merges, edits, or deletes a skill.

Bind a done-claim to a GREEN test run of the changed package, not just diff shape. Use after a commit claims a package/feature is done and you want to run that commit's affected tests and report CLAIM_TEST_GREEN / CLAIM_TEST_RED / CLAIM_TEST_UNRUN before folding the claim as true.

The generic scoring doctrine the whole fak scorecard family instantiates — how to BUILD a new deterministic, tree-cross-checked, debt-driving scorecard and how to RUN any of them as a repeatable RSI pass. Every sibling (code-quality, docs, doc-appeal, seo, demo-quality, repo-hygiene, observability, learning, industry, agent-readiness, product, persona) is the same machine pointed at a different surface: pure KPIs over a data-dir or the git-tracked tree, cross-checked against reality so the score can't be gamed by editing data, folded into one *-debt integer + an A–F grade, emitting a control-pane payload, retired worst-first by ADDING the real thing, and proven with a before/after compare. Use when adding a NEW scorecard for a surface that isn't measured yet, when refining the scoring method itself, or when you need the shared contract behind quality-score / appeal-score / industry-score / agent-readiness / product-score / persona-score.

One repeatable pass that keeps fak the path of least resistance for an AI agent — Claude Code, OpenAI Codex, Cursor, an MCP client — to discover, adopt, and build on. Runs the agent-readiness scorecard (`fak score agent-readiness`, backed by internal/agentreadinessscore) over the git-tracked tree, turns each HARD defect into a required affordance to ADD (a missing agents.md entry point, a missing harness config, a dead orientation link, no copy-pasteable first command, no install one-liner, an untagged claim, a missing per-agent recipe, a missing leaf scaffold, an unsurfaced guardrail, a missing contributor contract), retires friction-debt worst-step-first, re-measures + regenerates the snapshot to PROVE the debt dropped, and commits only the scorecard lane by explicit path. The INWARD agent-experience counterpart of industry-score (competitive) and repo-hygiene (structure). Use after a change to an agent surface (AGENTS.md, llms.txt, CLAIMS.md, the integration recipes, the guards), when onboarding a new agen

One repeatable pass that keeps fak serving the top-10 personas who land on it — from the free-tier dev who downloads a binary and won't read a word, through the infra engineer who has to operate it, to the researcher who wants to reproduce it. Runs the persona-readiness scorecard (tools/persona_readiness_scorecard.py) over the git-tracked tree, turns each unmet HARD affordance into a required thing to ADD (a prebuilt-binary release, a deployment guide, a determinism witness, a refusal vocabulary, a green gate), retires persona-debt worst-served-first, re-measures + regenerates the snapshot to PROVE the debt dropped, and commits only the scorecard lane by explicit path. The go-to-market counterpart of agent-readiness (one persona: the AI agent), product (the concepts), and industry-score (the field). Use after a change to a persona's entry path (a release, a deploy doc, an integration recipe, the policy spec), when adding a persona to the roster, or on a /loop cadence to keep every front door open.

The agent door to unattended data collection — answer "what is the single most important datum I can collect on THIS box right now?" and then collect it on a loop. Wraps `fak nightrun`, which probes the local box (gpu/weights/datasets/creds), ranks the feasible-here collection tasks (the benchmark grid PLUS the curated open-witness backlog) by novelty × value × staleness, and closes the loop into a durable runtime ledger (.fak/nightrun/collected.jsonl, gitignored so a collection tick never dirties the shared tree). Use when the operator says "run it all night", "collect the next most important data", "what benchmark should I run on this machine", "start an overnight data-collection run", or when an agent on a fresh box (a Mac verify node, an A100, an H200) needs to know — without reading the whole repo — what data is worth gathering here.

Refresh the recent-operational cachevalue numbers in a guarded doc (e.g. docs/integrations/fable5-more-usage-for-free.md) when this-week's telemetry has moved on. Re-derives the frozen snapshots from live `fak cachevalue report`, reconciles the doc's rendered numbers + snapshot_date to the fresh capture, and re-runs the hermetic audit until it is clean. The audit (tools/cachedoc_numbers_audit.py, gated in `make cachedoc-numbers-lint`) binds every rendered number to a committed snapshot field and checks the arithmetic invariants the doc asserts — this skill is the maintenance loop that keeps that binding true as the fleet/dev windows advance. Distrusts the stale doc: the new numbers come from a fresh `--json` capture, never from editing the visible prose in place. Use when the audit WARNs on staleness, when a cachevalue doc looks out of date, or on a cadence to keep the operational docs honest.

One repeatable pass that turns "look at <repo>" into scoped, witnessed, license-clean, FILED backlog. When someone drops anything that names a body of code — a GitHub URL, a local checkout, a monorepo subtree, a single file, an npm/pypi/crates package, a paper-with-code / arXiv link, a tarball, a PR/diff, or a bare "study this repo" / "what can we learn from X" / "borrow from <repo>" with no URL at all — this drives the whole flow end to end. Acquire the source into scratch (never the tree) and PIN the commit SHA; read the CODE not the pitch, DEEP by default (fan parallel readers across load-bearing modules + tests + recent commits, then a completeness-critic pass — not a README skim) AND reconstruct THEIR design rationale + user world (who they built it for, what they optimized for, what constraint they were under); extract MANY candidate borrows, each grounded at a real source `path:line@sha` and ABLATED to the one axis it optimizes; decide borrow-vs-integrate with a license + attribution check; DECOMPOSE i

One repeatable pass that keeps agent-steer prose leading with the AFFORDANCE, not the prohibition. Runs `fak score negframe` over the steer-prose corpus (AGENTS.md, CLAUDE.md, the skills, or explicit paths), reads the negframe_debt (mechanical negatives with an unambiguous positive rewrite) plus the judgement-tier soft signal, retires the mechanical debt worst-first by applying the suggested reframe, checks the `--since <ref>` ratchet before landing a steer-prose change, re-measures to PROVE the debt dropped, and commits only the scorecard lane by explicit path. Use after editing AGENTS.md/CLAUDE.md/a skill, when a new negatively-framed directive is proposed, or on a /loop cadence to keep steer prose reading as "do this" instead of "don't do that."

One repeatable pass that decides whether a GitHub ticket is a single dispatchable unit of agent work — or names exactly which of the six scope axes it fails and how to fix it. Wraps the native scope toolkit (`fak issue contract` for structure/size/routing, `fak dispatch issue-smallness-lint` for atomicity, `fak issue cohort` for batch/wave placement) and reads back one verdict per issue: DISPATCHABLE, or TRIAGE (add the missing section), DECOMPOSE (S2+ epic → leaves), or SPLIT (two deliverables / not one witness). Read-only — it fetches, lints, and proposes the fix; editing the issue, splitting it into children, or relabeling is a separate operator-approved step. Use when the operator says "is this ticket ready to dispatch", "scope issue #N", "why won't this issue dispatch", "check the backlog is well-scoped", "split this epic", or on a /loop cadence before a dispatch wave.

The super-loop-family member that ASKS instead of ships. It launches detached workers whose only job is to ask 5–10 hard, honest questions about what the repo is doing — the question no other agent has asked, the one everyone's afraid to ask, the one that's opposite what the repo claims, the steelman of the other side — and append them to a durable ledger (docs/questions/asked.jsonl). A SEPARATE next-step loop, in a SEPARATE context window, turns qualifying questions into gh tickets for actual work. Use when the operator says "ask the hard questions", "what aren't we asking", "run a question loop", "start the asking loop", "question what we're doing", or wants a standing cadence of provocations rather than more issue-draining. NOT idea-scout (external feeds), NOT /super-loop (ships fixes), NOT the Go superloop.Super interior node.

Compact the context window and prune the memory store when a session grows too long.

Score the repo quality and emit a report card.

One repeatable pass over the open GitHub issue backlog — classify every open issue (needs-priority / needs-kind / needs-area, orphaned P0-P1, stale, dormant question), rank them into a deterministic "do next" order, propose the mechanical gardening moves (mark stale, close dormant questions), and apply them only on operator approval. The helper is read-only; writing labels, comments, or closes is gated. Use when the operator says "triage the issues", "what should I work on next", "garden the backlog", "the issue labels are a mess", "close stale issues", or on a /loop cadence to keep the backlog honest.

One repeatable pass that turns an outward field idea into grounded backlog WITHOUT guessing whether fak already has it — the dogfood-witnessed capability-import loop. Before filing "fak should add X" from a named external system (Letta/MemGPT, Mem0, Zep/Graphiti, Cognee, vLLM/SGLang, a dated paper) or a row from the RESEARCH-*/industry field scans, it DOGFOODS fak's own self-query surface (`fak_feature_query` / `fak capabilities` / `fak index docs|leaves|verbs|claims`) to witness PRESENT / PARTIAL / ABSENT, grounds each real gap in a file:line seam, and files epic-anchored issues carrying the named source + the dogfood witness + the seam + a first checkable step. The human-curated, witness-first counterpart to the automated `idea-scout` (which dedups a candidate only against already-filed issues — a seen-cache, issue-body stamp, and title-Jaccard index — and never asks fak what it already has in the codebase); the product/agent-capability counterpart of `sota-check` (kernels) and `industry-score` (the competi

Witnessed lifecycle for the project skill pack — usage-telemetry sidecar, value/idle-driven auto-archive (never delete, restorable), pin-exemption, journaled reversible transitions. Use to record skill usage, review archive verdicts, archive or restore a skill, or pin one exempt. Max action is archive; nothing is ever deleted.

Run recurring `dos-dispatch` cycles, switching to `dos-replan` when the backlog drains and stopping on the kernel's loop verdict. Use for unattended dispatch->replan->dispatch work across disjoint lanes.

Compact the context window and prune the memory store so a long session stays under budget. Use when the context is getting large.

Score the repository's code quality and emit a ranked table of findings. Read-only.

One repeatable pass that keeps every number and status fak reports PROVENANCE-HONEST - each value labeled by what fak CONTROLS (witnessed/authored) vs what it only OBSERVES (relayed from an external party), and no bad observed value blamed on a fak action. Runs the conflation scorecard (`fak conflation-scorecard`, the Go verb backed by internal/conflationscore) over the fact-reporting surfaces (Prometheus metric help, the fak guard exit summary), turns each HARD defect into a required edit (label an unlabeled external value OBSERVED; correct prose that attributes a provider-side miss to a fak action), retires conflation-debt worst-first WITHOUT changing any number or logic, re-measures to PROVE the debt dropped, and commits only the scorecard lane by explicit path. The truth-maintenance counterpart of appeal-score (prose voice) and observability (what is measured). Use after adding a metric/exit-summary that reports an external value, when a dashboard mislabels whose number it is, or on a /loop cadence to kee

One repeatable pass that keeps fak light to DRIVE — the operator-facing counterpart of steerability-score. Runs the operator-heaviness scorecard (`fak operator heaviness`) over the live operator surface (the cmd/fak dispatch table, the front-door verb's flag set, the dos.toml refusal vocabulary, and whether the doc map makes the steering surfaces discoverable), reads the unbounded `heaviness_pressure` headline plus the HARD `heaviness_debt` gate, drives pressure DOWN and HARD debt to zero by REAL surface consolidation (group verbs, cut front-door flags, fold refusal reasons, wire a missing doc-map entry or appeal channel) — never by gaming a detector, re-measures to PROVE the pressure fell, regenerates the committed snapshot, and commits only the touched lane by explicit path. The operator-surface counterpart of steerability-score (package-graph shape) and the steering-effort companion of quality-score (code defects). Use after a verb, a front-door flag, or a refusal reason is added, when the dispatch table "

One repeatable pass that makes the milestone report's CLIMB and ROADMAP retirable by the RSI loop — the milestone counterpart of quality-score (code) and stability-score (trust under iteration). Runs the milestone scorecard (`fak milestone-scorecard --json`) over the report's OWN two dimensions — the distance-from-MATURED climb shortfall across the M0..M7 support-maturity grid PLUS the un-progressed tracked-epic roadmap gaps — folds them into one deterministic milestone_debt integer + a worst-first milestone_worklist, retires debt worst-first (climb the lowest-rung cell to M4, then close the most-open discrete epic), re-pins the climb ratchet on a real climb improvement, re-measures with --compare to PROVE the debt dropped, and commits only the milestone lane by explicit path. COMPOSES — does NOT duplicate — support-maturity (which fences each cell to its regime ceiling); milestone_debt scores raw distance-to-MATURED across the grid as the headline climb, alongside the roadmap. Use after a cell climbs a rung,

One repeatable pass that makes a doc read like a person wrote it, not a model. Runs the doc-appeal scorecard (tools/doc_appeal_scorecard.py), turns each HARD defect into a required edit (em-dash flood, bold-emphasis flood, run-on / overlong sentences, walls of text, stacked "X, not Y" contrast frames, a dense or unanchored lead, LLM-scaffolding phrases) and each SOFT signal into a judgment call, retires appeal-debt worst-axis-first WITHOUT changing any claim, number, or link, re-measures to PROVE the debt dropped, and commits only the doc lane by explicit path. The prose-voice counterpart to refresh-readme (freshness) and quality-score (code). Use to de-LLM-ify the README or any reader-facing prose doc, or on a /loop cadence to keep the front door human.

Apply the two new-work defaults — ship the minimal WORKING end-to-end spine first (or file the spine as its own issue), then fan out the 3..50+ follow-on QA/dogfood/productization backlog at creation time via `fak issue fanout`. Use when starting any new feature/leaf/verb/demo, when a spine just shipped, when asked to "fan out", "file follow-ons", "create the e2e spin", or at the end of a super-loop turn that landed new work.

Sweep recent Claude Code session transcripts (.jsonl) for token-weighted cost/efficiency problems visible only across runs — machine-wide input:output ratio, prompt-cache / KV reuse, per-session distributions (tool calls, I:O, cache-hit, read-only fraction), the global tool mix, and the heaviest sessions by output tokens — plus the behavioral stuck/churn lens (#2365): per-tool error rates, shell timeout kills, foreground sleep-polls, Edit/Write read-discipline churn, repeated identical failure signatures, and per-file mutation churn. Wraps the project's auditor `tools/session_audit.py` (EXACT token accounting from the transcript usage records). Use when the operator says "audit recent claude trajectories/chats/sessions", "where is the token/cost going", "what are the heaviest sessions", "which sessions are stuck/looping/churning", or wants cross-session efficiency or behavior numbers. Read-only — emits a dated report, never edits code.

One repeatable pass that stops fak from re-inventing known kernel art - before writing or optimizing a compute kernel (a quantized GEMM, a fused attention, a KV-cache reuse, a MoE dispatch, a Metal/CUDA kernel), it checks the SOTA prior-art matrix for the production reference (llama.cpp / Marlin / CUTLASS / FlashInfer / vLLM / SGLang / a named paper), decides the route (borrow / bind / stay-minimal), holds the result to the named oracle, and records what was consulted in a Prior-art trailer. Runs `fak sota <op|file>` to surface the reference, reads it, routes deliberately, and (when the matrix has a blind spot) adds the missing row so the next person inherits the map. The inward kernel-engineering counterpart of industry-score (the outward field map). Use before any kernel-optimization commit, when the PRIOR_ART advisory gate fires, when onboarding a new compute operation, or on a /loop cadence to keep the matrix honest against the tree.

The honest closing half of a super loop — after a detached bulk wave (`/super-loop`) has run, HARVEST it: witness what each headless worker actually shipped (not what its log claims), re-queue the leaves that were claimed-done-but-not-shipped, stop workers that are spinning without net gain, and surface any lane a worker stranded dirty. A launch is not a ship, so a bulk loop is only durable if something reconciles its output against git ground truth. Read-mostly — it audits and re-queues; it may stop a spinning PID but never closes an issue by narration. Use when the operator says "harvest the wave", "what did the fleet actually ship", "reconcile the workers", "clean up after the super loop", or on a cadence between waves.

One repeatable RSI pass over claim reproducibility; run the claim-repro scorecard, retire unfalsifiable witness debt worst-first by adding the real artifact/test/path, re-measure, and commit only the claim-repro lane.

Snapshot the repo's phased-plan portfolio into a dispatch packet: audit candidates with `dos verify`, render who-does-what, and emit a `dos gate` verdict. Use when you need the current next-work view before dispatching agents.

One repeatable pass that keeps the dojo's self-improving RSI loop actually CLOSING on our own billed usage - the real calibration history the dojo measures - instead of a plan-mode scaffold that never acts. Drives the native dojo-RSI verbs (`fak dojo-rsi fold|propose|rewrite|run|loop|trend`) over a scored dojo report, picks the worst-calibrated MEASURED, NON-FLOOR cell, previews the one-literal recalibration, self-scores it on a strict FoldCalibrable drop + a sample floor + an external witness, routes REPROJECT/HARVEST/floor cells to the human/agent arm, and commits only the dojo lane by explicit path. The calibration-loop counterpart of guard-rsi-score (which scores the guard's verdict loop). Use after a change to a dojo lever or the claim registry, after a fresh corpus scan, or on a /loop cadence to keep the gym's predictors getting better calibrated over time.

Plan and ship the next batch on one lane: run `dos-next-up`, acquire a lease with `dos arbitrate`, gate empty work, dispatch the packet, and archive the run. Use when a single lane should move end to end with collision safety.

One repeatable pass that keeps the RSI loop for `fak guard` actually CLOSING on our own usage - the real, hash-chained decision journal `fak guard` writes - instead of a plan-mode scaffold that never closes. Runs the native guard-RSI scorecard (`fak guard-rsi-scorecard`) over the two guard RSI loops (the hardware-gated LATENCY loop tools/guard_hop_rsi.py and the hardware-free VERDICT loop `fak guard-verdict-rsi`), scores maturity (can it honestly close?) + realized value (does it run on our usage?), turns each HARD defect into a required affordance to ADD (a journal-grounded loop, a deterministic verdict-quality metric, a non-forgeable keep-bit, real adjudicated rows, control-pane membership, a paired honesty test), retires guard_rsi_debt worst-first, re-measures to PROVE the debt dropped, and commits only the guard-RSI lane by explicit path. The product-loop counterpart of rsi-maturity (which scores the generic internal/rsiloop engine). Use after a change to either guard RSI loop, after a guarded session add

Refresh a plan portfolio from evidence: close shipped queue items, update cooldown state, and surface the few decisions an operator must make. Use after dispatch bursts, drained backlogs, or recurring findings.

One repeatable pass that keeps the skill pack itself effective — the one surface no other scorecard grades. Runs the skill-effectiveness scorecard (`fak skill-effectiveness-scorecard`) over every .claude/skills/*/SKILL.md, reads the skill-debt work-list, and retires it worst-first by ADDING the real affordance — a sharp "Use when …" trigger, a reference that resolves on disk, the commit-by-path discipline a committing skill owes the shared trunk, a witness step, a scoped allowed-tools — never by spraying a keyword. Re-measures to PROVE skill-debt dropped, regenerates the committed snapshot, and commits only the skill lane by explicit path. An instance of the /score-2x loop pointed at the skill pack; the inward counterpart of agent-readiness (the agent's front door) and quality-score (the code). Use after adding or editing a skill, when a skill cites a tool that no longer exists, or on a /loop cadence to keep every skill discoverable, safe to operate, and trustworthy.

One repeatable pass that keeps fak's OUT-OF-THE-BOX token economy amazing — every stacking token-saving method that can SAFELY default is on by default, honestly noted, and locked against regression. Runs the token-saving-defaults scorecard (`fak token-defaults-scorecard`) over the entrypoint source (cmd/fak/guard.go, cmd/fak/serve.go, the gateway Default* constants, and the audited servewiringData rows), turns each HARD defect into a required fix — turn a WITNESSED-safe bounded-loss saver on by default with an honest note, write the missing regression lock, document a dark lever's gate, align the two front doors — and each off high-value saver into a tracked roadmap item (produce the missing witness, then default it). Retires token-defaults-debt worst-first WITHOUT ever shipping an unwitnessed claim, re-measures to PROVE the debt dropped, and commits only the scorecard lane by explicit path. The out-of-the-box-defaults counterpart of persona-score (who lands) and industry-score (the field). Use after a chang

The generic 2×-then-harden loop the whole scorecard family runs — score a surface, drive its debt down 2× with genuine fixes, rescore to PROVE the drop, and when the surface saturates (grade A, zero debt, nothing left to retire) HARDEN the metric itself — tighten a real threshold, promote a SOFT KPI to HARD, or add a dimension — so the score stays a live gradient instead of a frozen A. The conductor over the per-surface instruments (quality-score, industry-score, persona-score, steerability-score, …): it owns the one move no single *-score skill owns — raising the bar when a metric stops discriminating, then re-pinning the control-pane ratchet. Use to run a 2× pass on any surface, to decide whether a saturated scorecard needs hardening, or on a /loop cadence to keep every metric honest in BOTH directions (debt down, bar up).