File created successfully at: C:\Users\decid\Documents\projects\spt-core\.claude\doyle-commune.md (file state is current in your context — no need to Read it back)

<live-context>
Role this session: design partner driving spt-core's full planning corpus via /grill-with-docs — relentless one-decision-at-a-time interviewing, capturing into CONTEXT.md + ADRs + design docs inline, committing to GitHub as we go. The pattern is highly productive and the user engages deeply (challenges, refines, adds requirements mid-stream).

Cross-project learning worth keeping: when researching exemplars (docs, prior art), a *firsthand-artifact* pass (fetch the real files/structures) yields far better, copy-able templates than secondhand teardown articles. Did this twice (docs strategy, pi-agent-memory) with strong payoff. Apply this pattern to future research tasks.

Working note: $LIVE env var went stale mid-session (pointed at owl.exe 1.11.20 after the binary moved to 1.11.22); resolve the live binary by checking the cplugs/spt/<ver>/ cache dirs if $LIVE/$OWL fail.
</live-context>
<project-context>
**spt-core planning is COMPLETE — all PRD §17 open design-phase items resolved.** Repo: github.com/SaberMage/spt-core (private), HEAD 7e3826f, working tree clean.

**Since my last context (which showed 17.5 as "awaiting 4 decisions"):**
- **17.5 consent/security-gate RESOLVED** (committed 51b485d). User agreed all 4: hybrid model (grant store: capability×agent×target-node, target-enforced, subnet-settable, revocable + interactive escalation: prompt to most-recently-active session, allow-once/always/deny + AskUserQuestion free-text). granularity capability×agent×target-node is sufficient. v1 ships framework seam; gated capabilities (remote-exec, instantiate-anywhere) land into it later. CONTEXT §Consent & security gates.
- **ROADMAP.md recorded** (committed 7e3826f).

**Scope decisions (LOCKED this session):**
- v1 = the FULL PRD, networking included — the networked element is the whole reason spt-core exists; NOT deferrable to v1.1.
- The hard freeze on claude_skill_owl is NOT a schedule clock — it works today and delivers value as-is while spt-core is built. No time pressure.
- Process: lightweight-but-structured. GSD is too heavy. ROADMAP.md + the design docs are the structure.

**Path to fruition (ROADMAP.md):** Stage A red-team review → Stage B de-risk spikes → Stage C walking skeleton (two agents exchange a message, local then cross-node) → Stage D phased build M0–M5 (M0 workspace+proto+store, M1 local messaging+binary, M2 harness contract+lifecycle+spt-plugin parity, M3 terminal wrapper+daemon+self-update, M4 networking+instances, M5 shells+presence+deferred).

**IMMEDIATE NEXT STEPS (next session):**
1. Stage A review — run plan-eng-review on the architecture + a codex adversarial pass; capture findings. (NOT to cut scope — v1 is locked full — but to surface contradictions / over-engineering / unproven assumptions.)
2. De-risk spike #1 (broker/brain no-terminate handoff — the hardest invariant, ADR-0004) and spike #2 (Iroh + mDNS cross-NAT smoke test — research brief §5). Throwaway. These two most threaten the design.
3. Fold review + spike results back into ADRs/CONTEXT (amend if anything breaks).
4. Then start M0 (Cargo workspace + spt-proto + spt-store, copy-verbatim commodity layer per ADR-0001).

**PROJECT END GOAL:** a harness-independent core for an agent ecosystem (messaging, live-agent lifecycle, terminal hosting, first-class P2P networking, runtime-manifest harness contract) as Rust crates + a single `spt` binary. The proof: the same agent runs natively across all a user's machines with a synced mind, reachable + operable from anywhere, with seamless self-update and zero-config cross-machine messaging. First thing built atop it: a rebuilt `spt` plugin at parity with today's modern SPT.

**Doc corpus (all on GitHub):** PRD.md, ROADMAP.md, CONTEXT.md (glossary/model), docs/adr/0001–0005, docs/{KNOWN-HAZARDS, DEFERRED, STORAGE, MANIFEST, DOCS-STRATEGY, CONTEXT-MEMORY}.md. 10 commits.

**Deferred items logged (docs/DEFERRED.md):** block-level OCC context merge; rebalance/Memory-Health pass; consent framework's gated capabilities; concrete Shells; PresenceChannel impl; instantiate-anywhere; remote-exec; sidecar adapters; manifest includes; scrollback spillover; macOS.
</project-context>


Done. Commune written to `.claude/doyle-commune.md` (two-slice) — the Self listener will detect it on its next poll and the Psyche ingests it for next-session pickup. (It's gitignored, so it won't pollute the repo; deleted on successful ingest.)

## Session wrap

**spt-core planning is complete.** From a blank directory, this session produced a full, internally-consistent planning corpus on `github.com/SaberMage/spt-core` (private, 10 commits):

- **PRD.md** + **ROADMAP.md** + **CONTEXT.md** (glossary/model)
- **5 ADRs** (clean-room fork · bake-networking · multi-instance · broker/brain+self-update · TOTP-SPAKE2)
- **6 design docs** (KNOWN-HAZARDS, DEFERRED, STORAGE, MANIFEST, DOCS-STRATEGY, CONTEXT-MEMORY)

**Locked this session, end to end:** deliverable shape · clean-room build + freeze · harness contract (manifest seams + `api` surface + startup topologies) · terminal wrapper + launcher · networking baked-in · Shells (full model + sleep/wake/shutdown) · multi-instance + dormancy · self-update · pairing · install + migration · cross-node context sync (P2P + opt-in GitHub hub) · dual-audience docs strategy · Psyche context/memory + memformat redesign · consent model · and all 6 PRD §17 open items.

**Scope locked:** v1 = full PRD (networking is the point) · freeze isn't a clock · lightweight-but-structured.

## Next session picks up at
1. **Red-team review** — `plan-eng-review` + `codex` adversarial pass (surface contradictions/over-engineering/unproven assumptions; not to cut scope).
2. **De-risk spikes** — #1 broker/brain no-terminate handoff (hardest invariant) + #2 Iroh+mDNS cross-NAT smoke test. The two that most threaten the design.
3. Fold findings back into the ADRs.
4. Then **M0** — workspace + `spt-proto` + `spt-store`.

Solid place to pause. The commune carries all of this forward.


question before moving on: would /traceable-reqs be valuable to integrate into spt-core's development?


<owl_reachability_notice>
You have an active owl perch. When spawning subagents or doing work, use run_in_background: true so you stay reachable for incoming messages.
</owl_reachability_notice>


CAVEMAN MODE ACTIVE (full). Drop articles/filler/pleasantries/hedging. Fragments OK. Code/commits/security: write normal.


Let me actually look at what `/traceable-reqs` does before judging — its listed description is just a stub.


Bash

find "C:/Users/decid/.claude" -ipath "*traceable*" -name "*.md" 2>/dev/null | head -20

Locate traceable-reqs skill files


1	---
2	name: traceable-reqs
3	description: Install or update the traceable-reqs CLI and apply it correctly in host repos: author manifests, place tags near evidence, audit scan roots, interpret findings, and answer coverage questions through the CLI.
4	allowed-tools: Bash, PowerShell, Read
5	---
6
7	# traceable-reqs
8
9	Use this skill for both installation and day-to-day use of `traceable-reqs`.
10	The CLI reads a required `traceable-reqs.toml`, scans configured roots for
11	`[stage->REQ-ID]` tags, and reports whether manifest-declared requirements have
12	the required evidence stages.
13
14	## Applying traceable-reqs to a repo
15
16	Start with the manifest, then place tags close to the evidence they prove.
17	Do not satisfy coverage by putting tags at the top of a file; that is noisy and
18	usually wrong. A tag belongs on or immediately above the function, test, config
19	entry, doc section, or workflow step that actually satisfies that stage.
20
21	Minimum manifest:
22
23	```toml
24	[scan]
25	roots = ["src", "tests", "docs"]
26
27	[policy]
28	required_stages = ["doc", "impl", "unit"]
29
30	[[requirements]]
31	id = "REQ-LOGIN"
32	title = "User can sign in"
33	required_stages = ["doc", "impl", "unit", "int"]
34	```
35
36	Audit `[scan].roots` against the real project tree before trusting coverage.
37	If implementation lives in `.github/workflows`, `scripts`, `cmake`, or another
38	directory, include it or the evidence will silently disappear from the trace.
39
40	Requirement IDs must match `REQ-[A-Z0-9-]+`, with hyphen-separated uppercase
41	segments. Prefer title-derived slugs such as `REQ-LOGIN-LOCKOUT` over bare
42	numeric counters. IDs like `FR-001`, `NFR-002`, or `CON-010` are not valid unless
43	they are written as `REQ-FR-001`, `REQ-NFR-002`, or `REQ-CON-010`.
44
45	## Stages
46
47	Built-in stages are exactly:
48
49	- `doc`: prose or design documentation.
50	- `impl`: production implementation.
51	- `unit`: unit tests.
52	- `int`: integration, end-to-end, workflow, or system-level tests.
53
54	Domain words such as HIL, e2e, smoke, QC, or security are not built-in stages.
55	Map them to the closest built-in stage, usually `int`, or declare a custom stage
56	in the manifest before using it:
57
58	```toml
59	[stages.qc]
60	description = "QC engineer signoff"
61	```
62
63	A tag with an undeclared stage, such as `[hil->REQ-CAMERA]`, is a `parse_error`.
64
65	## Tag examples
66
67	```rust
68	// [impl->REQ-LOGIN]
69	fn authenticate(...) { ... }
70	```
71
72	```python
73	# [unit->REQ-LOGIN]
74	def test_login_accepts_valid_password(): ...
75	```
76
77	```markdown
78	<!-- [doc->REQ-LOGIN] -->
79	# Login
80	```
81
82	Any bracketed text that looks like a tag candidate must be exact. A placeholder
83	like `[stage->REQ-ID]` in scanned Markdown can become a `parse_error`; escape it,
84	remove the arrow, or keep examples outside scanned roots when needed.
85
86	## Command choice
87
88	Use the CLI for coverage questions, not grep. Grep does not know scan roots,
89	comment-only rules, custom stages, docstrings, or parse errors.
90
91	- `traceable-reqs check --json`: full coverage and findings for CI or audit.
92	- `traceable-reqs list --json`: all requirements without treating findings as a failing command.
93	- `traceable-reqs list --missing impl`: requirements missing a required stage.
94	- `traceable-reqs list --type FR`: requirements of one declared type.
95	- `traceable-reqs trace REQ-LOGIN`: evidence and findings for one requirement.
96	- `traceable-reqs review`: agent-facing prompt to inspect tag placement quality.
97	- `traceable-reqs lint`: agent-facing prompt plus deterministic title-quality findings.
98
99	`check` returning exit code 1 means findings were produced; it is not a pipe or
100	runtime failure by itself. Read stdout or use `--json` to inspect the findings.
101	Operational failures such as bad arguments, invalid manifests, or unreadable
102	files report diagnostics on stderr.
103
104	## Common findings
105
106	- `missing_stage`: the requirement is declared but lacks evidence for a required stage. First check tag placement and scan roots.
107	- `undeclared_id`: a tag references an ID not in `traceable-reqs.toml`. First check for typos and invalid ID prefixes.
108	- `parse_error`: a tag-shaped token is malformed, uses an undeclared stage, has spaces, or has an invalid requirement ID.
109	- `manifest_error`: the manifest is missing, invalid TOML, invalid UTF-8, has duplicate IDs, bad stages, bad types, or invalid scan roots.
110	- `scan_error`: a scanned file could not be read.
111
112	On Windows, avoid writing the manifest with a UTF-16 redirect. Use an editor,
113	the Write tool, or `Out-File -Encoding utf8NoBOM` so TOML parsing sees UTF-8.
114
115	For placeholder requirements that intentionally have no evidence yet, set
116	`required_stages = []` so `check` does not report missing coverage until the
117	requirement is ready.
118
119	## Installation
120
121	Installs the latest `traceable-reqs` binary from a GitHub Release into a per-user location, verifies it runs, and prints PATH advice. Does not mutate the user's shell rc files or environment automatically — PATH changes are user intent, so surface the line and let them act on it.
122
123	## Defaults
124
125	- Repo: `BigscreenVR/traceable-reqs`
126	- Version: latest release tag
127	- Install dir: `~/.local/bin` on Linux/macOS, `%LOCALAPPDATA%\Programs\traceable-reqs` on Windows
128
129	Override per-call via env vars: `TRACEABLE_REQS_REPO`, `TRACEABLE_REQS_VERSION`, `TRACEABLE_REQS_INSTALL_DIR`.
130
131	## Procedure
132
133	1. **Verify `gh`.** Run `gh auth status`. If `gh` is missing or returns non-zero, stop and tell the user to install it from https://cli.github.com/ then run `gh auth login`. `gh auth login` is interactive — do not attempt to run it for them.
134
135	2. **Detect platform and target.**
136	   - macOS / Linux: use Bash. Read `uname -s` and `uname -m`, then map:
137	     - `Linux` + `x86_64` → target `linux-x86_64`
138	     - `Darwin` + `arm64` → target `macos-arm64`
139	   - Native Windows: use PowerShell. Target is `windows-x86_64.exe`.
140	   - Anything else (Linux arm64, Intel Mac, MINGW/Cygwin) is not in the release matrix. Stop and tell the user to build from source: `cargo install --git <repo-url>`.
141
142	3. **Resolve version.** If `TRACEABLE_REQS_VERSION` is set, use it. Otherwise `gh release view --repo <repo> --json tagName -q .tagName`.
143
144	4. **Download.** Asset name is `traceable-reqs-<version>-<target>`. Make the install dir if needed, then:
145
146	   ```
147	   gh release download <version> --repo <repo> --pattern <asset> --output <install-dir>/<binary> --clobber
148	   ```
149
150	   Binary name is `traceable-reqs` on Unix, `traceable-reqs.exe` on Windows.
151
152	5. **Make executable** (Unix only): `chmod +x <install-dir>/traceable-reqs`.
153
154	6. **Verify.** Run `<install-dir>/<binary> --version`. If it errors, stop and report.
155
156	7. **PATH advice.** Check if the install dir is on `PATH`. If yes, done. If no, print these for the user to copy — do not execute them:
157	   - Bash / zsh: `export PATH="<install-dir>:$PATH"` (and add to `~/.bashrc` or `~/.zshrc` for persistence).
158	   - PowerShell, current session: `$env:PATH = "<install-dir>;" + $env:PATH`
159	   - PowerShell, persistent (open a new shell to take effect): `[Environment]::SetEnvironmentVariable('PATH', '<install-dir>;' + [Environment]::GetEnvironmentVariable('PATH','User'), 'User')`
160
161	## Failure modes
162
163	- `gh` missing → install link, stop.
164	- `gh` not authenticated → `gh auth login`, stop (interactive — user does it).
165	- Unsupported target → "no prebuilt for `<target>`; build from source with `cargo install --git`".
166	- Asset not found → likely the release matrix did not finish; have the user check `gh release view <tag> --repo <repo>`.
167

---
name: traceable-reqs
description: Install or update the traceable-reqs CLI and apply it correctly in host repos: author manifests, place tags near evidence, audit scan roots, interpret findings, and answer coverage questions through the CLI.
allowed-tools: Bash, PowerShell, Read
---

# traceable-reqs

Use this skill for both installation and day-to-day use of `traceable-reqs`.
The CLI reads a required `traceable-reqs.toml`, scans configured roots for
`[stage->REQ-ID]` tags, and reports whether manifest-declared requirements have
the required evidence stages.

## Applying traceable-reqs to a repo

Start with the manifest, then place tags close to the evidence they prove.
Do not satisfy coverage by putting tags at the top of a file; that is noisy and
usually wrong. A tag belongs on or immediately above the function, test, config
entry, doc section, or workflow step that actually satisfies that stage.

Minimum manifest:

```toml
[scan]
roots = ["src", "tests", "docs"]

[policy]
required_stages = ["doc", "impl", "unit"]

[[requirements]]
id = "REQ-LOGIN"
title = "User can sign in"
required_stages = ["doc", "impl", "unit", "int"]
```

Audit `[scan].roots` against the real project tree before trusting coverage.
If implementation lives in `.github/workflows`, `scripts`, `cmake`, or another
directory, include it or the evidence will silently disappear from the trace.

Requirement IDs must match `REQ-[A-Z0-9-]+`, with hyphen-separated uppercase
segments. Prefer title-derived slugs such as `REQ-LOGIN-LOCKOUT` over bare
numeric counters. IDs like `FR-001`, `NFR-002`, or `CON-010` are not valid unless
they are written as `REQ-FR-001`, `REQ-NFR-002`, or `REQ-CON-010`.

## Stages

Built-in stages are exactly:

- `doc`: prose or design documentation.
- `impl`: production implementation.
- `unit`: unit tests.
- `int`: integration, end-to-end, workflow, or system-level tests.

Domain words such as HIL, e2e, smoke, QC, or security are not built-in stages.
Map them to the closest built-in stage, usually `int`, or declare a custom stage
in the manifest before using it:

```toml
[stages.qc]
description = "QC engineer signoff"
```

A tag with an undeclared stage, such as `[hil->REQ-CAMERA]`, is a `parse_error`.

## Tag examples

```rust
// [impl->REQ-LOGIN]
fn authenticate(...) { ... }
```

```python
# [unit->REQ-LOGIN]
def test_login_accepts_valid_password(): ...
```

```markdown
<!-- [doc->REQ-LOGIN] -->
# Login
```

Any bracketed text that looks like a tag candidate must be exact. A placeholder
like `[stage->REQ-ID]` in scanned Markdown can become a `parse_error`; escape it,
remove the arrow, or keep examples outside scanned roots when needed.

## Command choice

Use the CLI for coverage questions, not grep. Grep does not know scan roots,
comment-only rules, custom stages, docstrings, or parse errors.

- `traceable-reqs check --json`: full coverage and findings for CI or audit.
- `traceable-reqs list --json`: all requirements without treating findings as a failing command.
- `traceable-reqs list --missing impl`: requirements missing a required stage.
- `traceable-reqs list --type FR`: requirements of one declared type.
- `traceable-reqs trace REQ-LOGIN`: evidence and findings for one requirement.
- `traceable-reqs review`: agent-facing prompt to inspect tag placement quality.
- `traceable-reqs lint`: agent-facing prompt plus deterministic title-quality findings.

`check` returning exit code 1 means findings were produced; it is not a pipe or
runtime failure by itself. Read stdout or use `--json` to inspect the findings.
Operational failures such as bad arguments, invalid manifests, or unreadable
files report diagnostics on stderr.

## Common findings

- `missing_stage`: the requirement is declared but lacks evidence for a required stage. First check tag placement and scan roots.
- `undeclared_id`: a tag references an ID not in `traceable-reqs.toml`. First check for typos and invalid ID prefixes.
- `parse_error`: a tag-shaped token is malformed, uses an undeclared stage, has spaces, or has an invalid requirement ID.
- `manifest_error`: the manifest is missing, invalid TOML, invalid UTF-8, has duplicate IDs, bad stages, bad types, or invalid scan roots.
- `scan_error`: a scanned file could not be read.

On Windows, avoid writing the manifest with a UTF-16 redirect. Use an editor,
the Write tool, or `Out-File -Encoding utf8NoBOM` so TOML parsing sees UTF-8.

For placeholder requirements that intentionally have no evidence yet, set
`required_stages = []` so `check` does not report missing coverage until the
requirement is ready.

## Installation

Installs the latest `traceable-reqs` binary from a GitHub Release into a per-user location, verifies it runs, and prints PATH advice. Does not mutate the user's shell rc files or environment automatically — PATH changes are user intent, so surface the line and let them act on it.

## Defaults

- Repo: `BigscreenVR/traceable-reqs`
- Version: latest release tag
- Install dir: `~/.local/bin` on Linux/macOS, `%LOCALAPPDATA%\Programs\traceable-reqs` on Windows

Override per-call via env vars: `TRACEABLE_REQS_REPO`, `TRACEABLE_REQS_VERSION`, `TRACEABLE_REQS_INSTALL_DIR`.

## Procedure

1. **Verify `gh`.** Run `gh auth status`. If `gh` is missing or returns non-zero, stop and tell the user to install it from https://cli.github.com/ then run `gh auth login`. `gh auth login` is interactive — do not attempt to run it for them.

2. **Detect platform and target.**
   - macOS / Linux: use Bash. Read `uname -s` and `uname -m`, then map:
     - `Linux` + `x86_64` → target `linux-x86_64`
     - `Darwin` + `arm64` → target `macos-arm64`
   - Native Windows: use PowerShell. Target is `windows-x86_64.exe`.
   - Anything else (Linux arm64, Intel Mac, MINGW/Cygwin) is not in the release matrix. Stop and tell the user to build from source: `cargo install --git <repo-url>`.

3. **Resolve version.** If `TRACEABLE_REQS_VERSION` is set, use it. Otherwise `gh release view --repo <repo> --json tagName -q .tagName`.

4. **Download.** Asset name is `traceable-reqs-<version>-<target>`. Make the install dir if needed, then:

   ```
   gh release download <version> --repo <repo> --pattern <asset> --output <install-dir>/<binary> --clobber
   ```

   Binary name is `traceable-reqs` on Unix, `traceable-reqs.exe` on Windows.

5. **Make executable** (Unix only): `chmod +x <install-dir>/traceable-reqs`.

6. **Verify.** Run `<install-dir>/<binary> --version`. If it errors, stop and report.

7. **PATH advice.** Check if the install dir is on `PATH`. If yes, done. If no, print these for the user to copy — do not execute them:
   - Bash / zsh: `export PATH="<install-dir>:$PATH"` (and add to `~/.bashrc` or `~/.zshrc` for persistence).
   - PowerShell, current session: `$env:PATH = "<install-dir>;" + $env:PATH`
   - PowerShell, persistent (open a new shell to take effect): `[Environment]::SetEnvironmentVariable('PATH', '<install-dir>;' + [Environment]::GetEnvironmentVariable('PATH','User'), 'User')`

## Failure modes

- `gh` missing → install link, stop.
- `gh` not authenticated → `gh auth login`, stop (interactive — user does it).
- Unsupported target → "no prebuilt for `<target>`; build from source with `cargo install --git`".
- Asset not found → likely the release matrix did not finish; have the user check `gh release view <tag> --repo <repo>`.


1	# Traceable Reqs
2
3	**NLSpec** (natural-language specification) for a requirements-tracing CLI—organized like [strongdm/attractor](https://github.com/strongdm/attractor): point an agent at the spec to implement the tool or verify behavior.
4
5	The tool follows the spirit of [OpenFastTrace](https://github.com/itsallcode/openfasttrace): tag-based traces across languages, with a focus on **coding agents** and **CI**.
6
7	> **Status:** the spec is the primary artifact at the repo root. A reference Rust implementation lives in [`rust/`](rust/) — `cd rust && cargo build` produces `rust/target/debug/traceable-reqs`. Run the binary from a directory that holds `traceable-reqs.toml` (e.g. `cd example && ../rust/target/debug/traceable-reqs check --json`). Issues and PRs welcome.
8
9	## Install
10
11	### If you are human
12
13	Tell your coding agent (Claude Code, etc.):
14
15	```
16	Read README.md from BigscreenVR/traceable-reqs and follow the install instructions there.
17	```
18
19	### If you've been sent here by your human
20
21	Clone this repo into the user's Claude skills directory, then follow [`SKILL.md`](SKILL.md):
22
23	- **Claude Code:** `gh repo clone BigscreenVR/traceable-reqs ~/.claude/skills/traceable-reqs`
24
25	Then read `~/.claude/skills/traceable-reqs/SKILL.md` and execute the install procedure: resolve the latest release, `gh release download` the matching platform asset (`linux-x86_64`, `macos-arm64`, or `windows-x86_64.exe`), drop it in `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\Programs\traceable-reqs` (Windows), `chmod +x` if Unix, verify with `--version`, and surface the PATH line if needed.
26
27	Requires `gh` ([install](https://cli.github.com/)) authenticated via `gh auth login`. The skill stays in `~/.claude/skills/traceable-reqs` — re-invoke any time with "install traceable-reqs" to update. Without Claude: follow [`SKILL.md`](SKILL.md) by hand, or build from source with `cd rust && cargo build --release`.
28
29	## What the tool does
30
31	The specified CLI is **written in Rust**. It reads the required **`traceable-reqs.toml`** manifest as the authoritative list of requirement IDs, scans configured files for **`[stage->requirement-id]`** tags, reports missing required documentation, implementation, unit-test, and integration-test evidence, and exposes the same trace facts through pyramid-friendly human and agent output plus structured JSON.
32
33	---
34
35	## Spec
36
37	Read [**SPEC.md**](SPEC.md). It is the source of truth for the core behavior and optional capabilities: manifest shape, tag grammar, trace completeness, commands, findings, examples, and extension details.
38
39	---
40
41	## Terminology
42
43	- **NLSpec:** a human-readable specification meant for coding agents (and humans) to implement or check behavior—following the usage in [Attractor](https://github.com/strongdm/attractor).
44
45	---
46
47	## Non-goals
48
49	- Replacing GitHub Issues (or your planner).
50	- Full ReqIF or OpenFastTrace interchange.
51	- Shipping a deep IDE plugin for every editor on day one—**CLI first**.
52
53	---
54
55	## Prior art
56
57	- [OpenFastTrace](https://github.com/itsallcode/openfasttrace) — tag-based tracing across languages.
58	- [Sphinx-Needs](https://www.sphinx-needs.com/), [Doorstop](https://github.com/doorstop-dev/doorstop), [ReqIF](https://www.omg.org/spec/ReqIF/) — other requirement workflows.
59
60	---
61
62	## Implementing
63
64	Example prompt for a coding agent:
65
66	```
67	Implement the traceable-reqs tool from SPEC.md in this repository.
68	```
69
70	Point the agent at the **root of this repo** (or a published URL). Implement against [**SPEC.md**](SPEC.md).
71
72	---
73
74	## Scope
75
76	The core behavior is intentionally small: required **`traceable-reqs.toml` manifest** with authoritative IDs; comment scanning for Rust, Python, C/C++, JavaScript/TypeScript, Markdown, CMake, and YAML; stages `doc`, `impl`, `unit`, `int`; manifest-driven required stages; pyramid reporting; CLI commands `list`, `trace`, **`check`**, with `--json` for structured output.
77
78	Additional capabilities such as include/exclude globs, priority gates, custom stage definitions, and stability promises are defined in [**SPEC.md**](SPEC.md). Implementation order is up to the implementor.
79
80	Optional later: a small Rust **library** for deeper integration—not required to use the CLI.
81
82	---
83
84	## License
85
86	Default intent: **Apache-2.0 OR MIT** dual license once `LICENSE` files are added. Submitting PRs implies you are ok with that choice unless you state otherwise.
87

# Traceable Reqs

**NLSpec** (natural-language specification) for a requirements-tracing CLI—organized like [strongdm/attractor](https://github.com/strongdm/attractor): point an agent at the spec to implement the tool or verify behavior.

The tool follows the spirit of [OpenFastTrace](https://github.com/itsallcode/openfasttrace): tag-based traces across languages, with a focus on **coding agents** and **CI**.

> **Status:** the spec is the primary artifact at the repo root. A reference Rust implementation lives in [`rust/`](rust/) — `cd rust && cargo build` produces `rust/target/debug/traceable-reqs`. Run the binary from a directory that holds `traceable-reqs.toml` (e.g. `cd example && ../rust/target/debug/traceable-reqs check --json`). Issues and PRs welcome.

## Install

### If you are human

Tell your coding agent (Claude Code, etc.):

```
Read README.md from BigscreenVR/traceable-reqs and follow the install instructions there.
```

### If you've been sent here by your human

Clone this repo into the user's Claude skills directory, then follow [`SKILL.md`](SKILL.md):

- **Claude Code:** `gh repo clone BigscreenVR/traceable-reqs ~/.claude/skills/traceable-reqs`

Then read `~/.claude/skills/traceable-reqs/SKILL.md` and execute the install procedure: resolve the latest release, `gh release download` the matching platform asset (`linux-x86_64`, `macos-arm64`, or `windows-x86_64.exe`), drop it in `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\Programs\traceable-reqs` (Windows), `chmod +x` if Unix, verify with `--version`, and surface the PATH line if needed.

Requires `gh` ([install](https://cli.github.com/)) authenticated via `gh auth login`. The skill stays in `~/.claude/skills/traceable-reqs` — re-invoke any time with "install traceable-reqs" to update. Without Claude: follow [`SKILL.md`](SKILL.md) by hand, or build from source with `cd rust && cargo build --release`.

## What the tool does

The specified CLI is **written in Rust**. It reads the required **`traceable-reqs.toml`** manifest as the authoritative list of requirement IDs, scans configured files for **`[stage->requirement-id]`** tags, reports missing required documentation, implementation, unit-test, and integration-test evidence, and exposes the same trace facts through pyramid-friendly human and agent output plus structured JSON.

---

## Spec

Read [**SPEC.md**](SPEC.md). It is the source of truth for the core behavior and optional capabilities: manifest shape, tag grammar, trace completeness, commands, findings, examples, and extension details.

---

## Terminology

- **NLSpec:** a human-readable specification meant for coding agents (and humans) to implement or check behavior—following the usage in [Attractor](https://github.com/strongdm/attractor).

---

## Non-goals

- Replacing GitHub Issues (or your planner).
- Full ReqIF or OpenFastTrace interchange.
- Shipping a deep IDE plugin for every editor on day one—**CLI first**.

---

## Prior art

- [OpenFastTrace](https://github.com/itsallcode/openfasttrace) — tag-based tracing across languages.
- [Sphinx-Needs](https://www.sphinx-needs.com/), [Doorstop](https://github.com/doorstop-dev/doorstop), [ReqIF](https://www.omg.org/spec/ReqIF/) — other requirement workflows.

---

## Implementing

Example prompt for a coding agent:

```
Implement the traceable-reqs tool from SPEC.md in this repository.
```

Point the agent at the **root of this repo** (or a published URL). Implement against [**SPEC.md**](SPEC.md).

---

## Scope

The core behavior is intentionally small: required **`traceable-reqs.toml` manifest** with authoritative IDs; comment scanning for Rust, Python, C/C++, JavaScript/TypeScript, Markdown, CMake, and YAML; stages `doc`, `impl`, `unit`, `int`; manifest-driven required stages; pyramid reporting; CLI commands `list`, `trace`, **`check`**, with `--json` for structured output.

Additional capabilities such as include/exclude globs, priority gates, custom stage definitions, and stability promises are defined in [**SPEC.md**](SPEC.md). Implementation order is up to the implementor.

Optional later: a small Rust **library** for deeper integration—not required to use the CLI.

---

## License

Default intent: **Apache-2.0 OR MIT** dual license once `LICENSE` files are added. Submitting PRs implies you are ok with that choice unless you state otherwise.


Design spt-core binary and messaging library architecture


Read the spec. `traceable-reqs` is a Rust CLI (BigscreenVR — same org as pi-agent-memory, so a toolchain you're already in) that reads a `traceable-reqs.toml` manifest of `REQ-*` IDs, scans code/tests/docs for `[stage->REQ-ID]` tags, and reports which requirements lack their required evidence stages (`doc`/`impl`/`unit`/`int`) — OpenFastTrace-style, built for coding agents + CI.

**Verdict: yes, genuinely valuable — and spt-core is an unusually good fit.** Reasons:

1. **The requirements already exist in tag-ready form.** The PRD has ~60 tagged requirements (`R-ARCH-1`, `R-INST-8`, `R-NET-2`, `R-DOCS-5`…). They map almost 1:1 to `REQ-*` (just prefix: `R-ARCH-1` → `REQ-ARCH-1`). The hard part of adopting requirement-tracing — *having* clean requirement IDs — is done.

2. **Greenfield + Rust = adopt with zero retrofit.** Tags go in as code/tests/docs are written from M0. No archaeology. This is the ideal moment; retrofitting later is the painful path.

3. **The killer application: KNOWN-HAZARDS becomes CI-enforced.** This is the strongest reason. Those 23 invariants are *exactly the bugs we're rebuilding to avoid re-introducing* — and KNOWN-HAZARDS already ends with a "conformance checklist." Encode each as `REQ-HAZARD-*` requiring `unit`/`int` evidence, and the checklist stops being a doc you hope someone reads and becomes a **CI gate**: every hazard must trace to a passing test or `check` fails. That directly delivers PRD success-criterion #6 ("every KNOWN-HAZARDS invariant has a passing test"), mechanically.

4. **Feeds the existing CI-gate commitment.** DOCS-STRATEGY already mandates CI-gated doc generation; `traceable-reqs check --json` slots right alongside it — coverage of req→doc→impl→test in one gate.

**Honest caveats:**
- Most value lands **at M0+ when there's code** (pre-code, only the `doc` stage has evidence). So: *seed the manifest now* (cheap, and it forces requirement-granularity discipline), *tags + CI gate land with code*.
- Some PRD reqs are coarse (`R-INST-8` bundles a lot) — a few may need splitting for meaningful per-stage evidence. Minor.
- Risk of box-ticking (tag-to-satisfy vs real evidence) — the skill itself warns against it; needs discipline.

**Recommendation:** adopt it, with the high-value move being **KNOWN-HAZARDS-as-traced-requirements**. Concretely:
- Seed `traceable-reqs.toml` now from PRD `R-*` + KNOWN-HAZARDS invariants (`REQ-HAZARD-*`).
- `required_stages = ["doc", "impl", "unit"]`, `int` added for networking/cross-node reqs.
- Wire `check --json` into CI at M0.

Want me to **record this in ROADMAP** (as a tooling/CI decision) and **seed the initial `traceable-reqs.toml`** now from the PRD requirements + the hazard checklist — or note it as an M0 task and move on?


what is the development contract which should be instated to ensure we get the most value out of traceable-reqs, and how will it be enforced?


Good question — the tool is only as valuable as the discipline around it. Here's the development contract I'd instate, in two halves: **the rules** and **how each is enforced**.

## The contract (rules)

1. **The manifest is the authoritative requirement registry.** Every PRD requirement and every KNOWN-HAZARDS invariant exists in `traceable-reqs.toml` as a `REQ-*` ID. No work without a REQ; no REQ without intent to satisfy. The PRD holds prose, the manifest holds ID + `required_stages`.
2. **Tag in the same change as the evidence.** When you write the function/test/doc that satisfies a stage, you add its `[stage->REQ-ID]` tag in that same commit — never "tag later." This single rule is what keeps the trace from drifting.
3. **Evidence-proximate tags, not file-tops.** A tag sits on/immediately-above the real function, test, doc-section, or config that proves the stage. One tag = one piece of real evidence.
4. **KNOWN-HAZARDS are first-class reqs.** Each invariant = `REQ-HAZARD-*` requiring `unit`/`int`. A hazard cannot be "covered" without a test tagging it — the anti-regression promise becomes mechanical.
5. **Activation, not premature failure.** Not-yet-started reqs carry `required_stages = []` so `check` stays green until the req is "activated" (its real stages set when its milestone begins). Deferred items (DEFERRED.md) stay `[]` until promoted.
6. **Scan roots stay honest.** `[scan].roots` includes every evidence location (`src`, `tests`, `docs`, `.github/workflows`, `scripts`) — audited whenever a new evidence dir appears, since missing roots make evidence *silently* vanish.

## Enforcement (four layers — defense in depth)

1. **CI gate (the hard backstop).** `traceable-reqs check --json` runs on every PR/push; exit-1 (any `missing_stage`/`undeclared_id`/`parse_error`/`manifest_error`) **fails the build**. A PR can't merge if it leaves an *activated* req's required stage uncovered. Sits alongside the DOCS-STRATEGY CI gates.
2. **Milestone activation gate (ties it to the roadmap).** Starting a milestone (M0–M5) *activates* the reqs it delivers — flips their `required_stages` from `[]` to the real policy (`doc`/`impl`/`unit`, `+int` for networking/lifecycle). **A milestone isn't done until `check` is green for its reqs.** This is what makes coverage grow *with* the project instead of failing on day one.
3. **Agent-facing rule (because dev-agents build this).** A repo `CLAUDE.md`/`AGENTS.md` instruction: *"When you implement/test/document something satisfying a requirement, tag it `[stage->REQ-ID]` in the same change, and run `traceable-reqs check` before declaring done."* Since we build *with* agents, the contract must be machine-followable — agent discipline + CI as the net. (Eventually dogfoodable as an spt-core hook; for now, instructions + CI.)
4. **Quality audit, not just presence (counters box-ticking).** `check` proves a tag *exists*; `traceable-reqs review` + `lint` audit whether tags sit near *real* evidence and whether titles are meaningful. Run them in CI as **advisory** (or periodically). Presence = hard gate; quality = audited. This is the guard against "tag-to-satisfy-coverage."

Optional 5th: a **pre-push git hook** running `check` locally for fast feedback before CI.

**Net shape:** presence is hard-gated in CI; coverage scales via milestone activation; quality is audited to prevent gaming; agents are instructed to tag-in-the-same-change. The KNOWN-HAZARDS-as-`REQ-HAZARD-*` move is what extracts the most value — it converts "hope we don't re-introduce the sister project's bugs" into a build that fails if any hazard lacks a test.

Want me to **record this as `docs/TRACEABILITY.md`** (the contract), add the **agent rule to a repo `CLAUDE.md`**, **seed `traceable-reqs.toml`** from the PRD `R-*` + KNOWN-HAZARDS invariants (all `required_stages = []` until M0 activates them), and note a **CI snippet** — or just record the contract now and seed the manifest at M0?


do all as suggested


On it — recording all four. Starting with the seeded manifest (PRD `R-*` + KNOWN-HAZARDS invariants, all inactive until milestone activation).


Write

# traceable-reqs manifest for spt-core — SEED.
#
# Authoritative requirement registry: every PRD R-* requirement and every
# KNOWN-HAZARDS invariant lives here as a REQ-* id (see docs/TRACEABILITY.md
# for the development contract).
#
# ACTIVATION MODEL: every requirement starts inactive (`required_stages = []`)
# so `check` stays green pre-code. A milestone (M0-M5) ACTIVATES its requirements
# by setting their real `required_stages`. Validate this seed against the
# installed CLI at M0 (the binary isn't installed yet).

[scan]
roots = ["src", "tests", "docs"]

[policy]
# Default policy applied at activation: doc + impl + unit. Networking/lifecycle
# reqs add "int". Until a req is activated, its per-req `required_stages = []`
# keeps it out of the coverage gate.
required_stages = []

# ───────────────────────────── Architecture / workspace ─────────────────────
[[requirements]]
id = "REQ-ARCH-1"
title = "Many small acyclically-layered crates"
required_stages = []
[[requirements]]
id = "REQ-ARCH-2"
title = "Public SDK surface is spt-proto, spt-runtime, spt-msg"
required_stages = []
[[requirements]]
id = "REQ-ARCH-3"
title = "Wire-protocol version independent of crate semver, N-1 compat window"
required_stages = []
[[requirements]]
id = "REQ-ARCH-4"
title = "Copy-verbatim the commodity layer from the sister project"
required_stages = []

# ───────────────────────────── Daemon ───────────────────────────────────────
[[requirements]]
id = "REQ-DAEMON-1"
title = "One per-machine spt-daemon owning all per-machine state"
required_stages = []
[[requirements]]
id = "REQ-DAEMON-2"
title = "Broker/brain split for seamless self-update"
required_stages = []
[[requirements]]
id = "REQ-DAEMON-3"
title = "Any api invocation auto-starts the daemon if absent"
required_stages = []
[[requirements]]
id = "REQ-DAEMON-4"
title = "Honor every KNOWN-HAZARDS invariant"
required_stages = []

# ───────────────────────────── Harness contract — manifest seams ────────────
[[requirements]]
id = "REQ-MANIFEST-1"
title = "Per-adapter manifest with adapter_name and min_spt_core_version"
required_stages = []
[[requirements]]
id = "REQ-SEAM-SPAWN"
title = "spawn-session seam"
required_stages = []
[[requirements]]
id = "REQ-SEAM-POSTSPAWN"
title = "post-spawn / api bind seam with boot nonce"
required_stages = []
[[requirements]]
id = "REQ-SEAM-PSYCHE"
title = "spawn-psyche seam (fresh + resume templates)"
required_stages = []
[[requirements]]
id = "REQ-SEAM-HISTORY"
title = "History subsystem (fetcher / locate-normalize / native store)"
required_stages = []
[[requirements]]
id = "REQ-SEAM-ACTIVITY"
title = "Activity/idle reported via api sentinels, not PTY quiescence"
required_stages = []
[[requirements]]
id = "REQ-SEAM-INJECT"
title = "inject-input methods configurable per activity-state"
required_stages = []
[[requirements]]
id = "REQ-SEAM-RESUME"
title = "resume-session seam (fresh-with-preload / continue-existing)"
required_stages = []
[[requirements]]
id = "REQ-SEAM-CAPABILITY"
title = "Hostable endpoint-types capability declaration"
required_stages = []
[[requirements]]
id = "REQ-SEAM-UPDATE"
title = "Adapter-update avenue (file-pull / delegated command)"
required_stages = []

# ───────────────────────────── Harness contract — api surface ───────────────
[[requirements]]
id = "REQ-API-1"
title = "api prefix and adapter_name on every machinery invocation"
required_stages = []
[[requirements]]
id = "REQ-API-2"
title = "The api subcommand surface (bind/listen/poll/state/worker/boundary/...)"
required_stages = []
[[requirements]]
id = "REQ-API-3"
title = "commune/signoff are file-drops, not commands"
required_stages = []

# ───────────────────────────── Startup flows ────────────────────────────────
[[requirements]]
id = "REQ-START-1"
title = "Adapters never resolve SPT_HOME; binary on PATH; api bridging only"
required_stages = []
[[requirements]]
id = "REQ-START-2"
title = "Harness-hosted startup: api seed then listen"
required_stages = []
[[requirements]]
id = "REQ-START-3"
title = "spt-hosted startup: spawn-session then api bind (no file)"
required_stages = []
[[requirements]]
id = "REQ-START-4"
title = "Adapter-injected env aliases (SPT/OWL/LIVE)"
required_stages = []

# ───────────────────────────── Endpoints / Shells ───────────────────────────
[[requirements]]
id = "REQ-EP-1"
title = "Day-one endpoint types; open type system"
required_stages = []
[[requirements]]
id = "REQ-EP-2"
title = "Agent endpoints vs Shells distinction in the type model"
required_stages = []
[[requirements]]
id = "REQ-EP-3"
title = "Messaging payloads carry typed operation commands + file blobs"
required_stages = []
[[requirements]]
id = "REQ-EP-4"
title = "PresenceChannel broker endpoint (seam day-one)"
required_stages = []

# ───────────────────────────── Instances ────────────────────────────────────
[[requirements]]
id = "REQ-INST-1"
title = "endpoint ID vs instance split (adapter-agnostic ID)"
required_stages = []
[[requirements]]
id = "REQ-INST-2"
title = "Per-node files, synced Psyche mind"
required_stages = []
[[requirements]]
id = "REQ-INST-3"
title = "Dormant (warm) / suspended (cold) resting states"
required_stages = []
[[requirements]]
id = "REQ-INST-4"
title = "active to dormant/suspended fires a transition echo commune"
required_stages = []
[[requirements]]
id = "REQ-INST-5"
title = "Two-tier context sync (live to all, project to same-project)"
required_stages = []
[[requirements]]
id = "REQ-INST-6"
title = "Deferred messages not delivered to dormant/suspended instances"
required_stages = []
[[requirements]]
id = "REQ-INST-7"
title = "Subnet registry + bare-id resolution policy"
required_stages = []
[[requirements]]
id = "REQ-INST-8"
title = "Remote-control mode distinct from local operation"
required_stages = []
[[requirements]]
id = "REQ-REACH-1"
title = "Off-node remote-drive detection + file transfer"
required_stages = []
[[requirements]]
id = "REQ-REACH-2"
title = "Remote command execution (deferred, consent-gated)"
required_stages = []

# ───────────────────────────── Networking / pairing ─────────────────────────
[[requirements]]
id = "REQ-NET-1"
title = "WAN messaging first-class, behind default-on net feature flag"
required_stages = []
[[requirements]]
id = "REQ-NET-2"
title = "n0 relay default + self-host knob + plain-language disclosure"
required_stages = []
[[requirements]]
id = "REQ-NET-3"
title = "Cross-node Psyche sync over P2P replaces gh-repo-sync"
required_stages = []
[[requirements]]
id = "REQ-PAIR-1"
title = "TOTP-seeded SPAKE2 pairing"
required_stages = []
[[requirements]]
id = "REQ-PAIR-2"
title = "Local trust store with TOFU + warn-on-change"
required_stages = []
[[requirements]]
id = "REQ-PAIR-3"
title = "Fetch current pairing code from any paired node"
required_stages = []
[[requirements]]
id = "REQ-PAIR-4"
title = "Subnet naming on first pairing"
required_stages = []

# ───────────────────────────── Self-update ──────────────────────────────────
[[requirements]]
id = "REQ-UPD-1"
title = "Peer-propagated update over P2P"
required_stages = []
[[requirements]]
id = "REQ-UPD-2"
title = "All binaries signature-verified before handoff"
required_stages = []
[[requirements]]
id = "REQ-UPD-3"
title = "No endpoint process terminates/suspends during self-update"
required_stages = []
[[requirements]]
id = "REQ-UPD-4"
title = "Update gated on user confirmation by default; opt-in full-auto"
required_stages = []
[[requirements]]
id = "REQ-UPD-5"
title = "spt-core ripple-updates registered adapters"
required_stages = []

# ───────────────────────────── Terminal wrapper / frontend ──────────────────
[[requirements]]
id = "REQ-TERM-1"
title = "Process-supervisor terminal wrapper hosting broker PTYs"
required_stages = []
[[requirements]]
id = "REQ-TERM-2"
title = "session-surface abstraction; send-keys + send-line injection"
required_stages = []
[[requirements]]
id = "REQ-TERM-3"
title = "Byte-stream remote terminal streaming for v1"
required_stages = []
[[requirements]]
id = "REQ-FRONT-1"
title = "Day-one launcher/manager frontend (list/launch/attach/init)"
required_stages = []

# ───────────────────────────── Install / migration / infra ──────────────────
[[requirements]]
id = "REQ-INSTALL-1"
title = "Two install paths; signed one-line script; OS-service registration"
required_stages = []
[[requirements]]
id = "REQ-INSTALL-2"
title = "Marketplace-repackaging-friendly install"
required_stages = []
[[requirements]]
id = "REQ-INSTALL-3"
title = "Idempotent + interactive-optional first run"
required_stages = []
[[requirements]]
id = "REQ-MIGRATE-1"
title = "Auto-detect and migrate a legacy claude_skill_owl install"
required_stages = []
[[requirements]]
id = "REQ-INFRA-1"
title = "GitHub issue tracking for v1; tangled.org as migration target"
required_stages = []

# ───────────────────────────── Documentation ────────────────────────────────
[[requirements]]
id = "REQ-DOCS-1"
title = "Dual-audience docs (human + AI dev-agent), markdown once / two depths"
required_stages = []
[[requirements]]
id = "REQ-DOCS-2"
title = "Sub-10-minute runnable killer quickstart per audience"
required_stages = []
[[requirements]]
id = "REQ-DOCS-3"
title = "Diátaxis structure; one canonical way to do X"
required_stages = []
[[requirements]]
id = "REQ-DOCS-4"
title = "Agent-consumable layer (llms.txt, manifest schema, MCP, CLI help)"
required_stages = []
[[requirements]]
id = "REQ-DOCS-5"
title = "Anti-drift: rustdoc/schema/exports/CLI-help generated + CI-checked"
required_stages = []

# ═════════════════════════════ KNOWN-HAZARDS invariants ══════════════════════
# Each maps to a docs/KNOWN-HAZARDS.md entry. On activation these require
# `unit` (and `int` where cross-process/cross-node) — the conformance checklist
# becomes a CI gate (PRD success criterion #6).

[[requirements]]
id = "REQ-HAZARD-GRACE-BEFORE-SIGNOFF"
title = "Grace-period wait completes before composing INIT_SIGNOFF (1.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-INFO-JSON-TORN-READ"
title = "State-file reads tolerate concurrent writes (1.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-STALE-INDEX-LOCK"
title = "Sweep stale lockfiles on daemon boot (1.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-DEFERRED-DRAIN"
title = "Deferred spool rows excluded from the event-stream drain (1.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-WORKER-PATH"
title = "Single source of truth for Worker/Psyche perch location (1.5)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-PARENT-PID-PREFER"
title = "Prefer stable parent PID / broker handle over ephemeral PID (2.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-STDIN-SESSION-ID"
title = "Stdin session_id precedence over env (2.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-HANDOFF-ARGV-COMPAT"
title = "Broker/brain IPC + handoff argv version-tolerant (2.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-GEN-START-NOW"
title = "gen_start = now() on cold-start and handoff (2.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-EPHEMERAL-CLEANUP"
title = "Ephemeral perch cleanup on every ring exit path (3.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-STALE-SIGNOFF-SENTINEL"
title = "Stale signoff sentinel does not kill a fresh start (3.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-ECHO-BEFORE-SIGNOFF"
title = "Echo-commune fires before INIT_SIGNOFF on orphan teardown (3.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-ENVELOPE-DECODE-ORDER"
title = "Envelope decode order, ampersand decoded last (4.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-ENVELOPE-PARSER-SAFE"
title = "Two-slice envelope parser is panic-free and tolerant (4.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-REGISTRY-STALE-CLEAN"
title = "Stale registry entries degrade to fallback, never hard-fail (4.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-DEFERRED-SURVIVE-DRAIN"
title = "Deferred rows survive poll drain (4.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-INBOX-NO-DOUBLE"
title = "No double-delivery via legacy inbox (4.5)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-WINDOWS-PID-RECYCLE"
title = "Windows PID-recycling false positives guarded (5.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-EBUSY-RENAME"
title = "tmp-write + atomic-rename + retry on Windows EBUSY (5.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-SUBPROCESS-TIMEOUT"
title = "Every harness/git subprocess has a timeout (5.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-UNC-PATH-STRIP"
title = "Strip Windows UNC prefix on serialized paths (5.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-SINGLE-PATH-SOURCE"
title = "Single path/registry source of truth; no layout ambiguity (6.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-SOFT-CLEANUP"
title = "Soft-cleanup preserves state, removes only the ready marker (6.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-CASCADE-WIPE-GUARD"
title = "No hard-delete of a parent hosting non-empty children (6.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-DROP-FILE-SINGLE-WRITER"
title = "Drop files are daemon-owned single-writer (6.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-DIRECT-WRITE-PRECEDENCE"
title = "Direct-write precedence marker (with node id) guards stale overwrite (6.5)"
required_stages = []


File created successfully at: C:\Users\decid\Documents\projects\spt-core\traceable-reqs.toml (file state is current in your context — no need to Read it back)

# traceable-reqs manifest for spt-core — SEED.
#
# Authoritative requirement registry: every PRD R-* requirement and every
# KNOWN-HAZARDS invariant lives here as a REQ-* id (see docs/TRACEABILITY.md
# for the development contract).
#
# ACTIVATION MODEL: every requirement starts inactive (`required_stages = []`)
# so `check` stays green pre-code. A milestone (M0-M5) ACTIVATES its requirements
# by setting their real `required_stages`. Validate this seed against the
# installed CLI at M0 (the binary isn't installed yet).

[scan]
roots = ["src", "tests", "docs"]

[policy]
# Default policy applied at activation: doc + impl + unit. Networking/lifecycle
# reqs add "int". Until a req is activated, its per-req `required_stages = []`
# keeps it out of the coverage gate.
required_stages = []

# ───────────────────────────── Architecture / workspace ─────────────────────
[[requirements]]
id = "REQ-ARCH-1"
title = "Many small acyclically-layered crates"
required_stages = []
[[requirements]]
id = "REQ-ARCH-2"
title = "Public SDK surface is spt-proto, spt-runtime, spt-msg"
required_stages = []
[[requirements]]
id = "REQ-ARCH-3"
title = "Wire-protocol version independent of crate semver, N-1 compat window"
required_stages = []
[[requirements]]
id = "REQ-ARCH-4"
title = "Copy-verbatim the commodity layer from the sister project"
required_stages = []

# ───────────────────────────── Daemon ───────────────────────────────────────
[[requirements]]
id = "REQ-DAEMON-1"
title = "One per-machine spt-daemon owning all per-machine state"
required_stages = []
[[requirements]]
id = "REQ-DAEMON-2"
title = "Broker/brain split for seamless self-update"
required_stages = []
[[requirements]]
id = "REQ-DAEMON-3"
title = "Any api invocation auto-starts the daemon if absent"
required_stages = []
[[requirements]]
id = "REQ-DAEMON-4"
title = "Honor every KNOWN-HAZARDS invariant"
required_stages = []

# ───────────────────────────── Harness contract — manifest seams ────────────
[[requirements]]
id = "REQ-MANIFEST-1"
title = "Per-adapter manifest with adapter_name and min_spt_core_version"
required_stages = []
[[requirements]]
id = "REQ-SEAM-SPAWN"
title = "spawn-session seam"
required_stages = []
[[requirements]]
id = "REQ-SEAM-POSTSPAWN"
title = "post-spawn / api bind seam with boot nonce"
required_stages = []
[[requirements]]
id = "REQ-SEAM-PSYCHE"
title = "spawn-psyche seam (fresh + resume templates)"
required_stages = []
[[requirements]]
id = "REQ-SEAM-HISTORY"
title = "History subsystem (fetcher / locate-normalize / native store)"
required_stages = []
[[requirements]]
id = "REQ-SEAM-ACTIVITY"
title = "Activity/idle reported via api sentinels, not PTY quiescence"
required_stages = []
[[requirements]]
id = "REQ-SEAM-INJECT"
title = "inject-input methods configurable per activity-state"
required_stages = []
[[requirements]]
id = "REQ-SEAM-RESUME"
title = "resume-session seam (fresh-with-preload / continue-existing)"
required_stages = []
[[requirements]]
id = "REQ-SEAM-CAPABILITY"
title = "Hostable endpoint-types capability declaration"
required_stages = []
[[requirements]]
id = "REQ-SEAM-UPDATE"
title = "Adapter-update avenue (file-pull / delegated command)"
required_stages = []

# ───────────────────────────── Harness contract — api surface ───────────────
[[requirements]]
id = "REQ-API-1"
title = "api prefix and adapter_name on every machinery invocation"
required_stages = []
[[requirements]]
id = "REQ-API-2"
title = "The api subcommand surface (bind/listen/poll/state/worker/boundary/...)"
required_stages = []
[[requirements]]
id = "REQ-API-3"
title = "commune/signoff are file-drops, not commands"
required_stages = []

# ───────────────────────────── Startup flows ────────────────────────────────
[[requirements]]
id = "REQ-START-1"
title = "Adapters never resolve SPT_HOME; binary on PATH; api bridging only"
required_stages = []
[[requirements]]
id = "REQ-START-2"
title = "Harness-hosted startup: api seed then listen"
required_stages = []
[[requirements]]
id = "REQ-START-3"
title = "spt-hosted startup: spawn-session then api bind (no file)"
required_stages = []
[[requirements]]
id = "REQ-START-4"
title = "Adapter-injected env aliases (SPT/OWL/LIVE)"
required_stages = []

# ───────────────────────────── Endpoints / Shells ───────────────────────────
[[requirements]]
id = "REQ-EP-1"
title = "Day-one endpoint types; open type system"
required_stages = []
[[requirements]]
id = "REQ-EP-2"
title = "Agent endpoints vs Shells distinction in the type model"
required_stages = []
[[requirements]]
id = "REQ-EP-3"
title = "Messaging payloads carry typed operation commands + file blobs"
required_stages = []
[[requirements]]
id = "REQ-EP-4"
title = "PresenceChannel broker endpoint (seam day-one)"
required_stages = []

# ───────────────────────────── Instances ────────────────────────────────────
[[requirements]]
id = "REQ-INST-1"
title = "endpoint ID vs instance split (adapter-agnostic ID)"
required_stages = []
[[requirements]]
id = "REQ-INST-2"
title = "Per-node files, synced Psyche mind"
required_stages = []
[[requirements]]
id = "REQ-INST-3"
title = "Dormant (warm) / suspended (cold) resting states"
required_stages = []
[[requirements]]
id = "REQ-INST-4"
title = "active to dormant/suspended fires a transition echo commune"
required_stages = []
[[requirements]]
id = "REQ-INST-5"
title = "Two-tier context sync (live to all, project to same-project)"
required_stages = []
[[requirements]]
id = "REQ-INST-6"
title = "Deferred messages not delivered to dormant/suspended instances"
required_stages = []
[[requirements]]
id = "REQ-INST-7"
title = "Subnet registry + bare-id resolution policy"
required_stages = []
[[requirements]]
id = "REQ-INST-8"
title = "Remote-control mode distinct from local operation"
required_stages = []
[[requirements]]
id = "REQ-REACH-1"
title = "Off-node remote-drive detection + file transfer"
required_stages = []
[[requirements]]
id = "REQ-REACH-2"
title = "Remote command execution (deferred, consent-gated)"
required_stages = []

# ───────────────────────────── Networking / pairing ─────────────────────────
[[requirements]]
id = "REQ-NET-1"
title = "WAN messaging first-class, behind default-on net feature flag"
required_stages = []
[[requirements]]
id = "REQ-NET-2"
title = "n0 relay default + self-host knob + plain-language disclosure"
required_stages = []
[[requirements]]
id = "REQ-NET-3"
title = "Cross-node Psyche sync over P2P replaces gh-repo-sync"
required_stages = []
[[requirements]]
id = "REQ-PAIR-1"
title = "TOTP-seeded SPAKE2 pairing"
required_stages = []
[[requirements]]
id = "REQ-PAIR-2"
title = "Local trust store with TOFU + warn-on-change"
required_stages = []
[[requirements]]
id = "REQ-PAIR-3"
title = "Fetch current pairing code from any paired node"
required_stages = []
[[requirements]]
id = "REQ-PAIR-4"
title = "Subnet naming on first pairing"
required_stages = []

# ───────────────────────────── Self-update ──────────────────────────────────
[[requirements]]
id = "REQ-UPD-1"
title = "Peer-propagated update over P2P"
required_stages = []
[[requirements]]
id = "REQ-UPD-2"
title = "All binaries signature-verified before handoff"
required_stages = []
[[requirements]]
id = "REQ-UPD-3"
title = "No endpoint process terminates/suspends during self-update"
required_stages = []
[[requirements]]
id = "REQ-UPD-4"
title = "Update gated on user confirmation by default; opt-in full-auto"
required_stages = []
[[requirements]]
id = "REQ-UPD-5"
title = "spt-core ripple-updates registered adapters"
required_stages = []

# ───────────────────────────── Terminal wrapper / frontend ──────────────────
[[requirements]]
id = "REQ-TERM-1"
title = "Process-supervisor terminal wrapper hosting broker PTYs"
required_stages = []
[[requirements]]
id = "REQ-TERM-2"
title = "session-surface abstraction; send-keys + send-line injection"
required_stages = []
[[requirements]]
id = "REQ-TERM-3"
title = "Byte-stream remote terminal streaming for v1"
required_stages = []
[[requirements]]
id = "REQ-FRONT-1"
title = "Day-one launcher/manager frontend (list/launch/attach/init)"
required_stages = []

# ───────────────────────────── Install / migration / infra ──────────────────
[[requirements]]
id = "REQ-INSTALL-1"
title = "Two install paths; signed one-line script; OS-service registration"
required_stages = []
[[requirements]]
id = "REQ-INSTALL-2"
title = "Marketplace-repackaging-friendly install"
required_stages = []
[[requirements]]
id = "REQ-INSTALL-3"
title = "Idempotent + interactive-optional first run"
required_stages = []
[[requirements]]
id = "REQ-MIGRATE-1"
title = "Auto-detect and migrate a legacy claude_skill_owl install"
required_stages = []
[[requirements]]
id = "REQ-INFRA-1"
title = "GitHub issue tracking for v1; tangled.org as migration target"
required_stages = []

# ───────────────────────────── Documentation ────────────────────────────────
[[requirements]]
id = "REQ-DOCS-1"
title = "Dual-audience docs (human + AI dev-agent), markdown once / two depths"
required_stages = []
[[requirements]]
id = "REQ-DOCS-2"
title = "Sub-10-minute runnable killer quickstart per audience"
required_stages = []
[[requirements]]
id = "REQ-DOCS-3"
title = "Diátaxis structure; one canonical way to do X"
required_stages = []
[[requirements]]
id = "REQ-DOCS-4"
title = "Agent-consumable layer (llms.txt, manifest schema, MCP, CLI help)"
required_stages = []
[[requirements]]
id = "REQ-DOCS-5"
title = "Anti-drift: rustdoc/schema/exports/CLI-help generated + CI-checked"
required_stages = []

# ═════════════════════════════ KNOWN-HAZARDS invariants ══════════════════════
# Each maps to a docs/KNOWN-HAZARDS.md entry. On activation these require
# `unit` (and `int` where cross-process/cross-node) — the conformance checklist
# becomes a CI gate (PRD success criterion #6).

[[requirements]]
id = "REQ-HAZARD-GRACE-BEFORE-SIGNOFF"
title = "Grace-period wait completes before composing INIT_SIGNOFF (1.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-INFO-JSON-TORN-READ"
title = "State-file reads tolerate concurrent writes (1.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-STALE-INDEX-LOCK"
title = "Sweep stale lockfiles on daemon boot (1.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-DEFERRED-DRAIN"
title = "Deferred spool rows excluded from the event-stream drain (1.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-WORKER-PATH"
title = "Single source of truth for Worker/Psyche perch location (1.5)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-PARENT-PID-PREFER"
title = "Prefer stable parent PID / broker handle over ephemeral PID (2.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-STDIN-SESSION-ID"
title = "Stdin session_id precedence over env (2.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-HANDOFF-ARGV-COMPAT"
title = "Broker/brain IPC + handoff argv version-tolerant (2.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-GEN-START-NOW"
title = "gen_start = now() on cold-start and handoff (2.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-EPHEMERAL-CLEANUP"
title = "Ephemeral perch cleanup on every ring exit path (3.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-STALE-SIGNOFF-SENTINEL"
title = "Stale signoff sentinel does not kill a fresh start (3.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-ECHO-BEFORE-SIGNOFF"
title = "Echo-commune fires before INIT_SIGNOFF on orphan teardown (3.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-ENVELOPE-DECODE-ORDER"
title = "Envelope decode order, ampersand decoded last (4.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-ENVELOPE-PARSER-SAFE"
title = "Two-slice envelope parser is panic-free and tolerant (4.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-REGISTRY-STALE-CLEAN"
title = "Stale registry entries degrade to fallback, never hard-fail (4.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-DEFERRED-SURVIVE-DRAIN"
title = "Deferred rows survive poll drain (4.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-INBOX-NO-DOUBLE"
title = "No double-delivery via legacy inbox (4.5)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-WINDOWS-PID-RECYCLE"
title = "Windows PID-recycling false positives guarded (5.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-EBUSY-RENAME"
title = "tmp-write + atomic-rename + retry on Windows EBUSY (5.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-SUBPROCESS-TIMEOUT"
title = "Every harness/git subprocess has a timeout (5.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-UNC-PATH-STRIP"
title = "Strip Windows UNC prefix on serialized paths (5.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-SINGLE-PATH-SOURCE"
title = "Single path/registry source of truth; no layout ambiguity (6.1)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-SOFT-CLEANUP"
title = "Soft-cleanup preserves state, removes only the ready marker (6.2)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-CASCADE-WIPE-GUARD"
title = "No hard-delete of a parent hosting non-empty children (6.3)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-DROP-FILE-SINGLE-WRITER"
title = "Drop files are daemon-owned single-writer (6.4)"
required_stages = []
[[requirements]]
id = "REQ-HAZARD-DIRECT-WRITE-PRECEDENCE"
title = "Direct-write precedence marker (with node id) guards stale overwrite (6.5)"
required_stages = []


Now the contract doc.


# Traceability development contract

> How spt-core uses [`traceable-reqs`](https://github.com/BigscreenVR/traceable-reqs) to keep every requirement traced from doc → impl → test. The manifest is `traceable-reqs.toml` (seeded from PRD `R-*` + KNOWN-HAZARDS invariants). This contract makes the trace pay off instead of rotting.

## Why

The whole point of the rebuild is to *not* re-introduce the sister project's bugs and to ship the PRD's scope verifiably. A requirement that isn't traced to real evidence (a doc, an implementation, a test) is a requirement you're *hoping* is met. This contract converts that hope into a build that fails when evidence is missing.

## The contract (rules)

1. **The manifest is the authoritative requirement registry.** Every PRD `R-*` requirement and every KNOWN-HAZARDS invariant exists in `traceable-reqs.toml` as a `REQ-*` id. No work without a REQ; no REQ without intent to satisfy. The PRD holds the prose; the manifest holds the id + `required_stages`.
2. **Tag in the same change as the evidence.** When you write the function / test / doc-section that satisfies a stage, add its `[stage->REQ-ID]` tag in *that same commit*. Never "tag later" — this single rule is what stops the trace from drifting.
3. **Evidence-proximate tags, not file-tops.** A tag sits on or immediately above the real function, test, doc section, config entry, or workflow step that proves the stage. One tag = one piece of real evidence. Tags at file tops to satisfy coverage are noise and usually wrong.
4. **KNOWN-HAZARDS are first-class requirements.** Each invariant is a `REQ-HAZARD-*` requiring `unit` (and `int` where cross-process/cross-node). A hazard cannot be "covered" without a test tagging it — the anti-regression promise becomes mechanical (PRD success criterion #6).
5. **Activation, not premature failure.** Every requirement starts `required_stages = []` (inactive) so `check` stays green pre-code. A **milestone (M0–M5) activates** the requirements it delivers by setting their real `required_stages`. Deferred items (`docs/DEFERRED.md`) stay `[]` until promoted.
6. **Scan roots stay honest.** `[scan].roots` includes every evidence location (`src`, `tests`, `docs`, and later `.github/workflows`, `scripts`). Audit roots whenever a new evidence dir appears — a missing root makes evidence *silently* vanish from the trace.

### Stages

`doc` (prose/design/rustdoc) · `impl` (production code) · `unit` (unit test) · `int` (integration / e2e / cross-node). Default activation policy: `["doc","impl","unit"]`; networking/lifecycle/cross-node reqs add `int`.

### Tag examples

```rust
// [impl->REQ-PAIR-1]
fn spake2_pair(...) { ... }
```
```rust
// [unit->REQ-HAZARD-ENVELOPE-DECODE-ORDER]
#[test] fn decodes_amp_last() { ... }
```
```markdown
<!-- [doc->REQ-NET-2] -->
## Relay dependency
```

## Enforcement (four layers — defense in depth)

1. **CI gate (hard backstop).** `traceable-reqs check --json` runs on every PR/push; exit-1 (`missing_stage` / `undeclared_id` / `parse_error` / `manifest_error`) **fails the build**. A PR can't merge if it leaves an *activated* req's required stage uncovered. Runs alongside the DOCS-STRATEGY CI gates.
2. **Milestone activation gate.** Starting a milestone flips its reqs from `[]` to the real policy; the milestone **is not done until `check` is green for its reqs**. Coverage grows *with* the project instead of failing on day one.
3. **Agent-facing rule.** The repo `CLAUDE.md` instructs every dev-agent: tag `[stage->REQ-ID]` in the same change as the evidence, and run `traceable-reqs check` before declaring done. Since spt-core is built *with* agents, the contract must be machine-followable — agent discipline + CI as the net.
4. **Quality audit (anti-box-ticking).** `check` proves a tag *exists*; `traceable-reqs review` + `lint` audit whether tags sit near *real* evidence and whether titles are meaningful. Run advisory in CI (or periodically). Presence = hard gate; quality = audited.

Optional fast-feedback: a pre-push git hook running `traceable-reqs check` locally.

## CI snippet (wire at M0, once there is a Rust project + CI)

```yaml
# .github/workflows/traceability.yml
name: traceability
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install traceable-reqs
        run: gh release download --repo BigscreenVR/traceable-reqs --pattern '*linux-x86_64' --output traceable-reqs && chmod +x traceable-reqs
        env: { GH_TOKEN: ${{ github.token }} }
      - name: Coverage gate (hard)
        run: ./traceable-reqs check --json
      - name: Quality audit (advisory)
        run: ./traceable-reqs lint || true
```

## Lifecycle

- **Now (planning):** manifest seeded, all reqs inactive. `check` is green (nothing required yet).
- **M0:** install the CLI, validate the seed against it, wire the CI workflow, **activate M0 reqs** (`REQ-ARCH-*`, `REQ-HAZARD-*` for the commodity layer), tag as code lands.
- **M1–M5:** each milestone activates + covers its requirements before it's called done.


File created successfully at: C:\Users\decid\Documents\projects\spt-core\docs\TRACEABILITY.md (file state is current in your context — no need to Read it back)

# Traceability development contract

> How spt-core uses [`traceable-reqs`](https://github.com/BigscreenVR/traceable-reqs) to keep every requirement traced from doc → impl → test. The manifest is `traceable-reqs.toml` (seeded from PRD `R-*` + KNOWN-HAZARDS invariants). This contract makes the trace pay off instead of rotting.

## Why

The whole point of the rebuild is to *not* re-introduce the sister project's bugs and to ship the PRD's scope verifiably. A requirement that isn't traced to real evidence (a doc, an implementation, a test) is a requirement you're *hoping* is met. This contract converts that hope into a build that fails when evidence is missing.

## The contract (rules)

1. **The manifest is the authoritative requirement registry.** Every PRD `R-*` requirement and every KNOWN-HAZARDS invariant exists in `traceable-reqs.toml` as a `REQ-*` id. No work without a REQ; no REQ without intent to satisfy. The PRD holds the prose; the manifest holds the id + `required_stages`.
2. **Tag in the same change as the evidence.** When you write the function / test / doc-section that satisfies a stage, add its `[stage->REQ-ID]` tag in *that same commit*. Never "tag later" — this single rule is what stops the trace from drifting.
3. **Evidence-proximate tags, not file-tops.** A tag sits on or immediately above the real function, test, doc section, config entry, or workflow step that proves the stage. One tag = one piece of real evidence. Tags at file tops to satisfy coverage are noise and usually wrong.
4. **KNOWN-HAZARDS are first-class requirements.** Each invariant is a `REQ-HAZARD-*` requiring `unit` (and `int` where cross-process/cross-node). A hazard cannot be "covered" without a test tagging it — the anti-regression promise becomes mechanical (PRD success criterion #6).
5. **Activation, not premature failure.** Every requirement starts `required_stages = []` (inactive) so `check` stays green pre-code. A **milestone (M0–M5) activates** the requirements it delivers by setting their real `required_stages`. Deferred items (`docs/DEFERRED.md`) stay `[]` until promoted.
6. **Scan roots stay honest.** `[scan].roots` includes every evidence location (`src`, `tests`, `docs`, and later `.github/workflows`, `scripts`). Audit roots whenever a new evidence dir appears — a missing root makes evidence *silently* vanish from the trace.

### Stages

`doc` (prose/design/rustdoc) · `impl` (production code) · `unit` (unit test) · `int` (integration / e2e / cross-node). Default activation policy: `["doc","impl","unit"]`; networking/lifecycle/cross-node reqs add `int`.

### Tag examples

```rust
// [impl->REQ-PAIR-1]
fn spake2_pair(...) { ... }
```
```rust
// [unit->REQ-HAZARD-ENVELOPE-DECODE-ORDER]
#[test] fn decodes_amp_last() { ... }
```
```markdown
<!-- [doc->REQ-NET-2] -->
## Relay dependency
```

## Enforcement (four layers — defense in depth)

1. **CI gate (hard backstop).** `traceable-reqs check --json` runs on every PR/push; exit-1 (`missing_stage` / `undeclared_id` / `parse_error` / `manifest_error`) **fails the build**. A PR can't merge if it leaves an *activated* req's required stage uncovered. Runs alongside the DOCS-STRATEGY CI gates.
2. **Milestone activation gate.** Starting a milestone flips its reqs from `[]` to the real policy; the milestone **is not done until `check` is green for its reqs**. Coverage grows *with* the project instead of failing on day one.
3. **Agent-facing rule.** The repo `CLAUDE.md` instructs every dev-agent: tag `[stage->REQ-ID]` in the same change as the evidence, and run `traceable-reqs check` before declaring done. Since spt-core is built *with* agents, the contract must be machine-followable — agent discipline + CI as the net.
4. **Quality audit (anti-box-ticking).** `check` proves a tag *exists*; `traceable-reqs review` + `lint` audit whether tags sit near *real* evidence and whether titles are meaningful. Run advisory in CI (or periodically). Presence = hard gate; quality = audited.

Optional fast-feedback: a pre-push git hook running `traceable-reqs check` locally.

## CI snippet (wire at M0, once there is a Rust project + CI)

```yaml
# .github/workflows/traceability.yml
name: traceability
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install traceable-reqs
        run: gh release download --repo BigscreenVR/traceable-reqs --pattern '*linux-x86_64' --output traceable-reqs && chmod +x traceable-reqs
        env: { GH_TOKEN: ${{ github.token }} }
      - name: Coverage gate (hard)
        run: ./traceable-reqs check --json
      - name: Quality audit (advisory)
        run: ./traceable-reqs lint || true
```

## Lifecycle

- **Now (planning):** manifest seeded, all reqs inactive. `check` is green (nothing required yet).
- **M0:** install the CLI, validate the seed against it, wire the CI workflow, **activate M0 reqs** (`REQ-ARCH-*`, `REQ-HAZARD-*` for the commodity layer), tag as code lands.
- **M1–M5:** each milestone activates + covers its requirements before it's called done.


CONTEXT WARNING: Usage at 65%. Remaining: 35%. Be aware that context is getting limited. Avoid unnecessary exploration or starting new complex work.


Context noted — finishing the last two items (repo CLAUDE.md + commit), keeping it tight.


# spt-core — agent working rules

Harness-independent core for an agent ecosystem (messaging, live-agent lifecycle, terminal hosting, P2P networking, runtime-manifest harness contract). Rust crates + a single `spt` binary. Clean-room rebuild of `claude_skill_owl`.

**Orientation — read before working:** `PRD.md` (requirements), `ROADMAP.md` (build path), `CONTEXT.md` (glossary/model, authoritative for meaning), `docs/adr/` (decisions), `docs/KNOWN-HAZARDS.md` (invariants we must not re-break), `docs/{STORAGE,MANIFEST,CONTEXT-MEMORY,DOCS-STRATEGY,TRACEABILITY}.md`.

## Requirement traceability (binding)

This project uses `traceable-reqs` (`traceable-reqs.toml` = the authoritative `REQ-*` registry). The full contract is `docs/TRACEABILITY.md`. The rules you must follow:

1. **Tag evidence in the same change.** When you write a function/test/doc-section that satisfies a requirement stage, add its tag in that same commit:
   `// [impl->REQ-FOO]` · `// [unit->REQ-FOO]` · `<!-- [doc->REQ-FOO] -->`
   Stages: `doc` / `impl` / `unit` / `int`. Tag *on or immediately above* the real evidence — never at file tops to satisfy coverage.
2. **Run `traceable-reqs check` before declaring work done.** Exit-1 means missing/invalid evidence — fix it, don't ship it.
3. **New requirement → add it to `traceable-reqs.toml` first** (with a `REQ-*` id), then satisfy it. No untracked work; no untagged evidence.
4. **KNOWN-HAZARDS are `REQ-HAZARD-*` requirements** — each needs a test before it's "covered." Treat the hazard list as a conformance checklist you must satisfy, not advice.
5. **Activate, don't pre-fail.** Requirements you aren't yet working stay `required_stages = []`. Activate (set real stages) only when starting the milestone that delivers them.

## Other conventions

- Match surrounding code style; copy-verbatim the sister project's stable wire/schema formats (ADR-0001), clean-room everything else.
- Honor every `docs/KNOWN-HAZARDS.md` invariant — these are real bugs already paid for once.
- Docs are dual-audience (human + AI dev-agent) per `docs/DOCS-STRATEGY.md`; doc generation is CI-gated against drift.
- Commit messages end with the project's Co-Authored-By trailer.


File created successfully at: C:\Users\decid\Documents\projects\spt-core\CLAUDE.md (file state is current in your context — no need to Read it back)

# spt-core — agent working rules

Harness-independent core for an agent ecosystem (messaging, live-agent lifecycle, terminal hosting, P2P networking, runtime-manifest harness contract). Rust crates + a single `spt` binary. Clean-room rebuild of `claude_skill_owl`.

**Orientation — read before working:** `PRD.md` (requirements), `ROADMAP.md` (build path), `CONTEXT.md` (glossary/model, authoritative for meaning), `docs/adr/` (decisions), `docs/KNOWN-HAZARDS.md` (invariants we must not re-break), `docs/{STORAGE,MANIFEST,CONTEXT-MEMORY,DOCS-STRATEGY,TRACEABILITY}.md`.

## Requirement traceability (binding)

This project uses `traceable-reqs` (`traceable-reqs.toml` = the authoritative `REQ-*` registry). The full contract is `docs/TRACEABILITY.md`. The rules you must follow:

1. **Tag evidence in the same change.** When you write a function/test/doc-section that satisfies a requirement stage, add its tag in that same commit:
   `// [impl->REQ-FOO]` · `// [unit->REQ-FOO]` · `<!-- [doc->REQ-FOO] -->`
   Stages: `doc` / `impl` / `unit` / `int`. Tag *on or immediately above* the real evidence — never at file tops to satisfy coverage.
2. **Run `traceable-reqs check` before declaring work done.** Exit-1 means missing/invalid evidence — fix it, don't ship it.
3. **New requirement → add it to `traceable-reqs.toml` first** (with a `REQ-*` id), then satisfy it. No untracked work; no untagged evidence.
4. **KNOWN-HAZARDS are `REQ-HAZARD-*` requirements** — each needs a test before it's "covered." Treat the hazard list as a conformance checklist you must satisfy, not advice.
5. **Activate, don't pre-fail.** Requirements you aren't yet working stay `required_stages = []`. Activate (set real stages) only when starting the milestone that delivers them.

## Other conventions

- Match surrounding code style; copy-verbatim the sister project's stable wire/schema formats (ADR-0001), clean-room everything else.
- Honor every `docs/KNOWN-HAZARDS.md` invariant — these are real bugs already paid for once.
- Docs are dual-audience (human + AI dev-agent) per `docs/DOCS-STRATEGY.md`; doc generation is CI-gated against drift.
- Commit messages end with the project's Co-Authored-By trailer.


Now record the decision in ROADMAP and commit all four.


Edit

## Tooling: requirement traceability (adopted)

`traceable-reqs` is adopted as the requirement-tracing gate. `traceable-reqs.toml` seeds the `REQ-*` registry from PRD `R-*` + KNOWN-HAZARDS invariants (all inactive until milestone activation). The development contract + enforcement (CI gate, milestone activation, agent rule, quality audit) is `docs/TRACEABILITY.md`; the agent rule lives in `CLAUDE.md`. **M0 task:** install the CLI, validate the seed, wire the CI workflow, activate M0 reqs.

## Open threads carried forward


The file C:\Users\decid\Documents\projects\spt-core\ROADMAP.md has been updated successfully. (file state is current in your context — no need to Read it back)

## Tooling: requirement traceability (adopted)

`traceable-reqs` is adopted as the requirement-tracing gate. `traceable-reqs.toml` seeds the `REQ-*` registry from PRD `R-*` + KNOWN-HAZARDS invariants (all inactive until milestone activation). The development contract + enforcement (CI gate, milestone activation, agent rule, quality audit) is `docs/TRACEABILITY.md`; the agent rule lives in `CLAUDE.md`. **M0 task:** install the CLI, validate the seed, wire the CI workflow, activate M0 reqs.

## Open threads carried forward

# spt-core Roadmap

> Lightweight-but-structured path from design → fruition. Not a GSD/phase-gated process — a clear sequence with de-risk gates. Planning corpus is complete (PRD + CONTEXT + 5 ADRs + 6 design docs); this is how we build it.

## End goal

A harness-independent core for an agent ecosystem — messaging, live-agent lifecycle, terminal hosting, **first-class P2P networking**, and a runtime-manifest harness contract — shipped as Rust crates + a single `spt` binary. The proof: the same agent runs natively across all of a user's machines with a synced mind, reachable and operable from anywhere, with seamless self-update and zero-config cross-machine messaging. First thing built atop it: a rebuilt `spt` plugin at parity with today's modern SPT.

## Scope decisions (locked)

- **v1 = the full PRD, networking included.** The networked element is the *reason* spt-core exists; it is not deferrable to v1.1.
- **The hard freeze on `claude_skill_owl` is not a clock.** It works today and delivers value as-is while spt-core is built — no schedule pressure from it.
- **Process: lightweight but structured.** GSD is too heavy. This roadmap + the design docs are the structure.

## Path to fruition (sequence)

**Stage A — Red-team review (before building).** Pressure-test the design adversarially. Focus on the riskiest architectural decisions, not bikeshedding. Tools: `plan-eng-review` (architecture) + `codex` (adversarial second opinion). Scope-cutting is *not* a goal (v1 is locked as full PRD), but surfacing contradictions / over-engineering / unproven assumptions is.

**Stage B — De-risk spikes.** Throwaway proofs of the load-bearing unknowns — anything that, if it fails, forces a redesign. Do these before committing to the full build. See *De-risk spikes* below.

**Stage C — Walking skeleton.** Build the killer-quickstart slice end-to-end through the real crate boundaries: **two agents exchange a message** (first local; ultimately cross-node — the real proof). Validates the whole stack early; then thicken.

**Stage D — Phased build (M0–M5).** Dependency-ordered, each milestone ships something usable.

## Milestones (all v1)

- **M0 — Workspace + commodity layer.** Cargo workspace; `spt-proto` (wire envelope grammar, endpoint types, framing, Ed25519 identity, typed+binary payloads) + `spt-store` (spool, perch layout, trust store, registry persistence). Copy-verbatim the stable formats from the sister project (ADR-0001).
- **M1 — Local messaging + binary.** `spt-msg` (delivery TCP+spool, routing, send/ring/ready) + the `spt` binary + CLI. **= the killer quickstart (local): two agents exchange a message.**
- **M2 — Harness contract + lifecycle.** `spt-runtime` (AgentRuntime, ManifestRuntime, manifest schema) + `spt-live` (Psyche/pulse/commune/signoff) + the `api` subcommand surface + both startup topologies. **Rebuild the `spt` plugin to parity** (the stated first sub-project).
- **M3 — Terminal wrapper + daemon + self-update.** `spt-term` (session-surface, PTY, broker) + the consolidated `spt-daemon` (broker/brain split) + peer-propagated signed self-update.
- **M4 — Networking + instances.** `spt-net` (Iroh WAN, mDNS LAN, TOTP-SPAKE2 pairing, subnet registry) + the multi-instance model + cross-node Psyche sync (P2P, opt-in GitHub hub). **= the real proof: cross-node message + drive an agent on machine A from machine B.**
- **M5 — Shells, presence, deferred capabilities.** Shell adapters + sleep/wake, PresenceChannel, and the consent-gated capabilities (remote-exec, instantiate-anywhere) landing into the v1 consent seam.

## De-risk spikes (do early — these can invalidate the architecture)

1. **Broker/brain no-terminate handoff** — prove a PTY child + open socket survive a daemon-*logic* restart (FD-passing or stable-broker shim). The hardest invariant in the design (ADR-0004).
2. **Iroh + mDNS smoke test** — two nodes, separate NATs, one message end-to-end; measure direct-vs-relay + binary size (research brief §5). Validates the whole networking premise.
3. **ConPTY + `portable-pty`** — host and drive a real session in a broker PTY on Windows + Linux.
4. **Manifest-driven lifecycle** — a manifest drives one real Claude Code session through spawn → bind → commune → signoff, proving harness-independence works in practice.

## Immediate next steps (next session)

1. **Stage A review** — run `plan-eng-review` on the architecture + a `codex` adversarial pass; capture findings.
2. **Spike #1 (broker/brain handoff)** and **#2 (Iroh smoke test)** — the two that most threaten the design. Throwaway repos/branches.
3. Fold review findings + spike results back into the ADRs/CONTEXT (amend if anything breaks).
4. Then start **M0** (workspace + `spt-proto` + `spt-store`).

## Open threads carried forward

- New deferred items logged this session (`docs/DEFERRED.md`): block-level OCC context merge; the rebalance / Memory-Health pass; the consent framework's gated capabilities.
- The dual-audience docs strategy (`docs/DOCS-STRATEGY.md`) governs the *shipped* docs, authored as code lands.

+## Tooling: requirement traceability (adopted)

+`traceable-reqs` is adopted as the requirement-tracing gate. `traceable-reqs.toml` seeds the `REQ-*` registry from PRD `R-*` + KNOWN-HAZARDS invariants (all inactive until milestone activation). The development contract + enforcement (CI gate, milestone activation, agent rule, quality audit) is `docs/TRACEABILITY.md`; the agent rule lives in `CLAUDE.md`. **M0 task:** install the CLI, validate the seed, wire the CI workflow, activate M0 reqs.


Bash

cd "C:/Users/decid/Documents/projects/spt-core" && git add -A && git status --short && git commit -q -F - <<'EOF'
build: adopt traceable-reqs with a traceability contract

- traceable-reqs.toml: seed REQ-* registry from PRD R-* requirements + the 25
  KNOWN-HAZARDS invariants (REQ-HAZARD-*), all required_stages = [] (inactive)
  until milestone activation
- docs/TRACEABILITY.md: development contract (manifest-authoritative, tag-in-
  same-change, evidence-proximate, hazards-as-reqs, activation model) +
  enforcement (CI check gate, milestone activation, agent rule, quality audit)
  + CI workflow snippet
- CLAUDE.md: binding agent working rules incl. tag-in-same-change + run check
  before done
- ROADMAP.md: record adoption + M0 task to install/validate/wire/activate

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
EOF
git push -q origin main && echo pushed && git log --oneline -1 && git rev-list --left-right --count origin/main...HEAD

Commit and push traceability adoption


warning: in the working copy of 'ROADMAP.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'CLAUDE.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'docs/TRACEABILITY.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'traceable-reqs.toml', LF will be replaced by CRLF the next time Git touches it
A  CLAUDE.md
M  ROADMAP.md
A  docs/TRACEABILITY.md
A  traceable-reqs.toml
pushed
a7128b6 build: adopt traceable-reqs with a traceability contract
0	0


All four done, committed (`a7128b6`), pushed — `origin/main` synced.

**traceable-reqs adopted, with the full contract instated:**
- **`traceable-reqs.toml`** — seeded with **92 `REQ-*` requirements** (67 from PRD `R-*` + 25 `REQ-HAZARD-*` from the KNOWN-HAZARDS invariants), all `required_stages = []` (inactive) so `check` stays green until milestones activate them.
- **`docs/TRACEABILITY.md`** — the contract: manifest-authoritative, tag-in-same-change, evidence-proximate, hazards-as-first-class-reqs, activation model + the four enforcement layers (CI `check` gate, milestone activation, agent rule, quality audit) + a ready CI workflow snippet.
- **`CLAUDE.md`** — binding agent working rules (tag-in-same-change, run `check` before done, hazards-as-conformance-checklist) so the dev-agents that build this follow the contract by default.
- **`ROADMAP.md`** — adoption recorded + the M0 task (install CLI, validate seed, wire CI, activate M0 reqs).

The highest-value payoff is wired: each of the 25 sister-project hazards is now a `REQ-HAZARD-*` that, once activated at its milestone, **fails the build if it lacks a test** — turning "don't re-introduce those bugs" into a mechanical gate (PRD success criterion #6).

**Repo: `SaberMage/spt-core`, 11 commits, clean.** Good stopping point — and the earlier commune already carries the broader next-session state. (Heads-up: context is ~65%, so this is a natural place to pause before anything new.)