ContextualWisdomLab · seonghobae · Aug 10, 2026 · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -0,0 +1,178 @@
+# ThreadWeave Architecture
+
+**Status:** Accepted as-built architecture for protected `main` at `4fa4caf86651193497002a3730ec19d8917f8818`  
+**Last reviewed:** 2026-08-10
+
+## Architectural goal
+
+ThreadWeave provides one deterministic email-threading kernel that remains useful as a zero-runtime-dependency standalone Python package and as a module inside a larger mail or knowledge service. Standards logic, transport presentation, host persistence, autonomous development, and release authority remain distinct boundaries.
+
+## As-built component map
+
+```mermaid
+flowchart LR
+    CALLER[Caller / host service]
+    ADAPT[adapters]
+    HDR[headers]
+    ENC[encoded_words]
+    SUBJ[subject]
+    COLL[collation]
+    DATE[dates]
+    CORE[threading]
+    NODE[container]
+    IMAP[imap]
+    FOREST[Container forest]
+    RESP[RFC 5256 THREAD data]
+
+    CALLER --> ADAPT
+    CALLER --> CORE
+    ADAPT --> HDR
+    ADAPT --> ENC
+    ADAPT --> CORE
+    CORE --> HDR
+    CORE --> SUBJ
+    SUBJ --> COLL
+    CORE --> DATE
+    CORE --> NODE
+    CORE --> FOREST
+    FOREST --> IMAP
+    IMAP --> RESP
+```
+
+## Module ownership
+
+| Boundary | Owns | Does not own |
+|---|---|---|
+| normalization (`headers`, `encoded_words`) | safe parsing/normalization of protocol text | mailbox storage, graph lifetime |
+| comparison (`subject`, `collation`) | RFC 5256 base subject and RFC 5051 key | semantic topic classification |
+| ordering (`dates`) | date normalization/order keys | scheduler clocks or persistence |
+| graph (`threading`, `container`) | authoritative batch forest | IMAP sessions, database state |
+| presentation (`imap`) | pure RFC 5256 projection/serialization | sockets, authentication, command dispatch |
+| adapters | stdlib email conversion | ownership of source message payloads |
+| GitHub automation | development/review/release evidence | runtime email behavior |
+
+## Current authoritative flow
+
+```text
+mail metadata / stdlib email
+→ normalize identifiers and header text
+→ canonical batch thread_messages
+→ optional subject fallback
+→ optional sent-date ordering
+→ Container forest
+→ optional non-mutating IMAP projection
+```
+
+`thread_messages` is the only structural correctness oracle. Transport adapters and future incremental state must delegate structural reconstruction to it rather than reproducing the algorithm.
+
+## Runtime trust boundary
+
+ThreadWeave runtime code is deliberately capability-poor:
+
+- no network client;
+- no database driver;
+- no subprocess/shell execution;
+- no model or cloud credentials;
+- no message-body rendering or active-content execution;
+- no tenant/session/authentication state.
+
+A caller may place arbitrary objects in `Message.payload`; the package treats those as opaque caller-owned references. Protocol output and future snapshots must not serialize arbitrary payload objects by accident.
+
+## Host-service boundary
+
+```mermaid
+flowchart LR
+    HOST[Host: naruon / IMAP server / archive]
+    AUTH[Host auth + tenancy]
+    STORE[(Host mailbox/persistence)]
+    SYNC[Host mailbox sync]
+    TW[ThreadWeave public API]
+    OUT[Thread forest / THREAD response]
+
+    HOST --> AUTH
+    HOST --> STORE
+    HOST --> SYNC
+    HOST --> TW
+    STORE -. metadata only .-> TW
+    SYNC -. stable caller metadata .-> TW
+    TW --> OUT
+```
+
+The host owns durable storage, tenant boundaries, authentication, distributed write serialization, mailbox sequence/UID lifecycle, audit, and API exposure. ThreadWeave does not read the host database directly.
+
+## Ordering architecture
+
+Sent-date ordering is optional to preserve backward compatibility. When enabled, date normalization is performed before RFC-defined sorting stages. An explicit `sequence_number`, when supplied, must be a positive mailbox sequence number. When it is omitted, the one-based `input_position` is used only as an internal ordering fallback. Effective ordering sequence values must be unique across all messages participating in sent-date sorting, because the implementation validates them before comparing dates. The input-position fallback is never exposed as, inferred to be, or persisted as a public IMAP sequence number.
+
+## Presentation architecture
+
+The IMAP serializer is a presentation boundary over a prebuilt forest. Search-result filtering produces a projection without mutating the source nodes. Invalid identifier state fails closed rather than being silently rewritten. This keeps threading correctness independent from IMAP session state.
+
+## Runtime and package compatibility
+
+Protected `main` supports Python 3.10 through 3.14 for the current release line. This is an evidence-backed compatibility boundary, not a syntax-only declaration: PR #27 merged after the complete Python matrix and the Python 3.14 package build, hash-install, and outside-source smoke succeeded. Changes to the Python support range, dependency lock, or build toolchain require fresh exact-head compatibility evidence and synchronized PRD/TRD/test/release documentation.
+
+## Active incremental target — not protected-main as-built
+
+PR #20 proposes the following extension:
+
+```mermaid
+flowchart LR
+    CHANGE[MailboxChangeSet]
+    IDX[IncrementalThreadIndex]
+    PART[affected component]
+    CORE[canonical thread_messages]
+    DELTA[ThreadDelta]
+    SNAP[payload-free snapshot]
+
+    CHANGE --> IDX
+    IDX --> PART
+    PART --> CORE
+    CORE --> IDX
+    IDX --> DELTA
+    IDX --> SNAP
+```
+
+Until PR #20 merges, `IncrementalThreadIndex`, RFC 8474 identity tracking, snapshots, and incremental mailbox benchmarks are ACTIVE-PR architecture only. A process-local lock in that proposal is not a distributed lock; any durable multi-process host continues to own write serialization.
+
+## Automation authority architecture
+
+```mermaid
+flowchart LR
+    DEV[OpenCode development process]
+    VERIFY[credential-free verification]
+    PUBLISH[trusted PR publisher]
+    CENTRAL[organization review/security/merge]
+    MAIN[protected main]
+
+    DEV -->|sealed bounded patch only| VERIFY
+    VERIFY -->|verified patch/evidence| PUBLISH
+    PUBLISH -->|PR only| CENTRAL
+    CENTRAL -->|policy satisfied| MAIN
+```
+
+The development model never receives merge/release authority. Organization-central review/security workflows remain independent. Repository-controlled code must not inherit the NVIDIA model key, GitHub write credentials, or OIDC credentials from privileged workflow phases.
+
+## Deployment modes
+
+1. **Embedded library — current:** ordinary Python dependency inside a host process.
+2. **Host adapter — supported architecture:** host exposes ThreadWeave through its own API/session/persistence layer.
+3. **Standalone network service — not provided by this repository:** a separate service may wrap the library, but must own auth, tenancy, persistence, rate limiting, audit, and deployment controls itself.
+
+## Failure behavior
+
+Expected malformed email/protocol input is handled deterministically where a public error contract exists. Cycles/deep structures terminate safely. The library must not turn unexpected programming defects into successful structural output.
+
+## Architectural change control
+
+Changes to any of these require an ADR and synchronized PRD/TRD/UML/ERD/security/test/operability documentation:
+
+- additional runtime capability or dependency;
+- alternative threading oracle;
+- persistence or network ownership;
+- durable snapshot schema;
+- external identity semantics;
+- Unicode comparison contract;
+- supported Python/runtime boundary;
+- protocol authority beyond pure presentation;
+- automation credential or merge-authority boundary.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,9 +6,23 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+- Extend the canonical architecture graph with a reconstruction-oriented
+  documentation fitness audit, data-governance/privacy boundary, incident/RCA
+  runbook, release/provenance/licensing gate, work-conserving autonomous
+  maintenance ADR, and exact evidence-identity ADR.
+- Restore `CLAUDE.md` as canonical agent context, explicitly preserving the
+  OpenCode + `NVIDIA_NIM_API_KEY` development boundary, prohibiting Copilot-token
+  use for development-model execution, and recording the protected-main Python
+  3.10–3.14 compatibility contract.
 - Add Python 3.14 to package classifiers and the full CI matrix, and build,
   hash-install, and smoke-test the distribution under Python 3.14 while
   preserving Python 3.10 as the minimum supported runtime.
+- Add a canonical product/technical architecture documentation graph with PRD,
+  TRD, root architecture, UML, conceptual ERD, API/version contract, indexed
+  ADRs, security/threat model, data governance, test strategy, operability,
+  incident/recovery, release provenance, traceability, and machine-checkable
+  documentation maturity guards that distinguish protected-main behavior from
+  active PR #20 incremental-state work.
 - Restore the hourly NVIDIA NIM/OpenCode product-development workflow's YAML and
   nested-shell contracts, and lint every GitHub Actions workflow with a pinned,
   checksum-verified `actionlint` release before ordinary CI may proceed.
@@ -109,7 +123,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   optional base-subject grouping.
 - `Message` input dataclass (`message_id`, `in_reply_to`, `references`,
   `subject`, `payload`) and loop-safe `Container` thread-tree node.
-- RFC 5322 §3.6.4 primitives extracted behaviour-preserving from the naruon
+- RFC 5322 §3.6.4 primitives extracted behaviour-preserving from naruon
   control plane: `normalize_message_id`, `extract_reference_ids`,
   `generate_email_fingerprint`.
 - `normalize_subject` / `is_reply_subject` base-subject helpers.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,48 @@
+# ThreadWeave Agent Context
+
+ThreadWeave is a deterministic, standards-grounded email-threading library. Repository code and the canonical documentation graph are authoritative; chat history, PR bodies, and generated summaries are supporting evidence only.
+
+## Read first
+
+Before changing product behavior or architecture, read:
+
+- `AGENTS.md`
+- `DOCUMENTATION.md`
+- `docs/PRD.md`
+- `docs/TRD.md`
+- `ARCHITECTURE.md`
+- `docs/adr/README.md`
+- `docs/TRACEABILITY.md`
+- `docs/TEST_STRATEGY.md`
+- `docs/SECURITY.md`
+
+## Product boundaries
+
+- Preserve `thread_messages` as the canonical structural correctness oracle unless an Accepted ADR explicitly supersedes that decision.
+- Keep the package usable as a zero-runtime-dependency standalone library and as a typed module inside naruon or another host.
+- Hosts own authentication, tenancy, mailbox persistence/synchronization, distributed locking, remote API lifecycle, durable audit, and deployment controls.
+- Do not invent a ThreadWeave database merely to satisfy an ERD. The current ERD is conceptual because the library owns no persistence.
+- Active PR behavior is not protected-main behavior. In particular, incremental mailbox state and RFC 8474 identity/snapshot contracts remain active-PR architecture until integrated.
+
+## Development rules
+
+- Use test-driven development for behavior changes: establish a realistic failing regression, implement the narrowest root-cause fix, then run focused and full verification.
+- Maintain exact 100% owned production statement and branch coverage and beginner-readable public docstrings.
+- Keep Python runtime/CI support claims synchronized with package metadata and the complete test matrix. Protected main currently proves Python 3.10–3.14; any support-range, dependency, or build-toolchain change must re-prove the complete matrix.
+- Use exact current-head and independently resolved live-base evidence for merge decisions. Queued, skipped, stale, cancelled, synthetic-only, status-only, or predecessor-head evidence is not passing.
+- Never weaken required checks, manufacture approval, or use a no-op source change merely to retrigger an external reviewer.
+- Never add self-modifying, one-shot branch-repair, or encoded-patch workflows as a substitute for a normal auditable source change.
+
+## Automation and credentials
+
+- Scheduled autonomous development uses an immutably pinned OpenCode Agent and `NVIDIA_NIM_API_KEY` only for actual model-backed execution.
+- `COPILOT_GITHUB_TOKEN` is not a development-model credential and must not be introduced into the autonomous development path.
+- Keep development-model credentials separate from deterministic verification, PR publication, independent review, merge, and release authority.
+- Central organization workflows and repositories with their own active writer loops are dependencies, not implicit write targets.
+- A run is work-conserving: a prompt edit, documentation audit, one commit, one PR action, one review request, or one queued check is never completion while another safe repository action exists.
+
+## Documentation and release
+
+Material changes to runtime capability, persistence, identity, Unicode/collation, ordering defaults, protocol authority, durable state, Python support, automation authority, or release evidence require the affected PRD/TRD/Architecture/ADR/UML/ERD/security/test/operability/traceability records to be reconciled in the same workstream.
+
+Release only from one exact integrated protected head that satisfies applicable CI, security, coverage/docstring, packaging, provenance/SBOM, compatibility, review, and release-acceptance gates. Update `CHANGELOG.md` and version metadata together and verify the published artifact after release.
diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
@@ -0,0 +1,45 @@
+# ThreadWeave Documentation Map
+
+Use this file as the discoverable index for product, technical, architecture, safety, governance, and operating documentation.
+
+| Area | Canonical document |
+|---|---|
+| Product requirements | [`docs/PRD.md`](docs/PRD.md) |
+| Technical requirements | [`docs/TRD.md`](docs/TRD.md) |
+| As-built architecture | [`ARCHITECTURE.md`](ARCHITECTURE.md) |
+| UML/runtime diagrams | [`docs/UML.md`](docs/UML.md) |
+| Conceptual domain/ERD | [`docs/ERD.md`](docs/ERD.md) |
+| Public API/version contract | [`docs/API_CONTRACT.md`](docs/API_CONTRACT.md) |
+| Architecture decisions | [`docs/adr/README.md`](docs/adr/README.md) |
+| Runtime/supply-chain security | [`docs/SECURITY.md`](docs/SECURITY.md) |
+| Threat model | [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) |
+| Data governance / privacy boundary | [`docs/DATA_GOVERNANCE.md`](docs/DATA_GOVERNANCE.md) |
+| Test strategy | [`docs/TEST_STRATEGY.md`](docs/TEST_STRATEGY.md) |
+| Operability/rollback | [`docs/OPERABILITY.md`](docs/OPERABILITY.md) |
+| Incident / RCA runbook | [`docs/INCIDENT_RUNBOOK.md`](docs/INCIDENT_RUNBOOK.md) |
+| Release/provenance/licensing gate | [`docs/RELEASE_PROVENANCE.md`](docs/RELEASE_PROVENANCE.md) |
+| Requirement/standard/evidence traceability | [`docs/TRACEABILITY.md`](docs/TRACEABILITY.md) |
+| Documentation fitness / maturity audit | [`docs/DOCUMENTATION_AUDIT.md`](docs/DOCUMENTATION_AUDIT.md) |
+| Standards and APA 7 references | [`docs/research/README.md`](docs/research/README.md) |
+| Supply-chain procedure | [`docs/supply-chain.md`](docs/supply-chain.md) |
+| Agent development policy | [`AGENTS.md`](AGENTS.md) |
+| Agent context | [`CLAUDE.md`](CLAUDE.md) |
+| User-facing product guide | [`README.md`](README.md) |
+| Release history | [`CHANGELOG.md`](CHANGELOG.md) |
+
+## Maturity labels
+
+Documentation in this repository must distinguish:
+
+- **implemented-main / IMPLEMENTED-ON-PROTECTED-MAIN**: present on protected `main`;
+- **active-PR / IMPLEMENTED-ON-ACTIVE-PR**: implemented or designed only on an open PR;
+- **proposed**: architectural decision under review;
+- **conceptual**: domain/ERD concept without ThreadWeave-owned persistence;
+- **host-owned**: responsibility belongs to naruon, an IMAP server, archive service, or another wrapper;
+- **planned / known gap**: accepted requirement not yet implemented/proven.
+
+PR #20 incremental mailbox state is active-PR/proposed until integrated. Sent-date ordering and RFC 5256 THREAD serialization are already implemented-main capabilities and must not be left in historical backlog lists. Python 3.14 CI/package support is a current known gap until it is implemented and proven on an exact head.
+
+## Documentation fitness rule
+
+`docs/DOCUMENTATION_AUDIT.md` is the reconstruction-oriented fitness record. It must distinguish design sufficiency from protected-main implementation sufficiency, identify missing or stale families, and prevent conversation-only decisions from being treated as durable architecture until they are captured in this graph.