@stravica-ai/rcf-schemas 0.2.0

package/docs/fbs.md

@@ -0,0 +1,75 @@
+# fbs.schema.json
+
+Functional Build Specification. One per build session. **Outside the traceability chain**: FBS owns `acIds[]` for build-time work assignment but is not load-bearing for "did REQ-001 get tested?" queries. See `id-conventions.md` for the chain detail.
+
+Structurally, each FBS carries the mandatory `bsId` back-reference plus `buildOrder` and `executionStatus`. The walker computes the ordered per-BS FBS list by loading every FBS under `rcf/fbs/`, filtering by `bsId`, and sorting by `buildOrder`.
+
+## Canonical `$id`
+
+`https://schemas.stravica.io/rcf/v0.2.0/fbs.schema.json`
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `fbsId` | `^FBS-\d{3,}$` | This FBS's identifier. |
+| `prdId` | `^PRD-\d{3,}$` | Root PRD. |
+| `bsId` | `^BS-\d{3,}$` | Parent Build Sequence. |
+| `buildOrder` | integer >= 1 | Position in the ordered sequence for this BS. Duplicates within one BS are a walker-time validation error. |
+| `executionStatus` | `executionStatus` enum | `notStarted`, `inProgress`, `complete`, `verified`. |
+| `title` | string, min 1 | One-line title. |
+| `summary` | string, min 1 | One-paragraph "what is this build doing". |
+| `acIds` | array of `acId`, min 1 | The ACs this build session delivers. Flat top-level array. |
+| `dependsOnFbsIds` | array of `fbsId`, min 0 | Other FBS items this one depends on. The build tool builds a DAG from these. Empty array is allowed. |
+| `createdAt` / `updatedAt` | ISO 8601 date-time | Lifecycle timestamps. |
+
+## Optional fields
+
+| Field | Type | Purpose |
+|---|---|---|
+| `approach` | string | "How to think about this build" narrative, distinct from `summary` (what) and `notes` (gotchas). |
+| `contextRequirements` | object | What the SDD adapter needs to walk for the BUILD prompt. See below. |
+| `estimatedSize` | enum: `small`, `medium`, `large` | Rough sizing. |
+| `estimatedHours` | number, 0.5..16 | Tighter estimate. |
+| `deliverables` | array of strings | Concrete artefacts expected from the build session. |
+| `riskLevel` | enum: `low`, `medium`, `high` | Risk classification. |
+| `domain` | string | Free-form domain label. |
+| `notes` | string | FBS-specific gotchas. |
+
+## `contextRequirements` shape
+
+Tells the SDD adapter (Phase 6 of `rcf-build-lite`) what to walk when assembling the BUILD prompt:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `prdSections` | array of strings | PRD section names to inline. |
+| `tadSections` | array of strings | TAD section names to inline. |
+| `tacIds` | array of `tacId` | Specific TACs to inline. |
+| `adrIds` | array of `adrId` | Specific ADRs to inline. |
+| `existingModules` | array of strings | Source files the build should be aware of. |
+| `schemas` | array of strings | Schema files relevant to this build. |
+| `externalDocs` | array of strings | Third-party docs (URLs or paths). |
+| `other` | array of strings | Anything else. |
+
+## Renamed fields in 0.2.0
+
+- `status` -> `executionStatus`. Same enum, more explicit name (disambiguates from authoring status used elsewhere).
+- `dependencies` -> `dependsOnFbsIds`. Same shape, mandatory with `minItems: 0`.
+
+## Why flat `acIds[]`
+
+Round-3 had `storyScope: [{ acIds: [...] }]`. The wrapping object served no purpose: the parent US is derivable from each AC id (each AC lives inside its US doc's `acceptanceCriteria[]`). Strict-by-default discipline: if it's derivable, don't store it.
+
+## Why FBS is outside the traceability chain
+
+The RCF traceability chain is `PRD -> REQ -> US -> AC -> TS -> TC`. FBS is a build-time work artefact, useful for "what's being built this session" but not for "did REQ-001 get tested?" Phase 5 traceability tooling in `rcf-build-lite` walks the chain without going through FBS.
+
+## What's NOT here
+
+- **`testableOutcomes`** dropped. Derivable from referenced ACs (each AC's `then` clause IS the testable outcome). SSoT: AC is the source.
+- **`constraints`** dropped. Architectural constraints live in TAC / ADR (referenced via `contextRequirements`). FBS-specific gotchas go in `notes`.
+- **Markdown narrative.** The schema is pure JSON. The BUILD-phase markdown prompt is assembled at build time by the SDD adapter from JSON FBS + walked references.
+
+## SDD adapter (informative, not in this repo)
+
+`rcf build FBS-XXX` reads the FBS JSON, walks `acIds[]` to parent US ACs, walks `contextRequirements.tacIds[]` and `adrIds[]` to TAC/ADR files, and assembles a single markdown prompt for the coding LLM. The adapter lives in `rcf-build-lite` (Phase 6 of that project). The schemas repo's job is to make sure the FBS schema carries every field the adapter needs.

package/docs/file-layout.md

@@ -0,0 +1,62 @@
+# File layout (recommended)
+
+The schemas validate documents by content, not by where they sit on disk. This page documents the **recommended canonical layout**. Adopters may deviate; nothing here is schema-enforced.
+
+## Recommendation
+
+Put all RCF docs under a `rcf/` top-level folder at project root. Test Suites live under `rcf/test-suites/`.
+
+```
+project-root/
+|-- rcf/
+|   |-- rcf-manifest.json
+|   |-- prd.json
+|   |-- requirements/
+|   |   |-- REQ-001.json
+|   |   `-- REQ-002.json
+|   |-- user-stories/
+|   |   |-- US-101.json
+|   |   `-- US-102.json
+|   |-- tad.json
+|   |-- tacs/
+|   |   |-- TAC-001.json
+|   |   `-- TAC-002.json
+|   |-- adrs/
+|   |   |-- ADR-001.json
+|   |   `-- ADR-002.json
+|   |-- build-sequence.json
+|   |-- fbs/
+|   |   |-- FBS-001.json
+|   |   `-- FBS-002.json
+|   `-- test-suites/
+|       |-- ts-001.json
+|       `-- ts-002.json
+```
+
+## Why everything lives under `rcf/`
+
+A single top-level folder keeps structured RCF artefacts cleanly separable from source code. Tools that walk the RCF tree (linters, query tools, the `rcf view` viewer) have a single boundary to read from.
+
+The Test Suite JSON is the *spec* of what the tests do; the *executable* test file (Jest, pytest, JUnit, ...) lives with the implementation and is linked from a TC's optional `testPointer` field (`filePath::testName`). This keeps the spec walkable by tooling without prescribing where executable tests live.
+
+## Conventions, not constraints
+
+The schema does not enforce file naming or directory layout. Adopters can:
+
+- Pick different filenames (`prd-2026.json` instead of `prd.json`).
+- Co-locate FBS files with the source they build (legal; the recommendation just keeps them under `rcf/fbs/` for discoverability).
+
+Tooling MAY enforce a layout per project, but the schemas repo deliberately does not.
+
+## Convention-derived paths from id
+
+Tools that walk from the manifest roots can resolve child paths by convention:
+
+- REQ-001 -> `rcf/requirements/REQ-001.json`
+- US-101 -> `rcf/user-stories/US-101.json`
+- TAC-001 -> `rcf/tacs/TAC-001.json`
+- ADR-001 -> `rcf/adrs/ADR-001.json`
+- FBS-001 -> `rcf/fbs/FBS-001.json`
+- TS-001 -> `rcf/test-suites/ts-001.json`
+
+A future minor bump may introduce an optional `paths` override block on the manifest for adopters who deviate from the recommendation; 0.2.0 ships convention-only.

package/docs/id-conventions.md

@@ -0,0 +1,60 @@
+# ID conventions
+
+The pattern, the prefix table, the AC sub-id form, and the file/nested asymmetry.
+
+## The pattern
+
+```
+^<PREFIX>-\d{3,}$
+```
+
+Three-digit minimum, unbounded above. `PRD-001` through `PRD-999` use the clean visual; `PRD-1000+` works without a schema migration. A single digit (`PRD-1`) is rejected.
+
+Two families deviate from the family default and are documented alongside their prefix below: `TS-\d{3}` (exactly three digits) and `TC-\d{3}-<slug>` (three-digit TS suffix plus a lowercase alphanumeric slug).
+
+## Prefix table
+
+| Prefix | Document | File? | Where defined |
+|---|---|---|---|
+| `PRD` | Product Requirements Document | yes | `prd.schema.json` |
+| `REQ` | Requirement | yes | `req.schema.json` |
+| `US`  | User Story | yes | `user-story.schema.json` |
+| `AC`  | Acceptance Criterion | no (nested in US) | `user-story.schema.json $defs.acceptanceCriterion` |
+| `TAD` | Technical Architecture Document | yes | `tad.schema.json` |
+| `TAC` | Technical Architecture Component | yes | `tac.schema.json` |
+| `ADR` | Architectural Decision Record | yes | `adr.schema.json` |
+| `BS`  | Build Sequence | yes | `build-sequence.schema.json` |
+| `FBS` | Functional Build Specification | yes | `fbs.schema.json` |
+| `TS`  | Test Suite | yes (one file per suite, sequential id `TS-\d{3}`) | `test-suite.schema.json` |
+| `TC`  | Test Case | no (nested in TS, id `TC-<TS-suffix>-<slug>`) | `test-suite.schema.json` |
+
+All prefixes are defined exactly once in `common.schema.json#/$defs` and referenced via `$ref` everywhere.
+
+## AC ids: flat or hierarchical
+
+The `acId` pattern is `^AC-\d{3,}(-\d+)?$`. Two forms are accepted:
+
+- **Flat:** `AC-001`, `AC-201` - single numeric space, fine for small projects.
+- **Hierarchical:** `AC-101-1`, `AC-101-2` - encodes the parent US id (`US-101`) in the prefix. Useful for FBS scope queries and grep.
+
+Pick per project; the schema does not enforce either form. The published `Stravica/rcf-examples` `comprehensive-product` tree uses the hierarchical form for clarity.
+
+## TS ids
+
+`^TS-\d{3}$`. Sequential, not parent-grouped: a US may have multiple TSs across levels (unit, integration, e2e, ...) and a parent-grouped id would collide. Recommended path: `rcf/test-suites/ts-001.json`.
+
+## TC ids
+
+`^TC-\d{3}-[a-z0-9-]+$`. TCs are nested in their parent TS's `testCases[]`. The pattern is `TC-<TS-suffix>-<slug>` where slug is a lowercase alphanumeric identifier chosen by the author (hyphens allowed). Examples: `TC-001-happy-path`, `TC-001-rejects-empty`, `TC-042-integration-boundary`. Slug uniqueness is within-TS, not global.
+
+Rationale: sequential numbering for TCs is brittle if you renumber; slug-based ids give readable pointers in test-suite bodies and traceability queries.
+
+## File-level vs nested-level: the asymmetry
+
+| Lives in its own file | Lives nested inside a parent |
+|---|---|
+| PRD, REQ, US, TAD, TAC, ADR, BS, FBS, TS | AC (inside US), TC (inside TS) |
+
+**The rule:** narrative-heavy structured documents that grow over time live in their own files (per-doc git history, parallel-safe authoring, no merge conflict on append). Tightly-coupled child structures (AC inside US, TC inside TS) stay nested, splitting them multiplies file counts without benefit.
+
+An AC outside its US has no meaning, the Given/When/Then only makes sense in the context of the asA / iWant / soThat triple. Same for TCs.

package/docs/manifest.md

@@ -0,0 +1,70 @@
+# manifest.schema.json
+
+Project manifest. Roots-only shape: declares `prd`, `tad`, `bs`. Children are owned by their parents and discovered by walking from the roots.
+
+## Canonical `$id`
+
+`https://schemas.stravica.io/rcf/v0.2.0/manifest.schema.json`
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `version` | string, `const: "2.0.0"` | Bundle major version. Lets tools dispatch on it. |
+| `projectName` | string, min 1 | Human-readable project name. |
+| `prd` | `docRef` | Root PRD. Singular. |
+| `tad` | `docRef` | Root TAD. Singular. |
+| `bs` | `docRef` | Root Build Sequence. Singular. |
+
+## Optional fields
+
+| Field | Type | Purpose |
+|---|---|---|
+| `description` | string | Short project description. |
+
+## `docRef` shape
+
+Defined once in `common.schema.json`:
+
+```json
+{
+  "id": "<doc-id>",
+  "path": "<relative-path-to-file>"
+}
+```
+
+Both fields are required.
+
+## What's NOT here
+
+Singular by design; no child arrays:
+
+- No `userStories[]`, `tacs[]`, `adrs[]`, `fbs[]`, `testSuites[]`, `requirements[]`.
+- No `prds: [...]` array (single-PRD per project).
+- No `activePrdId` (multi-PRD assumption retired).
+- No `buildSequence` (renamed to `bs` for abbreviation consistency with `prd`, `tad`, `fbs`, `tac`, `adr`).
+
+## Why roots-only
+
+SSoT discipline. Every parent-child edge is encoded exactly once, on the child, as a mandatory `<parent>Id` field:
+
+- Each **REQ** carries `prdId`; the walker inverts these to produce the PRD's requirement list.
+- Each **TAC** carries `tadId`; likewise for the TAD's component list.
+- Each **ADR** carries `tadId`; likewise for the TAD's decision list.
+- Each **FBS** carries `bsId` (plus `buildOrder` and `executionStatus`); the walker computes the ordered per-BS FBS list by filter + sort.
+- Each **US** carries `reqId`; the set of USs under a REQ is `childrenByParent.get(reqId)`.
+- Each **TS** carries `usId` and the `acIds[]` it verifies; the walker inverts these into cross-link maps.
+
+Enumerating children in the manifest as well would create two sources of truth; pick one. The child owns the reference. The manifest stays small (~8 properties) and a new US / TAC / ADR / FBS / REQ / TS never requires a manifest edit.
+
+## Example
+
+```json
+{
+  "version": "2.0.0",
+  "projectName": "Acme Notes",
+  "prd": { "id": "PRD-001", "path": "rcf/prd.json" },
+  "tad": { "id": "TAD-001", "path": "rcf/tad.json" },
+  "bs":  { "id": "BS-001",  "path": "rcf/build-sequence.json" }
+}
+```

package/docs/prd.md

@@ -0,0 +1,64 @@
+# prd.schema.json
+
+Product Requirements Document. One per project. Pure shell document; REQ bodies live in [req.schema.json](./req.md) files and each REQ carries the mandatory `prdId` back-reference. The walker computes the PRD's requirement list by inverting `REQ.prdId` at load time.
+
+## Canonical `$id`
+
+`https://schemas.stravica.io/rcf/v0.2.0/prd.schema.json`
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `prdId` | `^PRD-\d{3,}$` | The PRD identifier. |
+| `productName` | string, min 1 | Human-readable product name. |
+| `version` | semver string | Per-document version, independent of the schema bundle's. |
+| `status` | `authoringStatus` enum | `draft`, `review`, `needsRevision`, `approved`, `superseded`. |
+| `problemStatement` | string, min 1 | One-paragraph framing of the problem the product solves. |
+| `objectives` | array, min 1 | Outcomes the product is judged on. |
+| `createdAt` | ISO 8601 date-time | First creation. |
+| `updatedAt` | ISO 8601 date-time | Last update. |
+
+## Optional fields
+
+| Field | Type | Purpose |
+|---|---|---|
+| `executiveSummary` | string | One-paragraph summary above the fold. |
+| `targetUsers` | array of strings | The user populations the product addresses. |
+| `inScope` | array of strings | What is included in this product. |
+| `outOfScope` | array of strings | What is deliberately left out, to head off scope creep. |
+| `constraints` | array of strings | Hard limits (budget, technology, regulatory). |
+
+## What's NOT here
+
+- **REQ bodies.** The PRD is a shell. REQ content lives in [req.schema.json](./req.md) files; each REQ carries the mandatory `prdId` back-reference. The walker inverts these to produce the PRD's requirement list.
+- **`requirementIds[]`.** Removed in 0.2.0; parents no longer store child lists.
+- **Architecture.** That belongs in [tad.schema.json](./tad.md).
+- **Test suites.** Those live per US, see [test-suite.schema.json](./test-suite.md).
+
+## Example
+
+```json
+{
+  "prdId": "PRD-001",
+  "productName": "Acme Notes",
+  "version": "0.1.0",
+  "status": "draft",
+  "problemStatement": "Users keep losing track of meeting notes scattered across tools.",
+  "objectives": ["Single home for personal notes across devices."],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-01-01T00:00:00Z"
+}
+```
+
+Fuller and minimal valid examples: `fixtures/valid/prd/`. Invalid examples illustrating common rejection cases: `fixtures/invalid/prd/`.
+
+## Traceability
+
+A PRD is the root of the requirements chain.
+
+```
+PRD -> REQ -> US -> AC -> TS -> TC
+```
+
+Each REQ carries `prdId`; the walker inverts these into a `childrenByParent` map to walk PRD -> REQ. Each US in turn carries `reqId` for the next hop.

package/docs/req.md

@@ -0,0 +1,57 @@
+# req.schema.json
+
+Individual Requirement within a PRD. One file per REQ. Recommended path: `rcf/requirements/REQ-001.json`.
+
+## Canonical `$id`
+
+`https://schemas.stravica.io/rcf/v0.2.0/req.schema.json`
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `reqId` | `^REQ-\d{3,}$` | This requirement's identifier. |
+| `prdId` | `^PRD-\d{3,}$` | The parent PRD. |
+| `title` | string, min 1 | One-line title. |
+| `description` | string, min 1 | One-paragraph description. |
+| `category` | enum: `functional`, `nonFunctional`, `technical`, `security` | Per-doc-type enum; lives local to this schema. |
+| `domain` | string, min 1 | Free-form domain label (`auth`, `sync`, `billing`, etc.). Authors pick conventions per project. |
+| `priority` | enum: `must`, `should`, `could`, `wont` | MoSCoW. |
+| `version` | semver string | Per-document version. |
+| `status` | `authoringStatus` enum | `draft`, `review`, `needsRevision`, `approved`, `superseded`. |
+| `createdAt` / `updatedAt` | ISO 8601 date-time | Lifecycle timestamps. |
+
+## Optional fields
+
+| Field | Type | Purpose |
+|---|---|---|
+| `rationale` | string | Why this REQ exists. |
+| `tags` | array of strings | Free-form tags for grouping or filtering. |
+
+## Why REQ is its own file
+
+REQs grow over time, and a single PRD can carry hundreds. Inline REQ bodies on the PRD shell hit the GitHub API 1 MB file-fetch limit on rich PRDs and create merge-conflict pressure on the PRD whenever any REQ is edited. One file per REQ gives per-REQ git history, parallel-safe authoring, and a shell PRD that stays small. Same reasoning as ADR-per-file, TAC-per-file, FBS-per-file, US-per-file.
+
+## Cross-doc consistency
+
+The schema validates each REQ in isolation. Whether the `prdId` back-reference resolves to a loaded PRD is a walker-time referential-integrity check (Phase 5 traceability in `rcf-build-lite`), not a schema one.
+
+## Example
+
+```json
+{
+  "reqId": "REQ-001",
+  "prdId": "PRD-001",
+  "title": "Capture markdown notes",
+  "description": "The system must let a user write a markdown note and persist it.",
+  "category": "functional",
+  "domain": "capture",
+  "priority": "must",
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-01-01T00:00:00Z"
+}
+```
+
+Fuller example in `fixtures/valid/req/req-002-comprehensive.json`; invalid cases in `fixtures/invalid/req/`.

package/docs/tac.md

@@ -0,0 +1,49 @@
+# tac.schema.json
+
+Technical Architecture Component. One file per architectural component. Verbose per-component descriptions are fine; the schema does not constrain length.
+
+## Canonical `$id`
+
+`https://schemas.stravica.io/rcf/v0.2.0/tac.schema.json`
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `tacId` | `^TAC-\d{3,}$` | This component's identifier. |
+| `prdId` | `^PRD-\d{3,}$` | Root PRD. |
+| `tadId` | `^TAD-\d{3,}$` | Parent TAD. |
+| `version` | semver | Per-document version. |
+| `status` | `authoringStatus` enum | Lifecycle status. |
+| `name` | string, min 1 | Human-readable component name. |
+| `purpose` | string, min 1 | One-paragraph statement of what this component is for. |
+| `responsibilities` | array of strings, min 1 | What the component owns. |
+| `createdAt` / `updatedAt` | ISO 8601 date-time | Lifecycle timestamps. |
+
+## Optional fields
+
+| Field | Type | Purpose |
+|---|---|---|
+| `internalStructure` | string | Module breakdown, sub-component shape, key data types described in prose. |
+| `interfaces` | array of `interfaceDef` | What the component exposes (APIs, events, CLIs, web components, daemons, etc.). |
+| `dependencies` | array of `dependencyRef` | What this component depends on (other TACs or external systems). |
+| `tradeoffs` | string | Design trade-offs accepted. |
+| `notes` | string | Free-form notes the schema has no opinion on. |
+
+## Sub-schemas
+
+### `interfaceDef`
+
+Required: `name`, `kind`. Optional: `description`.
+
+`kind` is an **open string**, not an enum. Enumerating every kind of interface a component can expose (api, event, library, cli, SPA, web component, cron, daemon, microservice, batch...) is doomed; heavy `"other"` use in a closed enum signals the enum doesn't fit. The open string preserves the field for implementation-level filtering without imposing a brittle constraint.
+
+### `dependencyRef`
+
+Required: `name`, `kind`. Optional: `tacId` (when `kind` is `tac`), `description`.
+
+`kind` IS a closed enum here: `tac` (internal TAC-to-TAC dependency) or `external` (third-party services, libraries, infrastructure). The internal/external split is genuinely binary at the schema level, so the enum fits.
+
+## Example
+
+See `fixtures/valid/tac/tac-002-comprehensive.json` for a fuller TAC with multiple interfaces, mixed internal and external dependencies, and trade-offs called out.

package/docs/tad.md

@@ -0,0 +1,76 @@
+# tad.schema.json
+
+Master Technical Architecture Document. One per project. Pure shell for cross-cutting concerns; TAC and ADR each carry the mandatory `tadId` back-reference. The walker computes the TAD's component and decision lists by inverting `TAC.tadId` and `ADR.tadId` at load time. The schema defines the FULL set of possible sections; what's required for a given project is a tooling decision.
+
+## Canonical `$id`
+
+`https://schemas.stravica.io/rcf/v0.2.0/tad.schema.json`
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `tadId` | `^TAD-\d{3,}$` | TAD identifier. |
+| `prdId` | `^PRD-\d{3,}$` | Root PRD. |
+| `version` | semver | Per-document version. |
+| `status` | `authoringStatus` enum | Lifecycle status. |
+| `systemOverview` | object | See sub-schema below. |
+| `createdAt` / `updatedAt` | ISO 8601 date-time | Lifecycle timestamps. |
+
+## Optional sections (all top-level)
+
+When present, each section's own required fields apply.
+
+| Field | When useful |
+|---|---|
+| `architecturePrinciples` | If the project codifies design principles. |
+| `dataArchitecture` | For systems with non-trivial data stores or flows. |
+| `integrationArchitecture` | For systems with external APIs or events. |
+| `securityArchitecture` | For systems with non-trivial auth or threat models. |
+| `deploymentArchitecture` | For systems with deployment topology worth describing. |
+| `operationalConcerns` | For long-running services. |
+
+## Sub-schemas (in `$defs`)
+
+### `systemOverview` (required)
+
+`executiveSummary`, `systemPurpose`, `architecturalApproach`, `keyCapabilities[]` (all required, non-empty).
+
+### `principle`
+
+Used inside `architecturePrinciples[]`. Required: `name`, `description`, `rationale`.
+
+### `dataArchitecture`
+
+Required: `dataStores[]` (each `{name, kind, purpose?}`), `coreEntities[]` (each `{name, description?}`). Optional: `dataFlow`, `retention`.
+
+### `integrationArchitecture`
+
+Required: `apiDesign`. Optional: `externalSystems[]`, `eventModel`.
+
+### `securityArchitecture`
+
+Required: `authenticationPattern`, `authorizationModel`. Optional: `secretsManagement`, `threatModel`, `complianceRequirements[]`.
+
+### `deploymentArchitecture`
+
+Required: `targetEnvironment`. Optional: `topology`, `scaling`, `cicd`.
+
+### `operationalConcerns`
+
+Required: `healthChecks`, `logging`. Optional: `metrics`, `alerting`, `backup`, `disasterRecovery`.
+
+## TAD decomposition
+
+TAD + TAC + ADR is intentional. The v1 monolithic TAD ran to thousands of lines and produced useless git history. Decomposition gives:
+
+- **TAD** - project-wide architecture (overview + cross-cutting concerns).
+- **TAC** (`tac.schema.json`) - one per architectural component, verbose descriptions OK. Each TAC carries `tadId`.
+- **ADR** (`adr.schema.json`) - one per architectural decision, one file each (Nygard convention). Each ADR carries `tadId`.
+
+## What's NOT here
+
+- **Component bodies.** Live in [tac.schema.json](./tac.md); each TAC carries the mandatory `tadId` back-reference. The walker inverts these to produce the TAD's TAC list.
+- **Decision bodies.** Live in [adr.schema.json](./adr.md); each ADR carries the mandatory `tadId` back-reference. The walker inverts these to produce the TAD's ADR list.
+- **`componentIds[]` and `architecturalDecisionIds[]`.** Removed in 0.2.0; parents no longer store child lists.
+- **Generation metadata.** LLM call counts, token usage, generation timestamps belong to tooling (e.g. `.rcf/generation-log.json` sidecar). The schema describes the document only.

package/docs/test-suite.md

@@ -0,0 +1,56 @@
+# test-suite.schema.json
+
+Test Suite. One file per Test Suite. The JSON specification of what Test Cases exist for one or more Acceptance Criteria on a single User Story.
+
+## Canonical `$id`
+
+`https://schemas.stravica.io/rcf/v0.2.0/test-suite.schema.json`
+
+## TS-as-JSON: what this schema is for
+
+The TS schema validates the *specification* of the test cases (id, description, AC covered, authored status). It is the **contract for the test-writer** (human or AI). The executable test (Jest, pytest, JUnit, ...) is the *implementation* of that spec; the optional `testCase.testPointer` field points to the executable location.
+
+The JSON form is what lets Phase 5 traceability tooling walk `AC -> TS -> TC` programmatically, without parsing source-language test code. Whether the executable test file matches its TS spec is a separate concern (a test-of-the-test, owned by Phase 5 or the test-writer's own discipline).
+
+## TS file location
+
+Recommended path under the RCF tree: `rcf/test-suites/ts-001.json`. The schema validates the JSON shape; location is an implementation choice and is not enforced by schema or enumerated by manifest.
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `^TS-\d{3}$` | Test Suite identifier. Sequential, not parent-grouped (a US can have multiple TSs across levels). |
+| `usId` | `^US-\d{3,}$` | Parent User Story. Mandatory back-reference. |
+| `title` | string, min 1 | Human-readable suite title. |
+| `purpose` | string, min 1 | One-paragraph "what this suite is testing and why". |
+| `testLevel` | enum | `unit`, `integration`, `e2e`, `contract`, `manual`. |
+| `acIds` | array of `acId`, min 1 | The ACs this suite verifies. TS holds the reference; ACs stay clean of downstream references. |
+| `testCases` | array of `testCase`, min 0 | Inline TCs. Empty array allowed (a suite may be a purpose-only skeleton pre-authoring). |
+| `status` | `authoringStatus` enum | Lifecycle status of the suite itself. |
+| `createdAt` / `updatedAt` | ISO 8601 date-time | Lifecycle timestamps. |
+
+## Test case shape
+
+Each entry in `testCases[]`:
+
+| Field | Type | Required | Purpose |
+|---|---|---|---|
+| `id` | `^TC-\d{3}-[a-z0-9-]+$` | yes | TC identifier. `TC-<TS-suffix>-<slug>`; slug is a lowercase alphanumeric identifier (hyphens allowed). Slug uniqueness is within-TS, not global. |
+| `acId` | `^AC-\d{3,}(-\d+)?$` | yes | Which AC on the parent US this TC verifies. |
+| `description` | string, min 1 | yes | What the TC covers. |
+| `testPointer` | string | no | Pointer to the executable test, `filePath::testName` format. |
+| `status` | enum | yes | `pending`, `passing`, `failing`, `skipped`. Authored in 0.2.0; derived from real test runs in Phase 6+. |
+
+## What changed in 0.2.0
+
+The 0.1.0 shape was per-AC (`acId` + `prdId` + `version` + `testCases[given/when/then]`). 0.2.0 makes the suite per-US-and-across-ACs, keeps the TS id in `common.schema.json` (`tsId`), and moves the Given/When/Then verbiage into the TC's `description` (specialised BDD-style step language belongs in the executable test, not the JSON spec).
+
+## What's NOT here
+
+- **`given/when/then` on the TC.** The `description` field carries the intent; the executable test carries the BDD step language.
+- **`prdId` on the TS.** Removed in 0.2.0. Walk `usId` -> `US.reqId` -> `REQ.prdId` if you need the PRD.
+
+## Why TCs stay nested
+
+A TC outside its TS (and its AC) is meaningless. TCs are small; inline is the natural shape. `testPointer` links out to the executable location without hoisting the TC into a separate file.

package/docs/user-story.md

@@ -0,0 +1,61 @@
+# user-story.schema.json
+
+User Story document. One file per US. Contains Acceptance Criteria inline as `acceptanceCriteria[]`.
+
+## Canonical `$id`
+
+`https://schemas.stravica.io/rcf/v0.2.0/user-story.schema.json`
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `usId` | `^US-\d{3,}$` | This story's identifier. |
+| `prdId` | `^PRD-\d{3,}$` | The root PRD. |
+| `reqId` | `^REQ-\d{3,}$` | The parent REQ. |
+| `version` | semver | Per-document version. |
+| `status` | `authoringStatus` enum | Lifecycle status. |
+| `title` | string, min 1 | One-line title. |
+| `asA` | string, min 1 | "As a {asA}..." |
+| `iWant` | string, min 1 | "...I want {iWant}..." |
+| `soThat` | string, min 1 | "...so that {soThat}." |
+| `acceptanceCriteria` | array of `acceptanceCriterion`, min 1 | The testable conditions for this story. |
+| `createdAt` / `updatedAt` | ISO 8601 date-time | Lifecycle timestamps. |
+
+## Optional fields
+
+| Field | Type | Purpose |
+|---|---|---|
+| `description` | string | Additional narrative beyond the asA / iWant / soThat triple. |
+
+## Acceptance criterion shape
+
+Each AC inside `acceptanceCriteria[]`:
+
+| Field | Type | Required | Purpose |
+|---|---|---|---|
+| `id` | `acId` | yes | `AC-201` (flat) or `AC-101-1` (hierarchical). |
+| `description` | string, min 1 | yes | One-line description. |
+| `given` | string | no | Given/When/Then preamble. |
+| `when` | string | no | Trigger. |
+| `then` | string | no | Observable outcome. |
+| `testable` | boolean | yes | Author declares the AC is testable. |
+
+The Given/When/Then triple is optional at the schema level so non-Gherkin teams aren't forced into it; the `testable` boolean is required to make authors stop and confirm the AC can actually be tested.
+
+## Why ACs stay nested
+
+An AC outside its US is meaningless, the AC's Given/When/Then only makes sense in the context of the asA / iWant / soThat triple. Splitting would multiply file counts 5-10x with no benefit. Granular ids (`AC-101-1`) keep cross-doc references precise.
+
+## Example
+
+See `fixtures/valid/user-story/us-002-hierarchical-acs.json` for a US with three Given/When/Then ACs in the `AC-101-N` hierarchical form.
+
+## AC id form: flat or hierarchical
+
+The pattern `^AC-\d{3,}(-\d+)?$` accepts both:
+
+- **Flat** (`AC-001`, `AC-201`) - fine for projects with a single numeric space.
+- **Hierarchical** (`AC-101-1`, `AC-101-2`) - encodes the parent US id, useful for FBS scope queries and grep.
+
+Pick per project; the schema does not enforce either.

package/fixtures/invalid/adr/adr-001-authoring-status.json

@@ -0,0 +1,13 @@
+{
+  "adrId": "ADR-001",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "approved",
+  "title": "x",
+  "context": "y",
+  "decision": "z",
+  "consequences": "w",
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-01-01T00:00:00Z"
+}

package/fixtures/invalid/adr/adr-002-supersededBy-bad-id.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-001",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "0.1.0",
+  "status": "superseded",
+  "title": "x",
+  "context": "y",
+  "decision": "z",
+  "consequences": "w",
+  "supersededBy": "TAC-002",
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-01-01T00:00:00Z"
+}