Refound ontology around hypotheses and experiments

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