diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/architecture.md | 24 | ||||
| -rw-r--r-- | docs/libgrid-dogfood.md | 20 | ||||
| -rw-r--r-- | docs/product-spec.md | 40 |
3 files changed, 44 insertions, 40 deletions
diff --git a/docs/architecture.md b/docs/architecture.md index 37f5c55..30d01fc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -142,7 +142,7 @@ Specific actions may refuse incomplete records. Examples: - core-path experiment closure requires complete run/result/note/verdict state -- future promotion helpers may require a projection-ready change payload +- future promotion helpers may require a projection-ready hypothesis payload ## SQLite Schema @@ -256,7 +256,7 @@ Stores the atomic closure object for core-path work: - frontier id - base checkpoint id - candidate checkpoint id -- change node id +- hypothesis node id - run node id and run id - optional analysis node id - decision node id @@ -284,15 +284,15 @@ Stores durable audit events: Core path: - `contract` -- `change` +- `hypothesis` - `run` - `analysis` - `decision` Off path: -- `research` -- `enabling` +- `source` +- `source` - `note` ### Node tracks @@ -320,13 +320,13 @@ This projection is derived from canonical state and intentionally rebuildable. These are intentionally cheap: - `note.quick`, but only with explicit tags from the repo-local registry -- `research.record`, optionally tagged into the same repo-local taxonomy +- `source.record`, optionally tagged into the same repo-local taxonomy - generic `node.create` for escape-hatch use - `node.annotate` ### Low-ceremony core-path entry -`change.record` exists to capture intent before worktree state becomes muddy. +`hypothesis.record` exists to capture intent before worktree state becomes muddy. ### Atomic core-path closure @@ -423,8 +423,8 @@ Current policy: `frontier.status`, `node.list`, `node.read`, `skill.list`, `skill.show`, and resource reads are safe to replay once after a retryable worker fault -- mutating tools such as `tag.add`, `frontier.init`, `node.create`, `change.record`, - `node.annotate`, `node.archive`, `note.quick`, `research.record`, and +- mutating tools such as `tag.add`, `frontier.init`, `node.create`, `hypothesis.record`, + `node.annotate`, `node.archive`, `note.quick`, `source.record`, and `experiment.close` are never auto-replayed This is the hardening answer to side-effect safety. @@ -451,13 +451,13 @@ Implemented tools: - `frontier.status` - `frontier.init` - `node.create` -- `change.record` +- `hypothesis.record` - `node.list` - `node.read` - `node.annotate` - `node.archive` - `note.quick` -- `research.record` +- `source.record` - `metric.define` - `metric.keys` - `metric.best` @@ -537,7 +537,7 @@ Current commands: - `note quick` - `tag add` - `tag list` -- `research add` +- `source add` - `metric define` - `metric keys` - `metric best` diff --git a/docs/libgrid-dogfood.md b/docs/libgrid-dogfood.md index 5e13e51..59e214e 100644 --- a/docs/libgrid-dogfood.md +++ b/docs/libgrid-dogfood.md @@ -51,7 +51,7 @@ The root contract should state: ### Change node -Use `change.record` to capture: +Use `hypothesis.record` to capture: - what hypothesis is being tested - what base checkpoint it starts from @@ -83,8 +83,8 @@ The decision should make the verdict explicit: Use these freely: -- `research` for ideas, external references, algorithm sketches -- `enabling` for scaffolding that is not yet a benchmarked experiment +- `source` for ideas, external references, algorithm sketches +- `source` for scaffolding that is not yet a benchmarked experiment - `note` for quick observations This is how the system avoids forcing every useful thought into experiment @@ -99,10 +99,10 @@ The MVP does not need hard rejection. It does need meaningful warnings. Good first project fields: -- `hypothesis` on `change` -- `base_checkpoint_id` on `change` -- `benchmark_suite` on `change` and `run` -- `body` on `change`, `research`, and `note` +- `hypothesis` on `hypothesis` +- `base_checkpoint_id` on `hypothesis` +- `benchmark_suite` on `hypothesis` and `run` +- `body` on `hypothesis`, `source`, and `note` - `comparison_claim` on `analysis` - `rationale` on `decision` @@ -126,8 +126,8 @@ Good first metric vocabulary: ### 2. Start a line of attack 1. Read the current frontier and the recent DAG tail. -2. Record a `change`. -3. If needed, attach off-path `research` or `note` nodes first. +2. Record a `hypothesis`. +3. If needed, attach off-path `source` or `note` nodes first. ### 3. Execute one experiment @@ -183,7 +183,7 @@ That means we can already use it to test: - project initialization - schema visibility - frontier creation without a champion -- off-path research recording +- off-path source recording - hidden annotations - MCP read and write flows diff --git a/docs/product-spec.md b/docs/product-spec.md index 89d392c..efa57df 100644 --- a/docs/product-spec.md +++ b/docs/product-spec.md @@ -3,7 +3,7 @@ ## Thesis Fidget Spinner is a local-first, agent-first frontier machine for autonomous -program optimization and research. +program optimization, source capture, and experiment adjudication. The immediate target is brutally practical: replace gigantic freeform experiment markdown with a machine that preserves evidence as structure. @@ -96,7 +96,7 @@ Core-path work is disciplined and atomic. Off-path work is cheap and permissive. -The point is to avoid forcing every scrap of research through the full +The point is to avoid forcing every scrap of source digestion or note-taking through the full benchmark/decision bureaucracy while still preserving it in the DAG. ### 6. Completed core-path experiments are atomic @@ -117,7 +117,7 @@ low-level calls. Dirty worktree snapshots are useful as descriptive context, but a completed core-path experiment should anchor to a committed candidate checkpoint. -Off-path notes and research can remain lightweight and non-committal. +Off-path notes and source captures can remain lightweight and non-committal. ## Node Model @@ -180,7 +180,7 @@ the spine or project payload. These are the disciplined frontier-loop classes: - `contract` -- `change` +- `hypothesis` - `run` - `analysis` - `decision` @@ -189,8 +189,8 @@ These are the disciplined frontier-loop classes: These are deliberately low-ceremony: -- `research` -- `enabling` +- `source` +- `source` - `note` They exist so the product can absorb real thinking instead of forcing users and @@ -237,8 +237,8 @@ done. - disposable MCP worker execution runtime - bundled `fidget-spinner` base skill - bundled `frontier-loop` skill -- low-ceremony off-path note and research recording -- atomic core-path experiment closure +- low-ceremony off-path note and source recording +- explicit experiment open/close lifecycle for the core path ### Explicitly deferred from the MVP @@ -267,13 +267,16 @@ The initial tools should be: - `frontier.status` - `frontier.init` - `node.create` -- `change.record` +- `hypothesis.record` - `node.list` - `node.read` - `node.annotate` - `node.archive` - `note.quick` -- `research.record` +- `source.record` +- `experiment.open` +- `experiment.list` +- `experiment.read` - `experiment.close` - `skill.list` - `skill.show` @@ -282,8 +285,8 @@ The important point is not the exact names. The important point is the shape: - cheap read access to project and frontier context - cheap off-path writes -- low-ceremony change capture -- one atomic "close the experiment" tool +- low-ceremony hypothesis capture +- one explicit experiment-open step plus one experiment-close step - explicit operational introspection for long-lived agent sessions - explicit replay boundaries so side effects are never duplicated by accident @@ -295,11 +298,12 @@ The bundled skills should instruct agents to: 2. bind the MCP session to the target project before project-local reads or writes 3. read project schema, tag registry, and frontier state 4. pull context from the DAG instead of giant prose dumps -5. use `note.quick` and `research.record` freely off path, but always pass an explicit tag list for notes -6. use `change.record` before worktree thrash becomes ambiguous -7. use `experiment.close` to atomically seal core-path work -8. archive detritus instead of deleting it -9. use the base `fidget-spinner` skill for ordinary DAG work and add +5. use `note.quick` and `source.record` freely off path, but always pass an explicit tag list for notes +6. use `hypothesis.record` before worktree thrash becomes ambiguous +7. use `experiment.open` before running a live hypothesis-owned line +8. use `experiment.close` to seal that line with measured evidence +9. archive detritus instead of deleting it +10. use the base `fidget-spinner` skill for ordinary DAG work and add `frontier-loop` only when the task becomes a true autonomous frontier push ### MVP acceptance bar @@ -309,7 +313,7 @@ The MVP is successful when: - a project can be initialized locally with no hosted dependencies - an agent can inspect frontier state through MCP - an agent can inspect MCP health and telemetry through MCP -- an agent can record off-path research without bureaucratic pain +- an agent can record off-path sources and notes without bureaucratic pain - the project schema can softly declare whether payload fields are strings, numbers, booleans, or timestamps - an operator can inspect recent nodes through a minimal localhost web navigator filtered by tag - a git-backed project can close a real core-path experiment atomically |