diff --git a/.agents/skills/effort-modeling/SKILL.md b/.agents/skills/effort-modeling/SKILL.md index fa9f6504..1e04bcf0 100644 --- a/.agents/skills/effort-modeling/SKILL.md +++ b/.agents/skills/effort-modeling/SKILL.md @@ -1,13 +1,13 @@ --- name: effort-modeling -description: Sharpen a project's vocabulary and planning through one-question-at-a-time grilling, then journal Decisions, Constraints, Findings, Issues, and Risks into the Flatbread Proof. Use when a plan needs durable reasoning instead of ADRs. +description: Sharpen a project's vocabulary and planning through one-question-at-a-time grilling, then journal Decisions, Constraints, Findings, Issues, and Risks into Proof. Use when a plan needs durable reasoning instead of ADRs. disable-model-invocation: true --- # Effort modeling Use this discipline while a plan or design is being shaped. Store planning -records in the Proof. Keep project terms in a glossary such as +records in Proof. Keep project terms in a glossary such as `CONTEXT.md` or `docs/glossary.md`. ## Resume before asking @@ -36,7 +36,7 @@ answer, and resolve prerequisite choices before dependent ones. ## Journal the right speech act Use `flatbread proof write` for the current Effort, following -[the Proof reference](../proof/reference.md): +[Proof reference](../proof/reference.md): - **Finding** — evidence about code, users, or runtime behavior. - **Issue** — a question, defect, gap, or blocker needing attention. diff --git a/.agents/skills/grill-with-efforts/SKILL.md b/.agents/skills/grill-with-efforts/SKILL.md index 0b1f9599..c577afed 100644 --- a/.agents/skills/grill-with-efforts/SKILL.md +++ b/.agents/skills/grill-with-efforts/SKILL.md @@ -1,6 +1,6 @@ --- name: grill-with-efforts -description: Run a relentless one-question-at-a-time planning interview that sharpens vocabulary and journals durable reasoning into the Flatbread Proof. Use when a plan is fuzzy and needs an Proof trail instead of ADRs. +description: Run a relentless one-question-at-a-time planning interview that sharpens vocabulary and journals durable reasoning into Proof. Use when a plan is fuzzy and needs a Proof trail instead of ADRs. disable-model-invocation: true --- diff --git a/.agents/skills/proof/SKILL.md b/.agents/skills/proof/SKILL.md index c711a77d..931662a5 100644 --- a/.agents/skills/proof/SKILL.md +++ b/.agents/skills/proof/SKILL.md @@ -5,7 +5,7 @@ description: Journal reasoning (decisions, findings, issues, constraints, risks, # Proof — agent journaling and recall -The Proof stores durable project memory as markdown records in the +Proof stores durable project memory as markdown records in the repository. It has eight record types: **Effort**, **Issue**, **Finding**, **Decision**, **Constraint**, and **Risk** capture the work and reasoning; **Citation** stores a source or reference; and **Blob** stores attached diff --git a/.agents/skills/proof/glossary.md b/.agents/skills/proof/glossary.md index fd002a10..79926b2c 100644 --- a/.agents/skills/proof/glossary.md +++ b/.agents/skills/proof/glossary.md @@ -1,6 +1,6 @@ # Proof glossary -The Proof is persistent, queryable memory for long-horizon software +Proof is persistent, queryable memory for long-horizon software work. It builds on Flatbread's content vocabulary: each primitive is a Collection, its instances are Records, and cross-primitive references are Relations in frontmatter. diff --git a/docs/positioning.md b/docs/positioning.md index db3cfffa..b558ba6b 100644 --- a/docs/positioning.md +++ b/docs/positioning.md @@ -16,7 +16,7 @@ control how it reads files and turns them into data. ## The lead use case: memory for coding agents -The [Proof](../packages/proof/README.md) is a Flatbread content +[Proof](../packages/proof/README.md) is a Flatbread content model for what a coding agent works out along the way. An agent records an Effort and then writes Issues, Findings, Decisions, Constraints, Risks, Citations, and Blobs against it. Each record is a markdown file under diff --git a/packages/explorer/README.md b/packages/explorer/README.md index 93bc40df..042136de 100644 --- a/packages/explorer/README.md +++ b/packages/explorer/README.md @@ -1,7 +1,7 @@ # `@flatbread/explorer` Content-relation explorer for Flatbread. v1 ships a generic single-page app -(SPA) shell plus an **Proof** preset. When your config uses +(SPA) shell plus a **Proof** preset. When your config uses `proofContent()`, `flatbread start` serves this UI at `/`. ## Try it locally diff --git a/packages/explorer/package.json b/packages/explorer/package.json index 743011ee..1e0e23b4 100644 --- a/packages/explorer/package.json +++ b/packages/explorer/package.json @@ -1,7 +1,7 @@ { "name": "@flatbread/explorer", "version": "1.0.1", - "description": "Single-page app for browsing a Flatbread content graph, served by flatbread start. Ships an Proof preset.", + "description": "Single-page app for browsing a Flatbread content graph, served by flatbread start. Ships a Proof preset.", "type": "module", "scripts": { "build": "pnpm build:node && pnpm build:web", diff --git a/packages/explorer/src/web/app/components/ProofApp.tsx b/packages/explorer/src/web/app/components/ProofApp.tsx index aa15b94e..f528a0e6 100644 --- a/packages/explorer/src/web/app/components/ProofApp.tsx +++ b/packages/explorer/src/web/app/components/ProofApp.tsx @@ -127,7 +127,7 @@ function EmptyState({ ] : [ 'No Proof records yet', - 'Nothing found in the Proof content root. Journal a record and it will grow in here.', + 'Nothing found in this content root. Journal a record and it will grow in here.', ]; return ( diff --git a/packages/flatbread/README.md b/packages/flatbread/README.md index b9ddfd05..85514897 100644 --- a/packages/flatbread/README.md +++ b/packages/flatbread/README.md @@ -23,7 +23,7 @@ CLI. People use it two ways. -**Durable memory for coding agents.** The +**Durable memory for coding agents.** [Proof](https://github.com/FlatbreadLabs/flatbread/tree/main/packages/proof) stores an agent's reasoning as markdown records in the repository: Efforts, Issues, Findings, Decisions, Constraints, Risks, Citations, and Blobs. An agent diff --git a/packages/flatbread/src/cli/proof.test.ts b/packages/flatbread/src/cli/proof.test.ts index 6e72e99e..eb6b5656 100644 --- a/packages/flatbread/src/cli/proof.test.ts +++ b/packages/flatbread/src/cli/proof.test.ts @@ -1062,6 +1062,30 @@ export default { } ); +test.serial( + 'bootstrap names the write journal for Proof without a branded The Proof', + async (t) => { + const cwd = await createTempProject('flatbread-bootstrap-journal-copy-', t); + await writeFile( + join(cwd, 'flatbread.config.js'), + `import { source } from '@flatbread/source-filesystem'; +import { transformer } from '@flatbread/transformer-markdown'; +import { proofContent } from '@flatbread/proof'; +export default { source: source(), transformer: transformer(), content: proofContent() };` + ); + const report = await inspectEffortBootstrap(cwd); + const journal = report.requirements.find( + (requirement) => + requirement.code === 'EFFORT_BOOTSTRAP_JOURNAL_IGNORE_MISSING' + ); + t.is( + journal?.message, + 'The write journal for Proof at .flatbread-proof is not ignored.' + ); + t.false((journal?.message ?? '').includes('The Proof')); + } +); + test.serial( 'bootstrap detects a ready custom root and verify returns action-required JSON state', async (t) => { diff --git a/packages/flatbread/src/cli/proof.ts b/packages/flatbread/src/cli/proof.ts index 081164a2..0a443146 100644 --- a/packages/flatbread/src/cli/proof.ts +++ b/packages/flatbread/src/cli/proof.ts @@ -325,7 +325,7 @@ export async function inspectEffortBootstrap( requirements.push( requirement( 'EFFORT_BOOTSTRAP_JOURNAL_IGNORE_MISSING', - `The Proof journal for ${graphRoot} is not ignored.`, + `The write journal for Proof at ${graphRoot} is not ignored.`, `Add **/${graphRoot}/.journal/ to .gitignore.` ) ); diff --git a/packages/proof/skills/effort-modeling/SKILL.md b/packages/proof/skills/effort-modeling/SKILL.md index fa9f6504..1e04bcf0 100644 --- a/packages/proof/skills/effort-modeling/SKILL.md +++ b/packages/proof/skills/effort-modeling/SKILL.md @@ -1,13 +1,13 @@ --- name: effort-modeling -description: Sharpen a project's vocabulary and planning through one-question-at-a-time grilling, then journal Decisions, Constraints, Findings, Issues, and Risks into the Flatbread Proof. Use when a plan needs durable reasoning instead of ADRs. +description: Sharpen a project's vocabulary and planning through one-question-at-a-time grilling, then journal Decisions, Constraints, Findings, Issues, and Risks into Proof. Use when a plan needs durable reasoning instead of ADRs. disable-model-invocation: true --- # Effort modeling Use this discipline while a plan or design is being shaped. Store planning -records in the Proof. Keep project terms in a glossary such as +records in Proof. Keep project terms in a glossary such as `CONTEXT.md` or `docs/glossary.md`. ## Resume before asking @@ -36,7 +36,7 @@ answer, and resolve prerequisite choices before dependent ones. ## Journal the right speech act Use `flatbread proof write` for the current Effort, following -[the Proof reference](../proof/reference.md): +[Proof reference](../proof/reference.md): - **Finding** — evidence about code, users, or runtime behavior. - **Issue** — a question, defect, gap, or blocker needing attention. diff --git a/packages/proof/skills/grill-with-efforts/SKILL.md b/packages/proof/skills/grill-with-efforts/SKILL.md index 0b1f9599..c577afed 100644 --- a/packages/proof/skills/grill-with-efforts/SKILL.md +++ b/packages/proof/skills/grill-with-efforts/SKILL.md @@ -1,6 +1,6 @@ --- name: grill-with-efforts -description: Run a relentless one-question-at-a-time planning interview that sharpens vocabulary and journals durable reasoning into the Flatbread Proof. Use when a plan is fuzzy and needs an Proof trail instead of ADRs. +description: Run a relentless one-question-at-a-time planning interview that sharpens vocabulary and journals durable reasoning into Proof. Use when a plan is fuzzy and needs a Proof trail instead of ADRs. disable-model-invocation: true --- diff --git a/packages/proof/skills/proof/SKILL.md b/packages/proof/skills/proof/SKILL.md index c711a77d..931662a5 100644 --- a/packages/proof/skills/proof/SKILL.md +++ b/packages/proof/skills/proof/SKILL.md @@ -5,7 +5,7 @@ description: Journal reasoning (decisions, findings, issues, constraints, risks, # Proof — agent journaling and recall -The Proof stores durable project memory as markdown records in the +Proof stores durable project memory as markdown records in the repository. It has eight record types: **Effort**, **Issue**, **Finding**, **Decision**, **Constraint**, and **Risk** capture the work and reasoning; **Citation** stores a source or reference; and **Blob** stores attached diff --git a/packages/proof/skills/proof/glossary.md b/packages/proof/skills/proof/glossary.md index fd002a10..79926b2c 100644 --- a/packages/proof/skills/proof/glossary.md +++ b/packages/proof/skills/proof/glossary.md @@ -1,6 +1,6 @@ # Proof glossary -The Proof is persistent, queryable memory for long-horizon software +Proof is persistent, queryable memory for long-horizon software work. It builds on Flatbread's content vocabulary: each primitive is a Collection, its instances are Records, and cross-primitive references are Relations in frontmatter.