j7/StarrOS
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: canon pass — split canonical spec from runtime state, add 5 companion docs #2

Closed
san wants to merge 0 commits from docs/starros-doc-canon-pass into main
pull from: docs/starros-doc-canon-pass
merge into: j7:main
Conversation 0 Commits - Files changed -
san commented 2026-07-09 03:17:00 -04:00
Collaborator
Copy link

Summary

Follow-up to PR #1. Restructures the repo so the canonical spec is integration-overview only; runtime facts move to a live companion doc; 5 new companion docs land; cross-file references are normalized.

3 commits

# SHA Title Files
C1+C2 8e376e5 docs: split canonical spec from runtime state, add 5 companion docs 6 (1 modified, 5 new)
C3 b55107d docs: cross-file normalize — pointers to companion docs, E1 epic, packet field, ADR-0003 link 7 (all modified)

Net: 13 files changed (5 new, 8 updated). 616 lines added, 314 removed.

What is in the PR

Spec v2.0 (specs/starros-stack-spec.md)

  • Added §0 'Scope: target architecture vs current implementation state' so the spec stops absorbing debug-notebook cross-references.
  • Trimmed runtime facts (port maps, broken services, drift) out of architecture — moved to docs/runtime-state.md.
  • Renamed §14 to 'Recommendations' (3 spec-shape only); dropped the Ashitaka debug-action recommendation (it was a runtime concern, not architectural).
  • Added ADR 0003 link in §12.
  • Glossary cross-link added in spec §0 referencing decisions/0003-canonical-spec-boundaries.md §Glossary.

5 new companion docs

  1. docs/runtime-state.md — live operational state, per-week rewrite, deliberately short
  2. specs/gbrain-substrate.md — project substrate, in-scope per J7 2026-07-09
  3. docs/persistence-boundaries.md — 'where do I write this?' map (17-row table)
  4. docs/external-workers.md — CLI workers policy (5 in scope: Claude Code, OpenCode, Kilocode, Gemini, Copilot)
  5. decisions/0003-canonical-spec-boundaries.md — rationale + glossary for the spec/companion-doc split

Cross-file updates

  • kanban/backlog.md — E1 retitled from 'Mission Control shell' to 'StarrOS doc canon' with 7 cards (T1–T7); E2-T1 typo fix OKF/GBrain → GBrain; new E3 'Runtime ops' epic with 14 cards mapped to phases P0–P13
  • packets/leaf-card-template.md — new Report-back channel field; explicit cross-ref to docs/external-workers.md §6
  • prompts/san-handoff.md — reading list expanded to 15 docs
  • prompts/fable-global.md — paused-components callout with glossary cross-ref
  • docs/playbook.md — companion-docs section
  • docs/workflow.md — 'external coder workers' naming normalization; canonical-doc references
  • decisions/0001-repo-is-source-of-truth.md — Related: ADR 0003; strengthened consequences (per-week doc-canon pattern)

What is NOT in this PR

  • No code changes. No NixOS module changes. No deployment changes.
  • No Telegram/Matrix status posted yet (per J7 prior instruction 'don't assign the roles until we get to that point' — also held for review-lane discussion).
  • No reviewers pre-assigned (same J7 directive).

Open questions for J7

  1. GBrain owner — Ashitaka (orchestration), Okkoto (build), Mokku (taxonomy), or San (overall)?
  2. GBrain hosting — Mononoke only, or also Outpost for redundancy?
  3. GBrain Phase P11 deliverable — spec only, or spec + working skeleton?
  4. Per-project GBrain granularity — one per J7-named project, or one per StarrOS-wide initiative?
  5. External coder workers — add a 6th tool? Current cap is 5.
  6. Mission Control revival timeline — Phase P2 is 'deferred'; when is the right time to revisit?
  7. Hermes Workspace flake input — keep the NixOS module in /etc/nixos/nix/services/hermes-workspace.nix for later revival, or remove it entirely?
  8. AionUI addendum — specs/aionui-addendum.md is still a placeholder; when do we have content?
  9. PR-2 review lane — this PR is doc-canon only. Who is the right Jigo reviewer?

Reviewer assignment

Per J7 prior directive ('don't assign the roles until we get to that point'), no reviewers are pre-assigned. Will assign at review time per question #9.

Test plan

  • J7 visual review of all 13 file changes
  • Confirm Mnemosyne scoping language matches J7's intent (shared DB with author_id/channel_id filtering)
  • Confirm GBrain placement (in scope, undefined, Phase P11)
  • Confirm Karakeep owner swap (was San-consumer → now Mokku-taxonomy)
  • Confirm external coder workers naming normalization (5 CLIs, no 6th yet)
  • Jigo review (per ADR 0001)
  • Ashitaka review (multi-domain decomposition)

Provenance

  • v1.0 (2201 bytes, J7 original) — commit sha 908aae4a4b… on main
  • v1.1 (26995 bytes, San canonicalization) — commit 21dee6d on branch spec/starros-stack-canonicalization (PR #1, open)
  • v2.0 (this revision, doc-canon pass) — commits 8e376e5 + b55107d on branch docs/starros-doc-canon-pass (this PR)

— San

## Summary Follow-up to PR #1. Restructures the repo so the canonical spec is integration-overview only; runtime facts move to a live companion doc; 5 new companion docs land; cross-file references are normalized. ## 3 commits | # | SHA | Title | Files | |---|---|---|---| | C1+C2 | 8e376e5 | docs: split canonical spec from runtime state, add 5 companion docs | 6 (1 modified, 5 new) | | C3 | b55107d | docs: cross-file normalize — pointers to companion docs, E1 epic, packet field, ADR-0003 link | 7 (all modified) | Net: **13 files changed** (5 new, 8 updated). 616 lines added, 314 removed. ## What is in the PR ### Spec v2.0 (`specs/starros-stack-spec.md`) - Added **§0 'Scope: target architecture vs current implementation state'** so the spec stops absorbing debug-notebook cross-references. - **Trimmed runtime facts** (port maps, broken services, drift) out of architecture — moved to `docs/runtime-state.md`. - **Renamed §14** to 'Recommendations' (3 spec-shape only); dropped the Ashitaka debug-action recommendation (it was a runtime concern, not architectural). - **Added ADR 0003 link** in §12. - **Glossary cross-link** added in spec §0 referencing `decisions/0003-canonical-spec-boundaries.md` §Glossary. ### 5 new companion docs 1. `docs/runtime-state.md` — live operational state, per-week rewrite, deliberately short 2. `specs/gbrain-substrate.md` — project substrate, in-scope per J7 2026-07-09 3. `docs/persistence-boundaries.md` — 'where do I write this?' map (17-row table) 4. `docs/external-workers.md` — CLI workers policy (5 in scope: Claude Code, OpenCode, Kilocode, Gemini, Copilot) 5. `decisions/0003-canonical-spec-boundaries.md` — rationale + glossary for the spec/companion-doc split ### Cross-file updates - `kanban/backlog.md` — E1 retitled from 'Mission Control shell' to 'StarrOS doc canon' with 7 cards (T1–T7); E2-T1 typo fix OKF/GBrain → GBrain; new E3 'Runtime ops' epic with 14 cards mapped to phases P0–P13 - `packets/leaf-card-template.md` — new `Report-back channel` field; explicit cross-ref to `docs/external-workers.md` §6 - `prompts/san-handoff.md` — reading list expanded to 15 docs - `prompts/fable-global.md` — paused-components callout with glossary cross-ref - `docs/playbook.md` — companion-docs section - `docs/workflow.md` — 'external coder workers' naming normalization; canonical-doc references - `decisions/0001-repo-is-source-of-truth.md` — Related: ADR 0003; strengthened consequences (per-week doc-canon pattern) ## What is NOT in this PR - No code changes. No NixOS module changes. No deployment changes. - No Telegram/Matrix status posted yet (per J7 prior instruction 'don't assign the roles until we get to that point' — also held for review-lane discussion). - No reviewers pre-assigned (same J7 directive). ## Open questions for J7 1. **GBrain owner** — Ashitaka (orchestration), Okkoto (build), Mokku (taxonomy), or San (overall)? 2. **GBrain hosting** — Mononoke only, or also Outpost for redundancy? 3. **GBrain Phase P11 deliverable** — spec only, or spec + working skeleton? 4. **Per-project GBrain granularity** — one per J7-named project, or one per StarrOS-wide initiative? 5. **External coder workers — add a 6th tool?** Current cap is 5. 6. **Mission Control revival timeline** — Phase P2 is 'deferred'; when is the right time to revisit? 7. **Hermes Workspace flake input** — keep the NixOS module in `/etc/nixos/nix/services/hermes-workspace.nix` for later revival, or remove it entirely? 8. **AionUI addendum** — `specs/aionui-addendum.md` is still a placeholder; when do we have content? 9. **PR-2 review lane** — this PR is doc-canon only. Who is the right Jigo reviewer? ## Reviewer assignment Per J7 prior directive ('don't assign the roles until we get to that point'), no reviewers are pre-assigned. Will assign at review time per question #9. ## Test plan - [ ] J7 visual review of all 13 file changes - [ ] Confirm Mnemosyne scoping language matches J7's intent (shared DB with `author_id`/`channel_id` filtering) - [ ] Confirm GBrain placement (in scope, undefined, Phase P11) - [ ] Confirm Karakeep owner swap (was San-consumer → now Mokku-taxonomy) - [ ] Confirm external coder workers naming normalization (5 CLIs, no 6th yet) - [ ] Jigo review (per ADR 0001) - [ ] Ashitaka review (multi-domain decomposition) ## Provenance - v1.0 (2201 bytes, J7 original) — commit sha `908aae4a4b…` on `main` - v1.1 (26995 bytes, San canonicalization) — commit `21dee6d` on branch `spec/starros-stack-canonicalization` (PR #1, open) - v2.0 (this revision, doc-canon pass) — commits `8e376e5` + `b55107d` on branch `docs/starros-doc-canon-pass` (this PR) — San
v2.0 of specs/starros-stack-spec.md (14088 bytes, was 26995):
- Adds §0 'Scope: target architecture vs current implementation state'
  so the spec stops absorbing debug-notebook cross-references.
- Trims runtime facts (port maps, broken services, drift) out of
  architecture — moves them to docs/runtime-state.md.
- Renames §14 to 'Recommendations' (3 spec-shape only) and drops the
  Ashitaka debug-action recommendation (it was a runtime concern, not
  architectural).
- Adds ADR 0003 link in §12.

5 new companion docs:
- docs/runtime-state.md (live operational state; per-week rewrite)
- specs/gbrain-substrate.md (project substrate, in-scope per J7 2026-07-09)
- docs/persistence-boundaries.md ('where do I write this?' map)
- docs/external-workers.md (CLI workers policy; 5 in scope)
- decisions/0003-canonical-spec-boundaries.md (rationale + glossary)

Cross-references in the spec point at the companion docs; spec is now
the target architecture only.

Refs: ADR 0001 (repo is source of truth), PR #1 (commit 21dee6d),
specs/starros-stack-spec.md v1.1.
- kanban/backlog.md: drop E1 (Mission Control — paused), add E1
  doc-canon epic (T1-T7), rename E2-T1 OKF/GBrain → GBrain, add E3
  runtime-ops epic mapped to phases P0-P13.
- packets/leaf-card-template.md: add 'Report-back channel' field
  (default: project's Matrix room; see docs/external-workers.md §6).
  Honor docs/external-workers.md in Constraints.
- prompts/san-handoff.md: expand reading list to 15 docs including the
  5 new companion docs (runtime-state, persistence-boundaries,
  external-workers, gbrain-substrate, ADR 0003).
- prompts/fable-global.md: add 'Paused components' callout with
  cross-reference to ADR 0003 §Glossary.
- docs/playbook.md: add 'Companion docs' section pointing at the 5
  new docs; rename 'Status: Draft v0' → 'v1'; add 'canonical' line
  at top.
- docs/workflow.md: tighten to canonical doc references; rename
  'Claude Code' → 'external coder workers' per docs/external-workers.md
  §7 naming normalization.
- decisions/0001-repo-is-source-of-truth.md: add 'Related: ADR 0003'
  and stronger consequences (per-week doc-canon pattern).
san closed this pull request 2026-07-09 15:54:21 -04:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
j7/StarrOS!2
No description provided.