Traceability

Section	What it covers
Why	What breaks without traceability
Provenance chain	How content flows through HAAK with attribution
Carriers	The structural mechanisms that maintain traceability
Gaps	What's not yet traced

#Why

Auditability is the foundational claim: every decision must be traceable to who decided what, when, and why. This architecture doc describes HOW that claim is implemented in the filesystem. Without structural traceability, auditability is aspirational — you believe decisions were recorded, but you can't reconstruct the path from output to input.

The cost of lost traceability is proportional to importance. A lost citation is a formatting inconvenience. A lost provenance chain on a review means you can't verify whether the reviewer saw the right version of the paper. A lost attribution on a foundation means you can't tell whether a design decision reflects the PI's judgment or an AI's suggestion.

#Provenance chain

Content flows through HAAK in a directed chain. Each stage has a defined location and a defined transition:

Raw input (voice notes, handwritten, Bear)
    ↓ /ingest → classify → route to destination
<destination>/sources/ (provenance copies, [[original]] links)
    ↓ thread splitting, promotion
Typed content:
    foundations/  (conceptual positions)
    patterns/architecture/ (structural decisions)
    patterns/policies/     (constraints)
    patterns/methods/      (procedures)
    patterns/features/     (capability designs)
    projects/              (manuscripts, reviews, proposals)
    personas/              (researcher models)
    ↓ composition, review, publication
Outputs (PDFs, opinions, review packages)

At every transition, the downstream document carries a pointer back to its source. The upstream document (when possible) carries a pointer forward to what it became. The chain is navigable in both directions.

#Carriers

Four structural mechanisms maintain traceability:

#Frontmatter fields

• source: — where this content came from (note path, Bear ID, external URL)
• created: — when it entered HAAK (immutable, write-once)
• related: — connections to other documents (symmetric for related, directional for depends/blocks)
• Model attribution in footer: haak · created YYYY-MM-DD · modified YYYY-MM-DD · zach + claude

#In-text links

• [[Original note title]] — links typed documents back to raw provenance copies in sources/ directories
• [external:], [gdrive:], [bear:] — pointers to content outside HAAK's git tree
• Citation references — DOIs linking claims to published literature

#Source snapshots

• source/ directories in review rounds (R*/source/) — frozen copies of what reviewers actually read
• source.md metadata files — canonical reference for external content
• These are immutable: once a review round starts, the source snapshot never changes

#Transcripts

• Session transcripts capture the decision-making process (which options were considered, what was approved, what was rejected)
• Frontmatter transcript: field links to the session that produced a document
• process: field names the method followed (e.g., process: workflow-pattern (Define → Collect → Reason → Act → Validate))

#Gaps

What's not yet systematically traced:

• Conversation → decision mapping: transcripts exist but there's no structured extraction of "decision X was made at turn Y for reason Z"
• Cross-session provenance: when work spans multiple sessions, the chain between sessions is implicit (git history + timestamps) rather than explicit
• Skill invocation tracing: which skills were composed to produce an output is reconstructible from transcripts but not declared in output frontmatter

Architecture 16 — Traceability — 2026 — Zachary F. Mainen / HAAK