doc updates

This commit is contained in:
ari committed 2026-10-19 14:14:29 -04:00
1 parent 7e1bd4a9a4
commit a511ff532e
26 files changed
+573 -770

No files matched your search

+20 -49
View File
@@ -1,54 +1,25 @@
# Workboard
# Planning the next phase
Markdown workboard for building skyg-linux-tracker (CLI: `slinuxm`). The design lives in [`../plan.md`](../plan.md). This folder tracks the work.
`plan/` is only for planning the next big piece of work, before it starts. It is empty of plans while the current board is clean.
| File | Purpose |
Where other things live:
| What | Where |
|---|---|
| [`BOARD.md`](BOARD.md) | Kanban view. One row per workstream card, moved between columns. |
| [`../TODO.md`](../TODO.md) | Master checklist. The only place task checkboxes are ticked. |
| [`workstreams/`](workstreams/) | One card per workstream: goal, owned files, dependencies, design notes, done criteria, log. |
| [`review.md`](review.md) | Design review of `plan.md`. Corrections and gaps, each mapped to a task. |
| [`decisions.md`](decisions.md) | Decision log. Open questions and proposed defaults. |
| Work tracking and checkboxes | [`../TODO.md`](../TODO.md) (tick boxes only there) |
| Current design and decisions | [`../ARCHITECTURE.md`](../ARCHITECTURE.md) |
| Long-form docs | [`../docs/`](../docs/README.md) |
| Records of finished workstreams | [`../docs/workstreams/`](../docs/workstreams/) |
## Cards
## Proposing a phase plan
| Card | Phase | Depends on | Owned files |
|---|---|---|---|
| [P0 Foundation](workstreams/P0-foundation.md) | 0 | — | `Cargo.toml`, `devenv.nix`, `config.example.toml`, `src/main.rs`, `src/config.rs`, `src/error.rs`, `src/state.rs`, `src/sources/mod.rs`, `src/sources/fake.rs`, all stubs |
| [WS-A systemd](workstreams/WS-A-systemd.md) | 1 | P0 | `src/sources/systemd.rs`, `examples/systemd_dump.rs` |
| [WS-B journal](workstreams/WS-B-journal.md) | 1 | P0 | `src/sources/journal.rs`, `examples/journal_tail.rs` |
| [WS-C docker](workstreams/WS-C-docker.md) | 1 | P0 | `src/sources/docker.rs`, `examples/docker_ps.rs` |
| [WS-D auth + DB](workstreams/WS-D-auth.md) | 1 | P0 | `src/db.rs`, `src/auth/`, `migrations/` |
| [WS-E REST](workstreams/WS-E-rest.md) | 2 | P0 (fakes); A, B, C, D to finish | `src/api/` |
| [WS-F MCP](workstreams/WS-F-mcp.md) | 2 | P0 (fakes); A, B, C, D to finish | `src/mcp/` |
| [WS-G OTel](workstreams/WS-G-otel.md) | 2 | P0 (fakes); A, B, C to finish | `src/telemetry/`, `dev/otelcol.yaml` |
| [P3 Integration](workstreams/P3-integration.md) | 3 | E, F, G | `src/main.rs` (wiring), `systemd/`, `README.md`, `tests/` |
| [WS-I TLS](workstreams/WS-I-tls.md) | 4 | P3 | `src/tls.rs`, `server.tls` config keys, `tests/tls.rs` |
| [WS-H NixOS](workstreams/WS-H-nixos.md) | 4 | P3, WS-I | `flake.nix`, `nix/` |
## Dependency graph
```
P0 Foundation (config, DTOs, traits+fakes, AppState, stubs)
├── WS-A systemd ──┐
├── WS-B journal ──┤
├── WS-C docker ───┼──► WS-E REST ──┐
└── WS-D auth ─────┤ WS-F MCP ───┼──► P3 Integration
└──► WS-G OTel ──┘
P3 Integration ──► WS-I TLS ──► WS-H NixOS (package + module + CLI + VM test)
```
With source traits and fakes (DEC-2), Phase 2 cards can **start** as soon as P0 is done. They **finish** only once their real sources are merged and verified against a live host.
**Solo order:** P0 → A → B → C → D → E → F → G → P3.
## Rules
1. **Status flow:** `Backlog` → `Ready` → `In progress` → `Review` → `Done`, plus `Blocked` with a reason. A card becomes `Ready` when everything in its "Depends on" is `Done`, or when it can run against fakes.
2. **One owner per card.** Put the name (or agent/branch) in the card's Owner field and on the board.
3. **File ownership is strict.** A card edits only its owned files. If it needs a change in someone else's file, typically a DTO in `src/sources/mod.rs`, raise it in the card log and make the change as a small separate commit agreed with that file's owner.
4. **Tick tasks in `TODO.md`.** Cards describe tasks but do not carry checkboxes, so there is one source of truth.
5. **A card moves to `Done`** when every task is ticked, its "Done when" criteria are demonstrated, and `cargo clippy -- -D warnings` + `cargo test` pass.
6. **Decisions go in `decisions.md`.** Record the outcome there and link it from the card log.
7. **Branch naming:** `ws-a/systemd-source`, `p0/foundation`, and so on.
1. Copy [`TEMPLATE.md`](TEMPLATE.md) to `plan/<short-name>.md` (for example `plan/phase-5-alerting.md`).
2. Fill in:
- **Goal**: what changes for users or operators, in a few sentences.
- **Scope**: what is in, and explicitly what is out.
- **Workstreams**: independent tracks with owned files, dependencies and done criteria, so they can run in parallel without merge conflicts.
- **Open decisions**: questions that need a human call, each with options and a recommendation.
- **Exit criteria**: how you will know the phase is done (commands to run, behaviour to demonstrate).
3. Review and settle the open decisions in the plan file.
4. When the plan is accepted, move the work into [`../TODO.md`](../TODO.md): add the phase milestone and one checklist per workstream with stable task IDs. Fold the accepted decisions into the Decisions section of [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
5. When the phase finishes, move the plan file (and any per-workstream notes) to `docs/workstreams/` as an archived record and collapse its tasks in `TODO.md` into the Completed table.