fix: post-codex validation - research guard, memory unification, CLI learning-loop wiring, truthful docs

AGENTS.md

@@ -39,6 +39,12 @@ small, trustworthy accounting kernel.
   - `openfpa entrypoint-list <company-root>` before generated workflows
   - `openfpa entrypoint-register <company-root> ...` after validating a command
   - `openfpa doctor <company-root>` before relying on workspace state
+  - `openfpa correction-record <company-root> --slug <slug> --type <type> --target <target> --date <date>` after establishing a correction
+  - `openfpa correction-list <company-root>` to review recorded corrections
+  - `openfpa scorecard-render <company-root>` to rebuild scorecard.md from all snapshots
+  - `openfpa experiment-list <company-root>` to review experiment records
+  - `openfpa context-pack <company-root> --task "<task>"` to retrieve bounded memory for a task
+  - `openfpa onboarding-render <company-root> --proposal-summary "<summary>"` when intake is ready
 - The CLI emits JSON and performs deterministic workspace operations. Read its
   output as evidence; do not treat it as the reasoning engine.
 - If the console script is unavailable in a source checkout, use

CLAUDE.md

@@ -46,6 +46,13 @@ and register a tested company-specific reconciliation command.
 Do not force onboarding for a narrow request. Ask before accessing external
 systems or connectors.
 
+Keep the learning loop current. When a human flags something off, record it with
+`openfpa correction-record` (list with `correction-list`). After scoring closed
+periods, refresh the track record with `openfpa scorecard-render` and review past
+hypotheses with `openfpa experiment-list`. Before broad company work, build a
+bounded context pack with `openfpa context-pack`. Regenerate onboarding documents
+from intake with `openfpa onboarding-render`.
+
 After the initial architecture is approved, use `fpa-research-loop` for bounded
 autonomous improvement. You may generate, evaluate, and discard challengers
 without asking for approval each time. Human approval is required for promotion

README.md

@@ -183,7 +183,7 @@ The `openfpa` command is a machine-oriented control surface for Codex, Claude
 Code, and other capable coding agents. It emits JSON, performs deterministic
 workspace operations, and leaves reasoning and conversation to the host agent.
 
-The initial command set is:
+The command set is:
 
 ```text
 openfpa init
@@ -203,8 +203,17 @@ openfpa intake-record
 openfpa doctor
 openfpa entrypoint-list
 openfpa entrypoint-register
+openfpa correction-record
+openfpa correction-list
+openfpa scorecard-render
+openfpa experiment-list
+openfpa context-pack
+openfpa onboarding-render
 ```
 
+In a source checkout without the `openfpa` console script installed, every
+command also works as `python3 -m pyfpa.cli <command>`.
+
 The CLI can:
 
 - initialize and validate the workspace;

docs/blog/launch.md

@@ -1,66 +1,68 @@
-# I gave Claude a 10-minute intake call and it built itself a CFO
+# The AI is the analyst. We built its toolbelt.
 
-*Open-sourcing openfpa — an AI-native FP&A toolkit. By Guiderail.*
+*Open-sourcing openfpa, an agent-native FP&A workbench. By Guiderail.*
 
 ---
 
 Every founder has lived this: you don't need a full-time CFO yet, but you absolutely need CFO-grade answers. *When do we run out of cash? Can we afford this hire? What does the board need to see?* The honest answer is usually a spreadsheet someone built once, nobody fully trusts, and everyone is afraid to touch.
 
-So I tried something. Instead of building another FP&A *app*, I built an FP&A **skillset** — and handed it to an AI.
+Here's the thing we eventually admitted to ourselves: the AI coding agents are already good enough to do this work. Claude Code or Codex, pointed at your books, can interview you, write a model, and explain a variance. The agent is the superhero. What it's missing is the toolbelt: the tested accounting math, the working method, the memory, and the checks that separate a real analyst from a very confident intern.
 
-## The toolkit re-tools itself for your business
+So instead of building another FP&A *app*, we built the toolbelt.
 
-The headline isn't the forecast engine. It's this: **the toolkit writes its own tooling for your company.**
+## What the toolbelt holds
 
-The first skill, `fpa-learn-business`, runs before any modeling. It interviews the operator, reads whatever financials exist, and writes a durable *business profile*. Then it does the part that still surprises me — it looks at *your* business and proposes new, bespoke skills that the generic toolkit doesn't ship.
+openfpa gives the agent four things a bare chat session doesn't have:
 
-To prove this wasn't a demo rigged for one company, I spun up a **fresh AI agent with zero context** — it had never seen the repo — and gave it a 10-minute intake for a fictional coffee roaster, *Harbor & Vine*. With nothing but the skillset, it:
+- **A tested finance kernel.** Revenue, COGS, opex, working capital, debt, tax, and cash flow live in one regression-tested place, so the accounting is not re-derived (differently) every run.
+- **An operating contract.** Rules for how the agent inspects evidence before asking questions, registers data sources, reconciles before forecasting, and asks a human before promoting anything.
+- **Durable memory.** What it learns about your business, your corrections, its own forecast track record, all of it lives as plain files in your repo. The agent is not reset every session.
+- **A research loop.** Forecast hypotheses are scored against held-out actuals, champion versus challenger. Weak challengers are kept as failed research. Promotion requires evidence and your sign-off.
 
-1. Wrote the business profile from the conversation.
-2. Built a runnable financial model (two channels, holiday-skewed D2C, an equipment loan, a 60-day green-coffee inventory cycle) and produced a clean 12-month P&L and cash forecast — **$3.6M revenue, 10.7% EBITDA**.
-3. Generated a board-ready briefing.
-4. And then proposed a skill I never wrote: a **`green-coffee-cogs-model`** — because, it reasoned, "green coffee is a commodity purchased forward; a fixed COGS percentage will be wrong every time the ICE arabica market moves, and they hold 60 days of inventory, so future COGS is already largely locked in."
+The agent still does the thinking. It asks the questions, writes the company-specific code, and makes the judgment calls. The toolbelt makes that work auditable, repeatable, and cumulative.
 
-That's a real finance insight about a business it learned about ten minutes earlier — and a correct instinct to extend its own tooling to handle it. It even refused to *write* the skill without human approval, exactly as designed. Self-extending, not self-executing.
+## It re-tools itself for your business
 
-## It thinks like a CFO, not a calculator
+The part that still surprises us: when the standard tools don't fit a company, the agent extends the toolbelt, in reviewable code, with the reasoning written down.
+
+The committed proof lives in the Fox Factory example below. Fox reports segment Adjusted EBITDA under ASU 2023-07, not segment gross profit, which is a company shape the base kernel didn't ship with. The agent wrote itself a `segment-rollup` skill to handle it, citing the filing facts that justified the design. Self-extending, with a human gate; never self-executing.
 
-A model that's arithmetically perfect can still be wrong about reality. The skill I'm proudest of is `fpa-cfo-judgment` — the reflexes a seasoned finance person applies without thinking:
+## It thinks like a CFO, not a calculator
 
-- *That month looks suspiciously profitable* → it's probably unposted COGS, not real margin. Don't celebrate a month that isn't closed.
-- *EBITDA looks great* → EBITDA isn't cash. It ignores capex, the working-capital swing, and debt service — a banner EBITDA quarter can still burn cash.
-- *Cash went negative in week 3* → that's "you need a credit line," not "you're insolvent." Say which.
+A model that's arithmetically perfect can still be wrong about reality. The judgment layer encodes the reflexes a seasoned finance person applies without thinking:
 
-The cold agent caught the working-capital timing trap on Harbor & Vine on its own, using exactly these checks. That's the difference between AI that does math and AI that does finance.
+- *That month looks suspiciously profitable?* It's probably unposted COGS, not real margin. Don't celebrate a month that isn't closed.
+- *EBITDA looks great?* EBITDA isn't cash. It ignores capex, the working-capital swing, and debt service. A banner EBITDA quarter can still burn cash.
+- *Cash went negative in week 3?* That means "you need a credit line," not "you're insolvent." Say which.
 
 ## The cash-runway answer founders actually lose sleep over
 
-The demo company, *Ridgeline Chair Co.* (a fictional premium camping-chair brand), shows the punchline. Its 13-week cash forecast goes **negative in week 3** — the spring inventory build lands before the summer sell-through collects — troughs at **−$146K**, then recovers. The model doesn't paper over it with an automatic credit-line draw. It shows the raw hole, because the hole *is* the answer: *size a ~$150–200K line to bridge the build.*
+The demo company, *Ridgeline Chair Co.* (a fictional premium camping-chair brand), shows the punchline. Its 13-week cash forecast goes **negative in week 3**, as the spring inventory build lands before the summer sell-through collects, troughs at **-$146K**, then recovers. The model doesn't paper over it with an automatic credit-line draw. It shows the raw hole, because the hole *is* the answer: size a roughly $150K to $200K line to bridge the build.
 
 ## "Couldn't I just point Claude at my 10-K myself?"
 
-You could. Claude is a strong analyst. But a bare agent writes a *fresh* pile of pandas every run — no shared structure, no test, no audit trail. Correctness by luck-of-the-run, and the wrong number looks right.
+You could. Claude is a strong analyst. But a bare agent writes a *fresh* pile of pandas every run: no shared structure, no test, no audit trail. Correctness by luck of the run, and the wrong number looks right.
 
-So I pushed the toolkit at the opposite of a friendly demo: **Fox Factory (NASDAQ: FOXF)**, a real $1.5B public company with three segments, a debt-funded acquisition (Marucci), and a $557M goodwill impairment that turned a revenue-recovery year into a GAAP net loss. Pulled straight from its SEC filings, openfpa:
+So we pushed the toolbelt at the opposite of a friendly demo: **Fox Factory (NASDAQ: FOXF)**, a real $1.5B public company with three segments, a debt-funded acquisition (Marucci), and a $557M goodwill impairment that turned a revenue-recovery year into a GAAP net loss. Pulled straight from its SEC filings, openfpa:
 
-1. **Separated accounting reproduction from forecast validation.** Feeding the engine Fox's reported drivers reproduces FY2024 and FY2025 operating mechanics, but the demo explicitly says this is an arithmetic check, not proof of predictive skill.
-2. **Ran an FY2025 historical holdout.** Using FY2023–FY2024 only, the research loop rejected an over-aggressive recovery hypothesis, refined it, and proposed a challenger that improved every weighted holdout metric.
-3. Was honest about the rest: the impairment and Fox's discrete tax benefits are shown as an explicit **bridge**, not laundered through the model. A lean engine should model the operating business and *say* what it doesn't.
-4. Forecast FY2026–FY2027 at the segment level, preserved working-capital continuity across the year boundary, and modeled a "what if Fox sells Marucci" cash-flow and leverage sensitivity.
-5. And — because Fox reports segment **Adjusted EBITDA**, not gross profit (the new ASU 2023-07 rule) — the agent **wrote itself a `segment-rollup` skill** to fit a company shape the base engine didn't ship with.
+1. **Separated accounting reproduction from forecast validation.** Feeding the kernel Fox's reported drivers reproduces FY2024 and FY2025 operating mechanics, and the demo explicitly says this is an arithmetic check, not proof of predictive skill.
+2. **Ran an FY2025 historical holdout.** Using FY2023 and FY2024 only, the research loop rejected an over-aggressive recovery hypothesis, refined it, and proposed a challenger that improved every weighted holdout metric.
+3. **Was honest about the rest.** The impairment and Fox's discrete tax benefits are shown as an explicit bridge, not laundered through the model. A lean kernel should model the operating business and *say* what it doesn't.
+4. **Forecast FY2026 and FY2027 at the segment level**, preserved working-capital continuity across the year boundary, and modeled a "what if Fox sells Marucci" cash-flow and leverage sensitivity.
+5. **Extended itself**, writing the `segment-rollup` skill described above.
 
 Here's the part a one-off analysis usually lacks: **the proof runs in CI.** Every push, on three Python versions, checks the arithmetic reproduction, historical holdout behavior, segment rollup, and forecast continuity.
 
-And it earned that test. Mid-build, the engine had a subtle bug — it added depreciation back into operating cash flow without ever expensing it, silently inflating cash. That is *exactly* the error a one-shot agent emits and nobody catches. openfpa caught it because the logic lives in one tested place; the fix landed once, and a test now guarantees it never comes back. **That's the whole point of a substrate: correctness becomes a property of the system, not a coin-flip on each run.**
+And it earned that test. Mid-build, the kernel had a subtle bug: it added depreciation back into operating cash flow without ever expensing it, silently inflating cash. That is *exactly* the error a one-shot agent emits and nobody catches. openfpa caught it because the logic lives in one tested place; the fix landed once, and a test now guarantees it never comes back. That's the whole point of a substrate: correctness becomes a property of the system, not a coin flip on each run.
 
-> Bare Claude is a brilliant analyst with a blank spreadsheet. openfpa is the firm's tested model engine, the encoded house methodology, and the review checklist — the rails the agent drives on, and the gauges that catch it when it's wrong.
+> Bare Claude is a capable analyst with a blank spreadsheet. openfpa is the tested model kernel, the encoded house methodology, and the review checklist. Rails to drive on, and gauges that catch the mistakes.
 
 ## Why open-source it?
 
-Because the most credible thing you can say about being on the frontier is to show your work — and then let people check it. The engine is deliberately lean — a few hundred lines of pure, tested Python — because it's a substrate for an AI to extend, not an app to configure. The demo runs on synthetic data; the Fox Factory proof runs on nothing but public SEC filings, fully source-traced; it speaks NetSuite, QuickBooks, and Shopify when you connect them; and the whole thing installs as a Claude plugin.
+Because the most credible thing you can say about being on the frontier is to show your work, and then let people check it. The kernel is regression-tested Python built to be read and extended by an agent, not an app you configure by hand. The demo runs on synthetic data. The Fox Factory proof runs on nothing but public SEC filings, fully source-traced. Adapters for NetSuite, QuickBooks, and Shopify ship as fixture-backed scaffolds that document their live paths, and the agent builds the real connector for whatever source you actually have. The whole thing installs as a Claude plugin.
 
-Clone it. Point Claude at it. Hand it your numbers. Watch it build you a CFO.
+Clone it. Point your agent at it. Hand it your numbers. See what they build together.
 
 → **github.com/JeffBrines/openfpa** · MIT licensed · built by Guiderail
 
-*The forecast engine, the 13-week cash model, the data adapters, and the agent skills are regression-tested, including the Fox Factory actual-driver reproduction, historical holdout, and forecast-continuity checks. The cold-agent walkthrough and Fox run above were real runs, not scripts.*
+*The forecast kernel, the 13-week cash model, the data adapters, and the agent skills are regression-tested, including the Fox Factory actual-driver reproduction, historical holdout, and forecast-continuity checks. The Fox run above was a real run, not a script.*