[codex] Add technical teardown with valid Mermaid diagrams

[flyingrobots]

Summary

• Adds TECHNICAL-TEARDOWN.md as a repository architecture teardown document.
• Quotes Mermaid flowchart labels that contain punctuation, including parseFlags(argv) and path-like labels.
• Renames the ER relationship label from to to target so Mermaid does not parse it as syntax.

Problem Statement

TECHNICAL-TEARDOWN.md contained Mermaid diagrams that failed to render in GitHub Markdown. The command execution diagram failed on a punctuation-heavy node label, and the ER diagram failed because to conflicted with Mermaid parsing in that relationship position. The document should render cleanly before it is reviewed or used as architecture reference material.

ADR Compliance (Required)

Relevant ADR(s)

• ADR-0002 (Worktree Independence and Materialization Architecture)
• ADR-0003 (Graph-Native Content, Deterministic Materialization, and Workspace Bridge)
• None

Compliance Declaration

• This PR is fully compliant with all checked ADRs.
• This PR intentionally deviates from one or more checked ADRs (complete Exception Request below).

Exception Request (Required if deviating)

• ADR clause(s) deviated from: None.
• Why deviation is necessary now: Not applicable.
• Risk introduced by deviation: None.
• Mitigation and rollback plan: Revert this docs-only commit if needed.
• Follow-up ADR/issue to reconcile architecture debt: None.

---

Architecture Laws Checklist (Hard Gates)

Canonical Truth & Context

• Graph remains canonical truth (no dual truth with generated files).
• No hidden worktree coupling introduced in core/domain/materialization paths.
• Context-sensitive behavior is explicit (--at, --observer, --trust) or deterministically defaulted.
• Resolved context is surfaced in output metadata where applicable.

Determinism & Provenance

• Pure query/materialization paths remain deterministic for identical inputs.
• Mutations/materializations include provenance receipts/envelopes where required.
• Cache keys (if used) are derived only from semantic inputs + pinned versions.

Artifact Hygiene

• No forbidden generated artifact paths are tracked.
• Any generated artifacts intentionally tracked are in allowlisted publish paths only.
• Pre-commit/CI policy checks updated or confirmed valid.

Contracts & Compatibility

• Machine-facing outputs are schema-versioned.
• Breaking contract changes include version bump + migration notes.
• Backward compatibility impact is documented below.

Extension/Effects Safety (if applicable)

• Extension behavior does not bypass capability restrictions.
• Effectful operations use explicit plan/apply semantics and emit receipts.
• Timeouts/resource bounds are defined for new script/effect paths.

---

Scope Control

• PR is single-purpose/cohesive (no unrelated refactors).
• Any non-essential refactor is split into separate PR(s) or explicitly justified.

Backward Compatibility

• CLI/API contract changes: None.
• Data model/storage changes: None.
• Migration required?: No.
• User-facing behavior changes: GitHub-rendered documentation now includes a technical teardown whose Mermaid diagrams render successfully.

Test Plan (Required)

Unit

• Added/updated tests for changed logic
• Commands:

# Not run; docs-only change with no product logic touched.

Integration

• Added/updated integration tests
• Commands:

# Not run; docs-only change with no product logic touched.

Determinism

• Determinism assertions included for relevant paths
• Method: Not applicable; no runtime behavior changed.
• Commands:

# Not run; docs-only change with no product logic touched.

Contract/Schema

• Schema validation updated/passing
• Commands:

# Not run; no contract or schema files changed.

Policy Gates

• Mechanical architecture gates pass
• Commands:

node -e 'const fs=require("fs"); const out="/private/tmp/git-mind-mermaid"; fs.rmSync(out,{recursive:true,force:true}); fs.mkdirSync(out,{recursive:true}); const s=fs.readFileSync("TECHNICAL-TEARDOWN.md","utf8"); const re=/```mermaid\n([\s\S]*?)```/g; let i=0; for (const m of s.matchAll(re)) { const before=s.slice(0,m.index); const line=before.split("\n").length; const file=`${out}/diagram-${String(++i).padStart(2,"0")}-line-${line}.mmd`; fs.writeFileSync(file,m[1]); console.log(`${file}`); }'
ok=1; for f in /private/tmp/git-mind-mermaid/*.mmd; do out=${f%.mmd}.svg; printf 'render %s\n' "$f"; if ! mmdc -i "$f" -o "$out" --quiet; then ok=0; fi; done; exit $((1-ok))
git diff --cached --check

---

Security / Trust Impact

• Threat surface changed?: No.
• Trust policy impact: None.
• Provenance/audit impact: None beyond normal Git commit history.
• New failure modes introduced: None known.

Performance Impact

• Hot path affected?: No.
• Expected impact (latency/memory/io): None.
• Benchmarks or profiling evidence: Not applicable for a docs-only change.

Observability / Debuggability

• Errors are actionable and include context.
• Logs/diagnostics added or updated where needed.
• git mind status / diagnostics updated if writeback/eventing behavior changed.

Operational Notes

• Feature flag (if any): None.
• Rollback strategy: Revert commit 49d8516.
• Operational caveats: None.

Linked Issues / Milestones

• Closes Fix Mermaid rendering in technical teardown #318
• Milestone: None

---

Reviewer Quick Verdict Block (for maintainers)

MUST (Hard Gates)

• PASS
• CONDITIONAL
• FAIL

SHOULD (Quality)

• PASS
• CONDITIONAL
• FAIL

Verdict

• APPROVE
• APPROVE WITH CHANGES
• REJECT

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 12dfe873-0b25-4a5d-bee7-df2b27d93205

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[flyingrobots]

@codex please confirm these self-review findings before merge.

Self-Code Review: #319

Strict review scope: origin/main...origin/feat/technical-teardown-mermaid after git fetch --prune origin.

Summary

Severity	Count
Critical	0
High	0
Medium	1
Minor	3

Findings

File	Lines	Severity	Infraction	Evidence	Recommended mitigation prompt
TECHNICAL-TEARDOWN.md	61, 134, 204, 303, 393	Medium	Markdown heading hierarchy violation	The document starts with # TECHNICAL TEARDOWN: git-mind at line 1, then introduces five more top-level # headings. markdownlint reports MD025 for each of these section headings.	Fix TECHNICAL-TEARDOWN.md heading hierarchy: keep only the document title as H1, demote the major sections to H2, demote their subsections to H3, and update the table of contents anchors if needed.
TECHNICAL-TEARDOWN.md	65, 69, 138, 151, 155, 167, 187, 191, 202, 241, 245, 274, 278, 295, 297, 299, 301, 307, 319, 323, 329, 333, 347, 351, 367, 371, 373, 375, 377, 379, 381, 385, 387, 388, 389, 397, 399, 403, 409, 411, 417, 422, 424, 426	Minor	Markdown line-length violations	markdownlint reports MD013 on all listed prose/list lines. Several paragraphs exceed 150 characters; line 65 is 301 characters.	Wrap long prose/list lines in TECHNICAL-TEARDOWN.md to the repository markdown style target, preserving code fences and Mermaid blocks unchanged.
TECHNICAL-TEARDOWN.md	81, 318	Minor	Consecutive blank lines	markdownlint reports MD012 at both locations.	Remove duplicate blank lines in TECHNICAL-TEARDOWN.md while preserving one blank line around headings and fenced blocks.
docs/README.md, README.md	n/a	Minor	New root documentation is undiscoverable from the documentation map	The PR adds a new root-level technical teardown, but neither the canonical/transitional/historical docs map nor the root README documentation list links to it. Reviewers/users will only find it by filename.	Add TECHNICAL-TEARDOWN.md to the appropriate section of docs/README.md and, if it is intended as a user-visible reference, add it to the root README documentation list with a one-line classification.

Positive confirmation

All 12 Mermaid blocks render with mmdc; the original Mermaid parse errors are resolved. The remaining issues are documentation quality/style and discoverability, not Mermaid syntax.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 49d8516b96

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Demote section headings below the document title

With the document title already using the sole top-level heading, these additional # headings make the teardown violate markdownlint's MD025 single-H1 rule in environments that lint docs; the same pattern repeats for the other major sections, so demoting the section headings and their subsections preserves a valid hierarchy without changing content.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Wrap prose lines to satisfy markdown linting

This prose line is over 300 characters, and the added document contains many similar long prose/list lines; in markdownlint contexts this trips MD013 and makes the new teardown fail style checks even though the Mermaid syntax is valid. Please wrap the prose/list text while leaving fenced Mermaid blocks unchanged.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove the duplicate blank line before the next section

There are two blank lines between the Mermaid fence and the next heading here, which markdownlint reports as MD012 for this new document. Keeping a single separator line preserves readability and avoids the lint warning.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Link the teardown from the documentation index

This change adds a new root-level reference document, but the repository's documentation entry points (README.md and docs/README.md) do not link to it, so readers starting from the canonical docs map will not discover it. Please add it to the appropriate docs map section, and to the root README documentation list if it is meant to be user-visible.

Useful? React with 👍 / 👎.

[flyingrobots]

Closing this PR as superseded by #324. #324 now carries the current zero-to-hero technical teardown work, includes the README/docs index links, validates the Mermaid diagrams, and has already absorbed the Mermaid/rendering/readability cleanup. Keeping this older draft open would duplicate the same file path and review surface.