Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ make verify # exactly what CI runs
## Recipes
Add or change content:
```
tad set concepts --key id --set "name=Name" --set "statement=One-line statement."
tad set concepts --key example-one --set "statement=..."
tad set concepts --key id --set "name=Name" --set "summary=One-line summary."
tad set concepts --key example-one --set "summary=..."
make render && make verify
```
A new field: declare it in `tables.toml` (a `[[tables.<table>.fields]]` entry with its `name` and `type`, and `required`, `enum` or `pattern` if it has them), then `make canon`: every line gains the field, empty. A required field is then given a value on every row with `tad set` before `make verify` passes.
Expand Down
28 changes: 14 additions & 14 deletions data/concepts.json

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions data/session_log.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,4 @@
{"id":"its-idea-for-anyone","entry_date":"2026-11-10","title":"Its idea, told for anyone","done":"The idea of Rhizoid written as an ordered piece of writing in its own data - borrowed versus owned, a cutting rather than a copy, nothing hidden, what it does not fix, where it stands - for a reader who knows nothing of it.","considered":"Terse cards of concepts.","rejected":"Those as the idea: they name the parts for an insider."}
{"id":"its-workings","entry_date":"2026-11-10","title":"Its workings, told","done":"What delivers and proves the steps reached so far - the design log, the declarations layer and its tests - written under the steps they serve. The TUI and carrying ocoeco are left with nothing under them.","considered":"Filling every step.","rejected":"That: a step nothing serves should be seen."}
{"id":"2026-11-11-tad-in-rust","entry_date":"2026-11-11","title":"tad in Rust replaces the vendored Python engine","done":"This repository moved to tad in Rust: tables.toml is the authority, tad comes from its pinned release, the vendored .tad, schema.sql, load.sql and checks/ are gone, and AGENTS.md got simpler. The open item about dc.py blocking recovery from an empty table closed with it.","considered":null,"rejected":null}
{"id":"2026-11-11-one-word-summary","entry_date":"2026-11-11","title":"A concept's text is its summary","done":"The concepts table's statement field is now summary, the word the shared language (ocoeco's language.toml) and twenty other projects use; the observatory showed this repository's concepts without their text because of it. Found by checking every project against the shared language.","considered":"Teaching the shared language a second word for the same thing.","rejected":"That: one role, one word."}
28 changes: 14 additions & 14 deletions docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<a id="rhizoid-cutting"></a>
### Rhizoid-cutting (rhizcut)

Statement
Summary
: A single dependency managed by Rhizoid: a real GitHub fork of an upstream repo, owned and pinned rather than referenced remotely. Named after a horticultural cutting - a piece taken from a parent plant and rooted separately, genetically identical at the start but independent from then on.

Tags
Expand All @@ -22,7 +22,7 @@ Sources
<a id="additive-file-structure"></a>
### Additive-only file structure

Statement
Summary
: Rhizoid-managed metadata (manifest, sync state) is added as new files alongside upstream's own, never edited in place inside upstream's existing files. This keeps a pull from upstream conflict-free for the tracked branch - not a guarantee that any patch to upstream code stays conflict-free, only that Rhizoid's own bookkeeping never collides with it.

Tags
Expand All @@ -40,7 +40,7 @@ Sources
<a id="tracking-vs-patch-branch"></a>
### Tracking branch vs patch branch

Statement
Summary
: The branch that mirrors upstream is never hand-edited - only fast-forwarded via merge-upstream. All customization lives on a separate branch that merges from the tracking branch. The tracking branch never conflicts; the patch branch might, exactly once, when upstream touches a line you also patched - that is inherent to patching, not a tooling failure.

Tags
Expand All @@ -54,7 +54,7 @@ Relations
<a id="clean-patch-back"></a>
### Clean patch back upstream

Statement
Summary
: Because Rhizoid's own metadata never touches upstream's files, a diff of the patch branch against the pristine tracking branch is a clean patch, submittable as a normal PR to the original repo, whether or not its owner has ever heard of Rhizoid.

Tags
Expand All @@ -70,7 +70,7 @@ Sources
<a id="drift-detection"></a>
### Status detects drift, not just reports the manifest

Statement
Summary
: rhizoid status inspects the real state of every managed fork (does it exist, what commit is the tracking branch actually at, is there uncommitted or unmanifested structure) and diffs that against the manifest's record, the way terraform plan diffs real infrastructure against Terraform state. The manifest is a record of intent, not a source of truth Rhizoid trusts blindly - reality always wins the comparison.

Tags
Expand All @@ -87,7 +87,7 @@ Sources
<a id="adopt-vs-create"></a>
### Adopt an existing fork vs create a new one

Statement
Summary
: Two different, deliberately separate operations: rhizoid add forks a new copy of upstream; rhizoid import points at a fork that already exists (with or without the rhizoid wrapper already on it) and adopts it into the manifest without creating anything. Kept as two verbs rather than one flag with a default, the way terraform keeps import separate from apply - the two operations have different blast radii and a wrong default in either direction is a real mistake (an unwanted duplicate fork, or silently overwriting someone's existing, satisfactory fork).

Tags
Expand All @@ -104,7 +104,7 @@ Sources
<a id="fork-destination-manifest"></a>
### Fork destination is a manifest setting, not hardcoded

Statement
Summary
: Where a new fork lands (which org or account) is configured per manifest, with a default and a per-module override - the same shape as west's remotes list (a named set of url-bases) plus each project's optional remote: override. Nothing about Rhizoid assumes forks live in one specific org.

Tags
Expand All @@ -120,7 +120,7 @@ Sources
<a id="rhizoid-command-surface"></a>
### The v1 command surface: init, add, import, update, status, refresh, remove

Statement
Summary
: init sets up a manifest. add forks a new module into the configured org and starts tracking it. import adopts an existing fork without creating one. update pulls upstream into a module's tracking branch (GitHub's merge-upstream). status reports drift between the manifest and real git/GitHub state. refresh reconciles the manifest to match observed reality without changing anything (mirrors terraform apply -refresh-only) - this is how a by-hand change gets folded back in rather than flagged as drift forever. remove drops a module from the manifest. send-upstream (clean patch back to the true upstream) is real but deferred to v0.2, after the core loop is proven.

Tags
Expand All @@ -135,7 +135,7 @@ Relations
<a id="module-metadata-file"></a>
### Each fork carries its own .rhizoid/module.toml

Statement
Summary
: The additive metadata that makes a fork "attached" lives in a new .rhizoid/module.toml file at the fork's own root: origin URL, tracked ref, pinned commit, whether it was added or imported, when. Mirrors .tad/.gitrepo's pattern from the tad system - a plain, readable file is the source of truth for state, not something buried in commit messages or a separate database.

Tags
Expand All @@ -151,7 +151,7 @@ Relations
<a id="manifest-file-format"></a>
### The manifest is TOML, with the footgun that argues against it named up front

Statement
Summary
: TOML: native comments (unlike JSON), no implicit type coercion or indentation sensitivity (unlike YAML - see [the YAML document from hell](sources.md#yaml-document-from-hell)), and its array-of-tables syntax is a direct fit for "a list of modules, each a flat record". Cross-ecosystem adoption for exactly this kind of file (a hand-editable project/tool manifest, not a deeply-nested orchestration config) is real and independent of any one language: Cargo.toml, pyproject.toml, Hugo, Netlify. The honest counter-case: Cloudflare's Wrangler shipped TOML-only for years, then added JSONC and now recommends it for new projects, naming TOML's array-of-tables syntax as a real footgun in practice - a misplaced or missing [[table]] header silently puts a value in the wrong entry (see [the future of Wrangler configuration](sources.md#wrangler-toml-to-jsonc)). That risk is highest when a file is mostly hand-typed from scratch, which is not the common case here: the manifest is meant to be edited through add/import/remove, not freehand, and each module's own detailed state lives in its own .rhizoid/module.toml rather than piling many [[module]] entries into one large hand-edited file - closer to Cargo.toml's [dependencies] table (mostly tool-written) than to a large hand-maintained Wrangler config.

Tags
Expand All @@ -168,7 +168,7 @@ Sources
<a id="distributed-state-no-lockfile"></a>
### No central lockfile - state is distributed into each fork

Statement
Summary
: Cargo, npm, Poetry and Nix all pair a human-edited manifest with a separate, machine-written lockfile recording exact resolved state. Rhizoid does not need a top-level lockfile: each managed fork is already a real git repository with its own history, and its own .rhizoid/module.toml already carries that module's exact recorded state (see [module-metadata-file](concepts.md#module-metadata-file)). A central lockfile would just be a second, independently-driftable copy of information git already holds per-repo.

Tags
Expand All @@ -182,7 +182,7 @@ Relations
<a id="auth-via-gh"></a>
### Auth: shell out to gh, for now

Statement
Summary
: Rhizoid calls the GitHub CLI (gh) for anything needing authentication - forking, merge-upstream, reading repo state - rather than managing its own token or OAuth flow. Whoever already has gh authenticated can use Rhizoid immediately; the tool has no credentials of its own to store, rotate, or leak. Revisit if a use case needs something gh cannot do (a non-GitHub git host, for one).

Tags
Expand All @@ -192,7 +192,7 @@ Tags
<a id="argenv-is-flags-and-env-only"></a>
### argenv declares flags and env vars - not subcommands or positionals

Statement
Summary
: Read argenv's own source and README before designing against it: it is explicitly "a declared, typed contract for a program's invocation surface - argv and envp", and every Input it declares binds to a --flag/env-var pair, never a bare positional value. Confirmed by reading argenv-cli's own main.rs (the author's own reference CLI): subcommand dispatch is a plain match on args.first(), not anything argenv provides. Rhizoid's CLI follows the same shape: a thin hand-written dispatcher picks the verb and reads each command's one primary positional (a repo spec, a URL, a module name) directly; argenv declares only the named flags for each verb.

Tags
Expand All @@ -208,7 +208,7 @@ Sources
<a id="rhizoid-crate-shape"></a>
### Two crates: rhizoid-core and rhizoid-cli

Statement
Summary
: Mirrors argenv's own workspace shape (crates/argenv + crates/argenv-cli). rhizoid-core holds the Manifest and Module types, their JSON Schema (via schemars, the same crate argenv itself already uses for its own contract feature), and the GitPort/GitHubPort traits the real fork/sync logic will implement later. rhizoid-cli holds argv dispatch and the per-command argenv Models. Splitting now, before there is much code, avoids a disruptive later refactor once the planned TUI needs to depend on the same core logic without the CLI.

Tags
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@

- [Backlog](backlog.md): 6
- [Concepts](concepts.md): 14
- [Session Log](session_log.md): 19
- [Session Log](session_log.md): 20
- [Sources](sources.md): 11
18 changes: 18 additions & 0 deletions docs/session_log.md
Original file line number Diff line number Diff line change
Expand Up @@ -286,3 +286,21 @@ Entry date

Done
: This repository moved to tad in Rust: tables.toml is the authority, tad comes from its pinned release, the vendored .tad, schema.sql, load.sql and checks/ are gone, and AGENTS.md got simpler. The open item about dc.py blocking recovery from an empty table closed with it.

---


<a id="2026-11-11-one-word-summary"></a>
### A concept's text is its summary

Entry date
: 2026-11-11

Done
: The concepts table's statement field is now summary, the word the shared language (ocoeco's language.toml) and twenty other projects use; the observatory showed this repository's concepts without their text because of it. Found by checking every project against the shared language.

Considered
: Teaching the shared language a second word for the same thing.

Rejected
: That: one role, one word.
2 changes: 1 addition & 1 deletion tables.toml
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ type = "string"
required = true

[[tables.concepts.fields]]
name = "statement"
name = "summary"
type = "string"
required = true

Expand Down
Loading