Architecture

Principles

  1. Proof over pointers. A ticket, PR, file or imported claim is a pointer, not proof.
  2. Revision-bound. Evidence and approvals attach to an exact requirement revision.
  3. Unknown stays unknown. Missing facts are questions, never defaults.
  4. Offline and zero dependencies. Node.js built-ins only; no keys, no telemetry.
  5. Tamper evidence, honestly labelled. SHA-256 chains and seals detect edits; they are not signatures.

Layers

LayerImplementation in 0.2.1Status
BusinessRoles: product owner approves, engineer links, auditor verifiesimplemented as process contract
Capabilityintake, elicitation, versioning, acceptance, approval, evidence graph, impact, reports, auditimplemented
DomainRequirement, Revision, Source, Question, Criterion, Approval, Link, Attestation, Auditimplemented
SystemCLI, core library, registry file, report engine, loopback APIimplemented
Componentparser, normalizer, question engine, scenario generator, revision historian, trace evaluator, reporter, audit verifier, assurance auditor, installerimplemented
Data.intentsutra/requirements.json, audit.jsonl, canonical hashes, immutable history snapshotsimplemented
IntegrationGit, GitHub, ClickUp, Jira, OpenSpec, Spec Kit, CI, MCPplanned (contracts only)
EnterpriseOIDC, RBAC, PostgreSQL, signed audit, tenancyplanned

Component map

ModuleResponsibility
packages/core/common.mjshashing, canonical JSON, path containment, bounded reads, atomic writes, redaction
packages/core/requirements.mjsMarkdown parser, normalizer, questions, acceptance drafts, registry validation
packages/core/registry.mjsinit, ingest, revise, approve, link, attest; every mutation appends an audit event
packages/core/trace.mjsper-requirement state, evidence integrity re-check, impact
packages/core/reports.mjsJSON, Markdown, HTML traceability and companion artifacts
packages/core/assurance.mjsindependent audit: 11 checks, severity, seal, JSON/MD/HTML
packages/core/audit.mjshash-chained JSONL log
packages/core/installer.mjsproject-local IDE instruction packs
packages/server/server.mjsread-only authenticated loopback API
packages/cli/index.mjsargument parsing, deterministic exit codes

Dependency direction is strictly cli/server → core; core modules never import the CLI.

Data flow

brief.md / requirements.json
   → ingest (size cap, untrusted label, SHA-256)
   → Requirement rev 1 + questions + draft acceptance
   → approve (human, exact revision)
   → link code / test / test-run / release  (bound to revision, file hashed)
   → attest (needs approval + code + imported pass + imported release)
   → revise → rev 2: approvals and links become stale history
   → trace / report / audit (re-derive; write JSON, MD, HTML)

Key decisions

ADRDecisionReason
1JSON file registry, not a databaseinspectable, diffable, zero dependencies; DB is M5
2Hash-chained JSONL auditdetects edits cheaply; signatures need key management
3No completed stateprevents completion by proxy
4Audit re-derives instead of trusting registry labelscatches forged or edited state
5Registry changes must be explained by audit eventsdetects silent edits (AUD-08)
6No test execution in M0running untrusted code needs an isolated, opt-in runner (M1)

Known limits

No multi-process locking; a privileged local user can rewrite both registry and log; hashes show bytes unchanged, not correctness.