docs: align roadmap and backlog with architecture audit

[carlos-alm]

Summary

• Add Phase 4 (Resolution Accuracy) with 6 sub-sections: dead role sub-categories, receiver type tracking, interface/trait implementation edges, precision/recall benchmarks, package.json exports resolution, monorepo workspace resolution
• Reorder phases: TypeScript Migration (Phase 5) before Native Acceleration (Phase 6), per audit recommendation
• Remove Web UI from Phase 12 (Advanced Features)
• Add Section 5.9 (Kill List): MI formula removal, Halstead scoping, graph model migration, WASM skip
• Add Sections 7.10-7.11: Confidence annotations on query output, shell completion
• Add dual-engine architectural note to Phase 6
• Backlog: mark ID 45 done, promote IDs 73/74/80 to roadmap, add Tier 1j with 10 audit-identified items (IDs 87-96)

Source

Changes derived from architectural audit (v3.1.4).

Test plan

• Verify all internal anchor links in ROADMAP.md resolve correctly
• Verify phase numbering is sequential and consistent throughout
• Verify backlog IDs don't duplicate existing entries
• Verify cross-references between ROADMAP and BACKLOG are consistent

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review: docs: align roadmap and backlog with architecture audit

Todo List:

• Read modified documentation files
• Read referenced architecture audit document
• Apply 5-phase review process
• Provide comprehensive review feedback

Root Cause Analysis

Problem Being Solved: Aligning the project roadmap and backlog with findings from an architecture audit (v3.1.4, dated 2026-03-16) to ensure documentation reflects current strategic priorities and identified gaps.

Why This Approach: The changes systematically incorporate audit findings by: (1) reordering phases to prioritize Resolution Accuracy before Native Acceleration, (2) adding Phase 4 with 6 sub-sections addressing accuracy gaps, (3) removing Web UI from advanced features, (4) promoting backlog items to roadmap based on audit recommendations, and (5) adding audit-identified items to the backlog.

Risk Assessment: This is a documentation-only change with no code modification risk. The main risk is documentation consistency - anchor links, cross-references, and phase numbering need to be correct.

Phase 1: Configuration Change Detection ✅

No configuration changes detected - this PR only modifies documentation files.

Phase 2: Test Integrity ✅

No test changes - documentation-only PR with no risk to test integrity.

Phase 3: Code Quality ✅

Documentation-specific quality checks:

✅ Phase numbering consistency: Updated from 11 to 12 phases correctly throughout
✅ Cross-reference integrity: Backlog item promotions (IDs 73, 74, 80) properly marked as "PROMOTED"
✅ New content structure: Phase 4 sections well-organized with 6 sub-sections
✅ Anchor link compatibility: Internal links should resolve correctly post-change
✅ Kill list additions: Section 5.9 properly added with specific items to remove

Minor concerns:

• The architecture audit document referenced in the PR description (docs/architecture/ARCHITECTURE_AUDIT_v3.1.4_2026-03-16.md) does not exist in the repository, making it impossible to verify the changes align with actual audit findings
• Some promoted items (IDs 73, 74, 80) maintain their original descriptions in the backlog, which could create confusion about whether they're duplicated

Phase 4: Backlog Compliance

Zero-dep: ✓ — No new runtime dependencies, pure documentation changes

Foundation-aligned: ✓ — Changes align with FOUNDATION.md principles:

• Preserves local-first approach (P1, P4)
• Maintains embeddable-first design (P5)
• Focuses on planning/developing/refactoring over CI/CD (P8)
• No violations of core principles

Problem-fit: 5 — Directly addresses core problem:

• Reordering phases prioritizes accuracy improvements that prevent hallucinated dependencies
• New Phase 4 sections target call graph completeness (receiver tracking, interface implementation)
• Resolution accuracy improvements directly reduce "missed blast radius" problem
• Confidence annotations make blind spots visible to agents

Breaking: No — Documentation changes are non-breaking

Tier: 1 (zero-dep ✓ + foundation-aligned ✓)

Phase 5: Documentation Specific Checks

Content accuracy concerns:

1. Missing audit document: The referenced ARCHITECTURE_AUDIT_v3.1.4_2026-03-16.md doesn't exist, making it impossible to verify alignment
2. Dependency graph complexity: The ASCII dependency graph is quite complex and may be hard to maintain as phases evolve

Positive aspects:

1. Clear rationale: Each change includes explanation of why it was made
2. Systematic approach: Backlog items properly promoted/demoted with clear tracking
3. Comprehensive scope: Covers roadmap reordering, new sections, backlog updates, and kill list additions

Critical Concerns

None - this is a well-structured documentation update.

Minor Recommendations

1. Consider adding the referenced audit document to the repository for transparency
2. Verify all internal anchor links resolve correctly after the restructuring
3. Consider adding a changelog section documenting these major structural changes

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: This is a thoughtful documentation update that improves project planning alignment. The changes are well-structured, systematically implemented, and directly support the tool's core value proposition. While the missing audit document prevents full verification, the changes themselves are internally consistent and beneficial.

The PR successfully addresses the stated goal of aligning roadmap priorities with architectural audit findings, with clear benefits for development planning and stakeholder communication.

[greptile-apps]

Greptile Summary

This PR aligns the project roadmap and backlog with the v3.1.4 architecture audit, and ships two complementary code changes that enable old native binaries (pre-type-map support) to fall back gracefully to the JS edge builder.

Documentation changes:

• Inserts Phase 4 (Resolution Accuracy) and reorders TypeScript Migration ahead of Native Acceleration, bumping all later phases by one slot; all Depends on cross-references and the test-criteria table have been updated to match
• Removes the Web UI section (old Phase 11.1) and adds Phases 7.10 (Confidence Annotations) and 7.11 (Shell Completion)
• Adds ADR-001 documenting the settled dual-engine architecture and its known incremental-rebuild analysis-data-loss issue
• Adds Tier 1j to the backlog (IDs 87–96) with PROMOTED annotations for items already committed to the roadmap

Code changes (old-native-binary compatibility):

• patchNativeResult now initialises typeMap to [] for binaries that predate the type-map feature
• parseFileAuto / parseFilesAuto backfill typeMap via WASM (parallel Promise.all in the bulk path) and set _typeMapBackfilled = true on affected symbols
• build-edges.js checks _typeMapBackfilled across all symbols before deciding native vs JS call-edge builder

Issue found:

• The backfill guard if (extracted?.symbols?.typeMap) is truthy for empty arrays and empty Maps. When the WASM extractor returns no type annotations for a file, _typeMapBackfilled is still set, which causes build-edges.js to fall back to the JS edge builder for the entire build — not just the affected file. The same guard appears in both parseFileAuto and parseFilesAuto; both should check for a non-empty collection before setting the flag.

Confidence Score: 3/5

• Safe to merge for the docs-only portions; the code changes carry a logic bug that can silently degrade call-edge quality across the entire build for any user with an old native binary whose files have no WASM-detectable types.
• The documentation restructure is thorough and the previously flagged issues (PROMOTED annotations, Tier 1j header, Phase 4.6/12.2 scope) are resolved. The code logic for the happy path (old native binary + WASM finds types) is correct. However, the falsy-empty guard on the backfilled typeMap means a file with zero WASM type annotations silently sets _typeMapBackfilled=true, forcing the JS edge builder for all files — a build-wide quality regression that would be invisible in CI unless precision/recall benchmarks are exercised on a codebase that mixes typed and untyped files.
• src/domain/parser.js — the truthy-empty typeMap guard appears in both parseFileAuto and parseFilesAuto and needs the same fix in both locations.

Important Files Changed

Filename	Overview
src/domain/parser.js	Adds WASM typeMap backfill for old native binaries in both parseFileAuto and parseFilesAuto (using Promise.all for parallel I/O). Logic issue: truthy-empty guard on extracted.symbols.typeMap means files with no WASM type annotations still set _typeMapBackfilled = true, silently forcing the JS edge builder for all files in the build.
src/domain/graph/builder/stages/build-edges.js	Adds a typeMapBackfilled guard before using the native call-edge builder — if any symbol has _typeMapBackfilled set, all files fall back to the JS builder. The logic is sound given that the old native edge builder can't consume WASM-format typeMaps, though its scope-of-impact depends on the parser.js backfill flag being set correctly.
docs/architecture/decisions/001-dual-engine-architecture.md	New ADR documenting the settled dual-engine (Rust native + JS/WASM) architecture, its rationale, trade-offs, and known issues (analysis data loss on native incremental rebuilds). Well-structured and internally consistent.
docs/roadmap/ROADMAP.md	Major restructure: inserts Phase 4 (Resolution Accuracy) and Phase 5 (TypeScript Migration), bumps all subsequent phases by 1-2 slots, removes Web UI (old Phase 11.1), adds Phases 7.10/7.11 and SARIF early-delivery note. All cross-reference "Depends on" lines updated to new numbering; test-criteria table aligned. Previously flagged overlaps and missing scope notes have been addressed.
docs/roadmap/BACKLOG.md	Marks ID 45 done, promotes IDs 73/74/80 with strikethrough+PROMOTED annotations, adds Tier 1j (IDs 87–96). Previously flagged issues — missing PROMOTED annotations on 87/89/90/91/93 and the incorrect "All are zero-dep" claim in the Tier 1j header — are addressed per thread replies.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[parseFilesAuto or parseFileAuto] --> B[patchNativeResult]
    B --> C{typeMap empty AND calls exist?}
    C -- No --> G[Return patched, no flag set]
    C -- Yes --> D[wasmExtractSymbols]
    D --> E{extracted.symbols.typeMap truthy?}
    E -- empty array or Map = still TRUE --> H[Set typeMap to empty Map\n_typeMapBackfilled = true BUG]
    E -- non-empty Map or array --> F[Set typeMap to Map\n_typeMapBackfilled = true OK]
    E -- null or undefined --> G
    F --> I[build-edges.js]
    H --> I
    G --> I
    I --> J{any symbol has _typeMapBackfilled?}
    J -- Yes --> K[buildCallEdgesJS for ALL files]
    J -- No --> L[buildCallEdgesNative faster and more accurate]

Loading

_{Last reviewed commit: "fix: reconcile Phase..."}

[greptile-apps]

Tier 1j items duplicated in ROADMAP without "PROMOTED" annotation

Five items newly added to Tier 1j are simultaneously added to the ROADMAP, but unlike IDs 73, 74, and 80 (which were pre-existing backlog items correctly struck-through and annotated with **PROMOTED**), the new overlapping entries have no cross-reference:

Backlog ID	Backlog Title	ROADMAP section
87	Confidence annotations on query output	Phase 7.10
89	Call resolution precision/recall benchmark suite	Phase 4.4
90	package.json exports field resolution	Phase 4.5
91	Monorepo workspace resolution	Phase 4.6
93	Shell completion for CLI	Phase 7.11

Without the same strikethrough + **PROMOTED** treatment applied to 73/74/80, readers have no way to know these items are already committed roadmap phases. The PR test plan explicitly calls out "verify cross-references between ROADMAP and BACKLOG are consistent" — this is the exact gap. Each of these rows should receive the same annotation pattern, e.g.:

| 87 | ~~Confidence annotations on query output~~ | ... | **PROMOTED** — Moved to ROADMAP Phase 7.10 |

[carlos-alm]

Fixed — added PROMOTED annotations with strikethrough titles and roadmap phase cross-references to backlog IDs 87, 89, 90, 91, and 93, matching the pattern used for IDs 73/74/80.

[greptile-apps]

Tier 1j header incorrectly claims all items are zero-dep

The section header states: "All are zero-dep and foundation-aligned."

However, two entries in the table explicitly carry ✗ in the Zero-dep column:

• ID 92 (Auto-generate MCP tool schemas from types) — ✗ zero-dep (requires zod or typebox)
• ID 94 (VS Code extension) — ✗ zero-dep (requires VS Code extension APIs and bundler tooling)

The header should be corrected to reflect that the items are mostly zero-dep, or the qualifier should be removed entirely to avoid misleading prioritization reviewers who rely on the tier descriptions to pre-filter candidates.

Suggested change

	### Tier 1j — Audit-identified gaps (from Architecture Audit v3.1.4)
	Items identified by the [architectural audit](../../docs/architecture/ARCHITECTURE_AUDIT_v3.1.4_2026-03-16.md) that don't fit existing tiers. All are zero-dep and foundation-aligned.
	Items identified by the [architectural audit](../../docs/architecture/ARCHITECTURE_AUDIT_v3.1.4_2026-03-16.md) that don't fit existing tiers. Most are zero-dep and foundation-aligned (see individual rows for exceptions).

[carlos-alm]

Fixed — changed the Tier 1j header from "All are zero-dep and foundation-aligned" to "Most are zero-dep and foundation-aligned (see individual rows for exceptions)" to account for IDs 92 and 94.

[greptile-apps]

Phase 4.6 overlaps substantially with the existing Phase 12.2

Phase 4.6 (Monorepo Workspace Resolution) describes:

Detect workspace root and enumerate workspace packages. Resolve internal package imports to actual source files within the monorepo.

Phase 12.2 (Cross-Repository Support / Monorepo, which predates this PR) describes:

Detect workspace root (package.json workspaces, pnpm-workspace.yaml, lerna.json). Resolve internal package imports (e.g., @myorg/utils) to actual source files.

Both target the same workspace detection and internal import resolution mechanics. The distinction currently implied (4.6 = import-resolution accuracy, 12.2 = full cross-package graph support with a package column and --workspace flag) is not clearly stated in either section. A reader or implementer could reasonably implement 4.6 and then find the 12.2 scope already covered, or vice versa.

It's worth adding a note to 4.6 scoping it explicitly as the resolution layer only and deferring the full monorepo graph (package node type, cross-package edges, build --workspace) to 12.2 to avoid duplicating work.

[carlos-alm]

Fixed — added a scope note to Phase 4.6: "This phase covers the resolution layer only — detecting workspace packages and resolving internal imports to source files. Full monorepo graph support (package node type, cross-package edges, build --workspace flag) is deferred to Phase 12.2." Also added the same scoping note to backlog ID 91's PROMOTED annotation.

[carlos-alm]

@greptileai

[greptile-apps]

Synchronous fs.readFileSync blocks event loop in async context

parseFilesAuto is an async function that already uses await createParsers() just above this loop. Re-reading files synchronously inside the sequential for…of loop will block the Node.js event loop once per file. On a large codebase with an old native binary where many files need the WASM typeMap backfill, this adds a noticeable serial I/O stall.

The reads can be issued in parallel using fs.promises.readFile and Promise.all, and the WASM extraction can then be batched:

if (needsTypeMap.length > 0) {
  const parsers = await createParsers();
  await Promise.all(
    needsTypeMap.map(async ({ filePath, relPath }) => {
      try {
        const code = await fs.promises.readFile(filePath, 'utf-8');
        const extracted = wasmExtractSymbols(parsers, filePath, code);
        if (extracted?.symbols?.typeMap) {
          const symbols = result.get(relPath);
          symbols.typeMap =
            extracted.symbols.typeMap instanceof Map
              ? extracted.symbols.typeMap
              : new Map(extracted.symbols.typeMap.map((e) => [e.name, e.typeName]));
          symbols._typeMapBackfilled = true;
        }
      } catch {
        /* skip — typeMap is a best-effort backfill */
      }
    }),
  );
}

Note: wasmExtractSymbols is synchronous (WASM), so the CPU work still serialises, but the I/O waiting does not.

[carlos-alm]

Fixed — replaced the synchronous \ loop with \ inside , so I/O reads are issued in parallel and don't block the event loop. The WASM extraction () is still synchronous by nature, but the file reads no longer serialize.

[carlos-alm]

Addressed the Phase 5.9 / 6.6 contradiction flagged in the Greptile summary: Phase 6.6 now explicitly scopes native acceleration to cognitive and cyclomatic metrics only, with a note that Halstead and MI are governed by the Phase 5.9 Kill List (MI removed entirely, Halstead scoped to imperative code). Native acceleration should only target the metrics that survive the Kill List.

[carlos-alm]

@greptileai