---
phase: 07-verification-and-closure
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - TECH-DEBT.md
autonomous: true
requirements:
  - VERIFY-SC7

must_haves:
  truths:
    - "TECH-DEBT.md at repo root catalogs all accepted design decisions with origin citations"
    - "TECH-DEBT.md lists all v0.2 deferred items with requirement IDs"
    - "TECH-DEBT.md documents known architectural limitations with mitigation notes"
    - "TECH-DEBT.md documents test coverage gaps with justifications"
  artifacts:
    - path: "TECH-DEBT.md"
      provides: "Complete tech debt and deferred items inventory for v0.2 planning"
      contains: "Accepted Design Decisions"
  key_links:
    - from: "TECH-DEBT.md"
      to: ".planning/v1.0-MILESTONE-AUDIT.md"
      via: "Every item traces back to audit tech_debt section"
      pattern: "Origin:"
---

<objective>
Create TECH-DEBT.md documenting all accepted design decisions, deferred v0.2 items, known architectural limitations, and test coverage gaps.

Purpose: Provide a single reference for v0.2 planning so that future work does not need to re-discover trade-offs made during v0.1. This is the primary deliverable of Phase 7 that Claude can produce autonomously.

Output: `TECH-DEBT.md` at repo root
</objective>

<execution_context>
@/Users/paul/.claude/get-shit-done/workflows/execute-plan.md
@/Users/paul/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md
@.planning/v1.0-MILESTONE-AUDIT.md
@.planning/phases/07-verification-and-closure/07-RESEARCH.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create TECH-DEBT.md with complete tech debt inventory</name>
  <files>TECH-DEBT.md</files>
  <action>
Create `TECH-DEBT.md` at the repo root (alongside MAINTAINER.md). Use the structure from the research document, populated with real content from the following sources:

**Section 1: Accepted Design Decisions** — Extract from STATE.md decisions and milestone audit. Include at minimum:
- Catalog table name: `semantic_layer._definitions` vs `_semantic_views_catalog` (Phase 2 audit item, accepted)
- Sidecar file persistence: plain file I/O because DuckDB holds execution locks during scalar invoke (Phase 2, decision [02-04]). Action: replace with `pragma_query_t` in v0.2 C++ shim.
- Native EXPLAIN deferred to v0.2: `explain_semantic_view()` function provides expanded SQL inspection; native `EXPLAIN FROM semantic_query(...)` requires C++ shim (Phase 4, QUERY-V2-03)
- All output columns are VARCHAR: decision [04-03] varchar-output-columns. Consumers must cast numeric columns. v0.2 may restore typed output.
- Manual FFI entrypoint: replaced `#[duckdb_entrypoint_c_api]` macro with hand-written FFI entrypoint to capture raw `duckdb_database` handle (Phase 4, decision [04-01])
- ON-clause substring matching: sufficient heuristic for v0.1 join dependency detection; may need full SQL parsing in v0.2 (Phase 3, decision [03-02])

For each decision, include: Origin (phase + decision ID), Decision (what was decided and why), Action (what to do in v0.2, or "None needed").

**Section 2: Deferred to v0.2** — Pull from REQUIREMENTS.md v0.2 section:
| ID | Description | Reason |
| QUERY-V2-01 | Native CREATE SEMANTIC VIEW DDL | Requires C++ shim for parser hooks |
| QUERY-V2-02 | Time dimensions with granularity coarsening | Scoped out of v0.1 |
| QUERY-V2-03 | Native EXPLAIN interception | Requires C++ shim for EXPLAIN hook |
| DIST-V2-01 | Community extension registry publishing | Requires upstream PR |
| DIST-V2-02 | Real-world TPC-H demo | Documentation deliverable |

Also add: Sidecar replacement with pragma_query_t (from accepted decisions).

**Section 3: Known Architectural Limitations** — From milestone audit integration issues:
- FFI execution layer not fuzz-covered (`execute_sql_raw`, `read_varchar_from_vector` in `table_function.rs`)
- All output columns are VARCHAR (decision [04-03])
- DuckDB version pinning (`= 1.4.4`) — ABI not stable across minor versions
- Unqualified column names required in expressions (CTE flattens all tables into `_base` namespace)

For each: What, Why, Impact, Mitigation.

**Section 4: Test Coverage Gaps** — From milestone audit:
- Iceberg test uses Python instead of SQLLogicTest (reason: runner cannot install extensions)
- FFI execution layer not fuzz-testable standalone (reason: loadable-extension stubs only available at runtime)
- Sandbox test portability (3 sidecar tests require temp_dir pattern — resolved in Phase 6)

**Metadata section at the bottom:** Date, milestone version, link to audit report.

Do NOT use emojis. Use clean markdown. Keep each item concise (3-5 sentences). Every item must cite its origin.
  </action>
  <verify>
    <automated>test -f TECH-DEBT.md && grep -q "Accepted Design Decisions" TECH-DEBT.md && grep -q "Deferred to v0.2" TECH-DEBT.md && grep -q "Known Architectural Limitations" TECH-DEBT.md && grep -q "Test Coverage Gaps" TECH-DEBT.md && echo "PASS"</automated>
  </verify>
  <done>TECH-DEBT.md exists at repo root with all four sections populated. Every item cites its origin (phase/decision ID or audit item). v0.2 deferred items table includes all 5 REQUIREMENTS.md entries plus sidecar replacement.</done>
</task>

</tasks>

<verification>
1. `TECH-DEBT.md` exists at repo root
2. Contains four sections: Accepted Design Decisions, Deferred to v0.2, Known Architectural Limitations, Test Coverage Gaps
3. Every item has an origin citation (phase number, decision ID, audit item, or requirement ID)
4. v0.2 deferred table has at least 6 rows (5 from REQUIREMENTS.md + sidecar)
5. No placeholder text or TODOs remain
</verification>

<success_criteria>
- TECH-DEBT.md is comprehensive enough to serve as the sole input for v0.2 milestone planning
- A reader unfamiliar with v0.1 can understand each trade-off without consulting other project files
</success_criteria>

<output>
After completion, create `.planning/phases/07-verification-and-closure/07-01-SUMMARY.md`
</output>
