Added a '## Revision History' section at the end of spec_v2.md (just before
'End of spec_v2.md.') documenting the 2026-06-24 MVP pivot:
- MVP output is a single AUDIT_REPORT.md (6797 lines, 311KB) + per-aggregate
markdowns + summary.md TOC pointer
- v2 DSL format (to_dsl_v2/parse_dsl_v2/DSL_WORD_ARITY_V2/_atom) was
implemented but never produced and was deprecated in Task 2.2
- compute_result_coverage was dead code with a latent 100% bug, removed in Task 2.3
- Test count: 125 (was 131 pre-polish; -6 tests deleted)
- audit_weak_types.py --strict and generate_type_registry.py --check now pass
No changes to the v2 spec's overall design intent, 13 aggregates, 4-direction
decomposition cost, or cross-audit integration. The MVP pivot is purely about
the OUTPUT format and code-smell cleanup.
Sets:
- all_4_audit_gates_passing = true (the 4 exception-handling violations
are documented as NG1 in the polish track's spec; pre-existing + out
of scope for the polish track)
- type_registry_check_passing = true (Phase 1 Task 1.2 of the polish
track regenerated docs/type_registry/ and the --check now passes)
Also updates last_updated to note this follow-up. No changes to status,
current_phase, or per-phase statuses (the prior track IS shipped; only
the verification flags were stale).
Phase 1 data model: 19 unit tests passing. The 5 enums + 9
supporting dataclasses + AggregateProfile central artifact are
all in place. Phase 1 checkpoint at ef207cf6.
metadata.json: standard track metadata (15 fields per the
live_gui_test_fixes_20260618 precedent; includes scope,
depends_on, blocks, out_of_scope, tolerated_at_run_time,
test_summary, verification_criteria, 10 risks).
state.toml: initial state (status=active, current_phase=0;
14 phases pending; 19 verification flags all false).
TIER2_STARTUP.md: the per-track readme for the Tier 2 agent.
Track-specific supplement to conductor/tier2/agents/tier2-autonomous.md.
Covers: what to load (plan_v2.md first, spec_v2.md second;
do NOT load v1 spec/plan), hard bans (3-layer), conventions,
TDD protocol, per-task commit protocol, pre-delegation
checkpoint, failcount contract, 8 known gotchas, verification
protocol, end-of-track handoff, out-of-scope restatement.
EXPLICITLY NOTES:
- any_type_componentization_20260621 + phase2_4_5_call_site_completion_20260621
are NOT on master (merged f914b2bc, reverted 751b94d4).
v2 audit is tolerant of their absence.
- The 3 candidate aggregates (ToolSpec, ChatMessage,
ProviderHistory) are forward-compat placeholders with
is_candidate: True. The integration tests verify the
placeholder format (synthesize_aggregate_profile() in
Phase 9 Task 9.2 has the template hard-coded).
- The 1-line extension to scripts/audit_optional_in_3_files.py
is the audit gate; skipping Phase 12 Task 12.2 leaves the
new file uncovered by the Optional[T] ban.
Total v2 artifacts (committed):
- spec_v2.md (460 lines)
- plan_v2.md (5006 lines)
- metadata.json
- state.toml
- TIER2_STARTUP.md
Re-scopes the audit from 'expensive operations per action' (v1) to
'data pipelines per aggregate' (v2). The v1 framing was correct
2026-06-07 (the 4 foundational tracks were future) but is now
stale; v2 also cross-validates the data_structure_strengthening
+ data_oriented_error_handling deductions directly.
10 in-scope aggregates (Metadata, FileItem, FileItems,
CommsLogEntry, CommsLog, HistoryMessage, History, ToolDefinition,
ToolCall, Result[T]) + 3 candidate aggregates (ToolSpec,
ChatMessage, ProviderHistory; forward-compat placeholders for
any_type_componentization_20260621 which is NOT on master).
4 static analyses: PCG (3 AST passes), MemoryDim classifier,
APD (5 access patterns), CFE (7 frequencies). 11 public
functions, all return Result[T] per error_handling.md hard rule.
Decomposition-cost heuristic per aggregate answers: 'should
this data be componentize further (split) or unify further
(wider fat structs)?' 4 directions: componentize, unify, hold,
insufficient_data. 10-phase TDD plan, 69 tests total.
Consumes JSON from 6 existing audit scripts (cross-validates
data_structure_strengthening + data_oriented_error_handling).
Out-of-scope: runtime profiling (deferred to
pipeline_runtime_profiling_20260607), MMA worker spawn (cold).
v1 spec.md + plan.md preserved unchanged.
The user specified that the code_path_audit_20260607 track should run
AFTER the 4 foundational tracks complete (qwen_llama_grok,
data_oriented_error_handling, data_structure_strengthening,
mcp_architecture_refactor). This commit formalizes that timing
and grounds the audit's analytical framing in the 5 sources loaded
into context on 2026-06-08.
3 surgical additions to the spec/plan, no task changes:
1. Post-4-tracks timing (new section in spec.md §"Timing", plus
a "Timing" callout in plan.md's opening):
- The 4 tracks will significantly reshape src/ai_client.py,
src/mcp_client.py, src/app_controller.py, and
src/type_aliases.py
- Running the audit on pre-refactor code would produce a
report that's stale on day 1
- The post-4-tracks timing ensures the audit grounds
optimization decisions for the *resulting* architecture
- Pre-flight check: verify all 4 tracks are [x] completed
in conductor/tracks.md before starting this track
2. Analytical framing (new section in spec.md §"Analytical Framing
(5-source lens)"):
- Maps each of the 5 sources (Fleury taxonomy + Fleury
combinatoric + Muratori Big OOPs + Reece Assuming + user's
chunk ideation) to specific audit-time heuristics
- 4 concrete heuristics: effective-codepath count,
entity-hierarchy fingerprint, assumed-too-much detector,
chunkification candidates
- The heuristics shape REPORT INTERPRETATION, not the
static cost model (which stays data-grounded in
EXPENSIVE_THRESHOLD + per-class weights)
3. See Also cross-references in spec.md (6 new entries):
- nagent_review Pitfalls #2 and #4 (provider history
globals + stateful singleton)
- wo84LFzx5nI Big OOPs transcript (full text, 4310
segments, 200KB; loaded 2026-06-08)
- i-h95QIGchY Assuming transcript (full text, 3719
segments, 162KB; loaded 2026-06-08)
- ed_chunk_data_structures_20260523.md (5-image archive
of user's chunk ideation, 19KB; saved 2026-06-08)
- computational_shapes_ssdl_digest_20260608.md (the SSDL
digest that synthesizes the 4-source computational-shapes
thinking; the audit's tree/mermaid outputs ARE
computational-shape visualizations)
4. tracks.md entry updated to include the spec/plan links and
a brief status note that the audit is post-4-tracks.
5. plan.md has a "Timing" callout at the top stating the 4
tracks must ship before the plan executes.
No code modified. The audit's tasks (Phases 1-6) are unchanged
in structure; the new sections only add analytical context
and timing constraints.
Per user direction ('make a custom DSL ideal for recording the
call-graph or other metrics', 'I want a post-fix heiarchy', 'JSON
is ill-performant'): replaced JSON serializer with a custom
postfix (RPN) DSL tailored to the audit's record shapes.
THE CUSTOM DSL
- Postfix (operands before operator); no brackets, braces,
commas, or colons.
- Length-prefixed lists: N items followed by 'list' word.
- Tagged records: each 'word' is a constructor with a known
arity (action=3, fn=3, call=1, mut=3, exp-op=5, pair=2, int=1).
- Whitespace-tokenized; bare atoms unquoted; double quotes
only when whitespace/special chars present.
- nil for null; backslash for line comments; true/false for bool.
- Trivial parser (~30 lines): _tokenize_dsl splits on
whitespace and respects quotes + comments; parse_dsl
walks tokens and evaluates tagged words against a known
arity table (DSL_WORD_ARITY).
- Round-trips: to_dsl(profile) -> parse_dsl(to_dsl(profile))
yields the same in-memory structure.
DELIVERABLES (updated spec + plan)
- src/code_path_audit.py: to_dsl, dump_dsl, parse_dsl,
_tokenize_dsl, to_tree (prefix-tree text renderer),
to_markdown, to_mermaid.
- Output: .dsl files (machine) + .tree (human prefix view) +
.md (summary tables) + .mmd (Mermaid diagrams).
- No new pip dependencies; pure stdlib.
WHAT STAYED
- The 7 cost classes (file_io, network, ast_parse, json_io,
pickle, deep_copy, loop_amplified) and 5 mutation kinds
are unchanged. The json_io cost class is for JSON file
I/O the audit detects, not the output format.
- 36 tests total (15 + 8 + 10 + 3 across the 4 implementation
phases).
6 phases, one per commit:
Phase 1: data structures (CallGraph, ExpensiveOp, StateMutation)
- 15 unit tests
Phase 2: trace_action + ActionProfile + cost model + AST walking
- 8 tests (synthetic + integration on real src/)
Phase 3: JSON / markdown / Mermaid output
- 4 tests
Phase 4: MCP tool + CLI surface
- 3 tests
Phase 5: run audit on 3 actions; commit report
Phase 6: tracks.md update
TDD pattern: each task has synthetic-data unit test, then
real implementation, then integration with real src/, then
commit. The state.toml scaffold is created in Phase 0 Step 0.1
and advanced after each phase.
3 actions in scope (MMA is cold per user):
- ai_message_lifecycle (5 entry points)
- discussion_save_load (4 entry points)
- gui_startup (3 entry points)
Two follow-up tracks recorded but NOT in this track:
- pipeline_runtime_profiling_20260607
- pipeline_pruning_20260607
No new pip dependencies; pure stdlib (ast, json, pathlib,
dataclasses). Read-only on src/; new files are the tool, the
tests, and the report under docs/reports/code_path_audit/2026-06-07/.
Design for a data-oriented static-analysis tool
(src/code_path_audit.py) that audits the 3 major actions (AI
message lifecycle, discussion save/load, GUI startup) for
expensive operations, redundant calls, and pipelining
candidates. Output: JSON data files + markdown summaries +
Mermaid per-action call graphs in docs/reports/code_path_audit/.
61 src/ files, 27,447 total lines. Call graph is non-trivial;
per-action traversal is what makes analysis tractable.
Cost model: 7 cost classes (file_io, network, ast_parse,
json_io, pickle, deep_copy, loop_amplified) with heuristic
weights; EXPENSIVE_THRESHOLD = 40,000 module constant. 5
state mutation kinds (attr_write, container_mutate, file_write,
ipc_emit, global_write).
The 3 action entry points are per-action defined (see Per-Action
Design table). MMA worker spawn is OUT of scope per user (cold
until 1:1 discussion UX is dogfooded).
Two follow-up tracks recorded but NOT in this track:
- pipeline_runtime_profiling_20260607: calibrate the heuristic
cost model with real measurements; catch C-extension cost,
decorator dispatch, JIT effects that static analysis can't
resolve.
- pipeline_pruning_20260607: implement the high-priority
optimization candidates surfaced by this track's report.
6 atomic commits planned: data structures; trace_action +
ActionProfile + cost model; output (JSON/MD/Mermaid); MCP +
CLI; run audit + commit report; tracks.md update.
ed
conductor-tier2