diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/architecture.md | 45 | ||||
| -rw-r--r-- | docs/product-spec.md | 10 |
2 files changed, 50 insertions, 5 deletions
diff --git a/docs/architecture.md b/docs/architecture.md index acab8fe..5db53fb 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -95,6 +95,16 @@ project schema in `.fidget_spinner/schema.json`. This is where domain-specific richness lives. +Project field specs may optionally declare a light-touch `value_type` of: + +- `string` +- `numeric` +- `boolean` +- `timestamp` + +These are intentionally soft hints for validation and rendering, not rigid +engine-schema commitments. + ### 3. Annotation sidecar Annotations are stored separately from payload and are default-hidden unless @@ -122,6 +132,7 @@ Project field expectations are warning-heavy: - missing recommended fields emit diagnostics - missing projection-gated fields remain storable +- mistyped typed fields emit diagnostics - ingest usually succeeds ### Operational eligibility @@ -308,7 +319,7 @@ This projection is derived from canonical state and intentionally rebuildable. These are intentionally cheap: -- `note.quick` +- `note.quick`, but only with explicit tags from the repo-local registry - `research.record` - generic `node.create` for escape-hatch use - `node.annotate` @@ -356,6 +367,32 @@ worker subprocess. - return typed success or typed fault records - remain disposable without losing canonical state +## Minimal Navigator + +The CLI also exposes a minimal localhost navigator through `ui serve`. + +Current shape: + +- left rail of repo-local tags +- single linear node feed in reverse chronological order +- full entry rendering in the main pane +- lightweight hyperlinking for text fields +- typed field badges for `string`, `numeric`, `boolean`, and `timestamp` + +This is intentionally not a full DAG canvas. It is a text-first operator window +over the canonical store. + +## Binding Bootstrap + +`project.bind` may bootstrap a project store when the requested target root is +an existing empty directory. + +That is intentionally narrow: + +- empty root: initialize and bind +- non-empty uninitialized root: fail +- existing store anywhere above the requested path: bind to that discovered root + ### Fault model Faults are typed by: @@ -375,11 +412,11 @@ The tool catalog explicitly marks each operation as one of: Current policy: -- reads such as `project.status`, `project.schema`, `frontier.list`, +- reads such as `project.status`, `project.schema`, `tag.list`, `frontier.list`, `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 `frontier.init`, `node.create`, `change.record`, +- mutating tools such as `tag.add`, `frontier.init`, `node.create`, `change.record`, `node.annotate`, `node.archive`, `note.quick`, `research.record`, and `experiment.close` are never auto-replayed @@ -399,6 +436,8 @@ Implemented tools: - `project.bind` - `project.status` - `project.schema` +- `tag.add` +- `tag.list` - `frontier.list` - `frontier.status` - `frontier.init` diff --git a/docs/product-spec.md b/docs/product-spec.md index 8ab6210..89d392c 100644 --- a/docs/product-spec.md +++ b/docs/product-spec.md @@ -230,8 +230,10 @@ done. - local SQLite backing store - local blob directory - typed Rust core model +- optional light-touch project field types: `string`, `numeric`, `boolean`, `timestamp` - thin CLI for bootstrap and repair - hardened stdio MCP host exposed from the CLI +- minimal read-only web navigator with tag filtering and linear node rendering - disposable MCP worker execution runtime - bundled `fidget-spinner` base skill - bundled `frontier-loop` skill @@ -259,6 +261,8 @@ The initial tools should be: - `project.bind` - `project.status` - `project.schema` +- `tag.add` +- `tag.list` - `frontier.list` - `frontier.status` - `frontier.init` @@ -289,9 +293,9 @@ The bundled skills should instruct agents to: 1. inspect `system.health` first 2. bind the MCP session to the target project before project-local reads or writes -3. read project schema and frontier state +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 +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 @@ -306,6 +310,8 @@ The MVP is successful when: - 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 +- 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 - retryable worker faults do not duplicate side effects - stale nodes can be archived instead of polluting normal enumeration |