Codebase: Amanuensis Date: 2026-08-12 Onboarding session: mspky4v5-2wuk50if
§Epistemic status
This report is an onboarding map at repository revision b8b566f, not a completed subsystem survey. Observations cite code or repository contracts. Subsystem behavior and correctness remain unverified until the corresponding subsystem reaches the required survey phase.
§Repository shape
| Dimension | Observed value | Confidence |
|---|---|---|
| Primary language(s) | TypeScript/JavaScript and Python | Code verified |
| Secondary language(s) | SQL, Markdown, YAML/JSON | Code verified |
| Build system(s) | npm/TypeScript; Python standard library with Ruff for lint | Config asserted |
| Code generation present? | Yes | Code verified |
| Generated file patterns | mcp-server/dist/**; package mirrors of agents/** and materializer/**; generated ROADMAP.md | Code verified |
| Monorepo or single service? | One product with server, materializer, prompt/agent, and delivery surfaces | Docs asserted |
| Deployable unit count | Two executables: amanuensis-memory and installer CLI; Python materializer is invoked as a subprocess | Code verified |
| Canonical branch | main | Config asserted |
| Branch convention | codex/ for this implementation lane; historical feat/ and docs/ branches exist | Config asserted |
| Onboarding SHA | b8b566f | git-observed |
§Directory cluster map
| Cluster | Apparent role | Language | Confidence | Notes |
|---|---|---|---|---|
.claude/skills/amanuensis/ | Canonical survey methodology and phase references | Markdown | High | Source for skill-driven operation. .claude/skills/amanuensis/SKILL.md@b8b566f. |
agents/ | VS Code custom-agent bundle and public references | Markdown | High | Package source copied by prepack. mcp-server/scripts/prepack-bundle-assets.mjs@b8b566f. |
mcp-server/src/ | MCP bootstrap, persistence, invariants, CLI, and tool handlers | TypeScript/SQL | High | One stdio server registers 75 tools. mcp-server/src/index.ts:main@b8b566f. |
mcp-server/test-*.mjs and scripts/ | Contract, adversarial, integration, performance, and generation gates | JavaScript | High | CI enumerates the authoritative gate set. .github/workflows/test.yml@b8b566f. |
materializer/ | Read-only projection of DB/prose state into linked Markdown | Python | High | Uses per-page source hashes and a manifest. materializer/amanuensis_materializer/core.py:Materializer@b8b566f. |
dev/, root docs, .github/ | Product direction, research/design notes, contribution and delivery contracts | Markdown/JSON/JS/YAML | High | ROADMAP.md is generated from dev/roadmap.json. dev/render-roadmap.mjs@b8b566f. |
§Runtime boundary map
Host agent runtime
externalCommunicates withMCP server
Mechanismstdio MCP
Recorded noteStarts the server with a workspace path. .mcp.json@b8b566f.
amanuensis-memory
Node/TypeScriptCommunicates withhost, SQLite, git, Python
MechanismMCP stdio, native SQLite binding, subprocess
Recorded noteOwns validation and durable records. mcp-server/src/index.ts:main@b8b566f.
SQLite memory.db
SQLCommunicates withMCP server and materializer
MechanismWAL; one writer API, read-only materializer connection
Recorded noteSchema initializes and migrates on open. mcp-server/src/db.ts:openDatabase@b8b566f.
Git storage history
git subprocessCommunicates withstorage directory
Mechanismsynchronous child process
Recorded noteCommits DB/prose state at gates. mcp-server/src/storage-git.ts:commitStorage@b8b566f.
Python materializer
PythonCommunicates withSQLite and prose storage
Mechanismchild process and filesystem
Recorded noteEmits docs and .manifest.json. materializer/amanuensis_materializer/core.py:Materializer.materialize@b8b566f.
Installer CLI
Node/TypeScriptCommunicates withworkspace files
Mechanismfilesystem/config merge
Recorded noteWrites agents and VS Code MCP config. mcp-server/src/cli.ts:plan@b8b566f.
§Significant stateful entities
| Name | What it stores | Lifetime | Populated by | Invalidated by |
|---|---|---|---|---|
memory.db + WALLocation: ~/.amanuensis/workspaces/<owner>/<repo>/ | Survey entities, evidence, findings, sessions, queries, locks, seams | Cross-session | MCP tool handlers | Explicit reset/status/validity operations; schema has no general claim-time model yet |
ServerContext.sessionIdLocation: mcp-server/src/index.ts | Active writer session | Server process | start_session | end_session or process exit |
| Storage git repositoryLocation: project storage directory | Checkpoint history of non-ignored storage files | Cross-session | commit_phase_gate, end_session | Git history only; rollback is external |
| File ledger and git baselineLocation: SQLite tables | File-to-subsystem assignment and checked revision | Cross-session | scope and git tools | reset/change detection |
| Materializer manifestLocation: rendered docs directory | Per-page source/content hashes | Cross-render | materializer | source/version/content difference or page retirement |
| Write locks and dispatch rowsLocation: SQLite tables | Advisory coordination and fan-out history | Cross-process | lock/dispatch tools | release/expiry and completion calls |
§Concern calibration
| Territory | Verdict | Derived concerns / disqualifier |
|---|---|---|
| T1 scope-context identity | applicable | SI-1, SI-2 |
| T2 cache coherence | applicable by analogy to derived-state manifests and git baselines | CC-1 |
| T3 temporal bounds | applicable | TB-1 |
| T4 exceptional-path asymmetry | applicable | EP-1, EP-2 |
| T5 aliasing/ownership | not seeded | MCP values cross serialization boundaries and no shared returned mutable object was established during onboarding; revisit if B-02/B-03 finds one |
| T6 incremental/full divergence | applicable | IF-1 |
| T7 atomicity | applicable | AT-1, AT-2 |
| T8 concurrency races | applicable | CR-1 |
| T9 resource lifecycle | applicable | RL-1, RL-2 |
| T10 trust boundary | applicable | TR-1, TR-2 |
| T11 seam contracts | applicable | SC-1, SC-2 |
The calibrated checklist is in concern-checklist.md; the SQLite concern rows are authoritative for later disposition coverage.
§Draft master plan
Five subsystems were registered. B-02 and B-03 share priority 1 because all durable authority flows through their schema/invariant and handler seam. B-04 and B-01 share priority 2; delivery and documentation are B-05 at priority 3. See master-plan.md.
§Questions for the human
§Tier 1 — Blockers
- Should “fully surveyed” include every tracked test, generated file, prompt, and product document? Working assumption: yes, with explicit exclusions only.
§Tier 2 — Priority shapers
- Should the installer support Codex MCP registration alongside VS Code? Working assumption: record the gap in B-05; do not expand A0 installer scope.
§Tier 3 — Context
- Should phase checkpoints version live SQLite contents? Working assumption: yes; AT-2 remains active because WAL-backed mutations produced no storage commit during onboarding.
§Recommended first mapping
Top: B-02 — it owns database initialization, validity gates, session identity, project identity, and checkpoint mechanics.
Second: B-03 — it is the largest mutation surface and turns the B-02 contracts into the actual workflow API.