db7d94de886eb8246fac5e2b66d33af2f6e032a1
24
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 conductor-tier2
|
ac0c0cbe73 |
docs(styleguide): add No-Diagnostic-Noise rule to AI-Agent Conventions
One addition to conductor/code_styleguides/python.md §8 "AI-Agent Specific Conventions": - **No diagnostic noise in production code (Added 2026-06-09).** `sys.stderr.write(f"[XYZ_DIAG] ...") lines in src/*.py are technical debt. The right place for one-time investigation output is tests/artifacts/<test>.diag.log (a log file) or a standalone /tmp/diag_<name>.py script. If you must instrument production code, the diag lines are part of the same atomic commit as the fix. - **Test files ARE allowed to be diagnostic.** The rule applies to src/*.py only; tests/test_*.py may use print(..., file=sys.stderr) freely. Markdown only. No code modified. |
||
|
conductor-tier2
|
631c40c9c4 |
docs(workflow): add Process Anti-Patterns section + Isolated-Pass rule
Two additions to conductor/workflow.md §"Known Pitfalls": 1. **Isolated-Pass Verification Fallacy (Added 2026-06-09)** — the rule that a test passing in isolation but failing in batch is FAILING. The only verification that matters for live_gui tests is the batch run. This is the flip side of the existing "Live_gui Test Fragility (Authoring-Side)" rule. Cross-references that rule. 2. **Process Anti-Patterns (Added 2026-06-09)** — 8-rule summary list, with cross-reference to AGENTS.md for the full ruleset. The 8 patterns are: Deduction Loop, Report-Instead-of-Fix, Scope-Creep Track-Doc, Inherited-Cruft, Diagnostic Noise in Production, Premature Surrender, Verbose Commit Message, Isolated-Pass Verification Fallacy. Markdown only. No code modified. Cross-references AGENTS.md (the load-bearing agent doc) for the full text of each pattern. |
||
|
conductor-tier2
|
d7dc1e3b90 |
docs(edit-workflow): fix set_file_slice rule + add contract-change check
Three surgical fixes to conductor/edit_workflow.md:
1. **§2 "Verify Before Editing"** — removed the leftover
`git checkout -- src/gui_2.py` instruction. The user's
commit `4eba059e unfuck edit workflow` removed most of
the git checkout nuke instructions but missed §2. The
revised §2 now says: read the contract (function signature,
yield shape, return type) before editing, and DO NOT use
`git checkout` to revert. Ask the user.
2. **§3 "Reading Before Editing"** — added the line-number
offset check. `set_file_slice` uses 1-indexed inclusive
`start_line`/`end_line`; off-by-one is a common silent
failure. The rule is now: confirm the exact line range
with `get_file_slice` first.
3. **§8 "set_file_slice IS Valid for Multi-Line Content
(Revised 2026-06-09)"** — replaced the wrong rule
("Do not use set_file_slice for multi-line content") with
the correct rule: set_file_slice IS valid for 3-10 line
surgical edits, with a tool-selection guide (which tool
for which job), a mandatory contract-change check
(search for callers of the symbol being changed; update
all callers in the same atomic commit if the public
interface changes), and a mandatory whitespace-and-EOL
rule (preserve line ending, indentation, and line count).
4. **§9 "No Diagnostic Noise in Production Code
(Added 2026-06-09)"** — new section. Diag stderr goes
to log files or /tmp scripts, NOT src/*.py. If you must
add diag lines to production code, they are part of the
same atomic commit as the fix — they do not live
uncommitted in the working tree.
5. **"If set_file_slice produces wrong indentation"** —
new handler in the Step-by-Step Workflow. Tells the
agent: you wrote the wrong indent; the tool did what
you asked; re-read the file with get_file_slice; do
NOT use git checkout to revert.
These are the rule corrections the user demanded after
the Tier-2's bad set_file_slice + git nuke + diag-noise
behavior. Markdown only. No code modified.
|
||
|
conductor-tier2
|
113e68fe18 |
docs(agents): add Process Anti-Patterns section + revise set_file_slice rule
The user explicitly called out the bad patterns the agents (Tier-2 and the parent session's Tier-1) have been exhibiting. This commit updates AGENTS.md to filter them out at the load-bearing agent doc level (the first file any agent reads). Three changes: 1. **Revised the `set_file_slice` rule on line 38** of the Critical Anti-Patterns. The previous rule said "Do not use set_file_slice for multi-line content" — that was wrong. `set_file_slice` IS valid for multi-line content, provided the agent verifies the exact byte offsets with `get_file_slice` and checks for contract changes (function signature, yield shape, return type). The full revised rule is in `conductor/edit_workflow.md §8`. 2. **Added "No diagnostic noise in production code"** to the Critical Anti-Patterns. The pattern: agent adds `sys.stderr.write(f"[RAG_DIAG] ...") to src/*.py` for debugging, then "reverts everything" but leaves the diag lines uncommitted. Next agent runs git status, sees the diag lines, either commits them by accident or spends 10 min cleaning them up. The rule: diag goes to log files or /tmp scripts, NOT src/*.py. 3. **Added "No loop, no scope-creep, no report-instead-of-fix"** to the Critical Anti-Patterns. The 200-line status report is a confession, not a fix. The 5-phase "future track" document for a 1-line fix is scope-creep. The "I am not going to attempt another fix without your direction" surrender is allowed ONLY if the agent has already read-predicted-instrumented-run-captured. 4. **Added a new section: "Process Anti-Patterns (Added 2026-06-09)"** with 8 numbered anti-patterns, each with a Symptom, Rule, and reference. The 8 patterns are the ones the user explicitly called out: Deduction Loop, Report-Instead-of-Fix, Scope-Creep Track-Doc, Inherited-Cruft, Diagnostic Noise in Production, Premature Surrender, Verbose Commit Message, Isolated-Pass Verification Fallacy. These are the rules the user is filtering out of LLM training data noise. The full ruleset is the source of truth; AGENTS.md is the load-bearing entry point. No code modified. Markdown only. |
||
|
conductor-tier2
|
adc7ff8029 |
docs(audit): workflow/agent markdown audit with 10 recommendations
User asked: is there anything in our workflow or agent markdown that should be updated or introduced based on this session? This commit is the AUDIT ONLY. No workflow files are modified. The 10 recommendations are not yet applied. User picks which to act on, which to defer, which to discard. docs/reports/workflow_markdown_audit_20260608.md (~370 lines): Read all the workflow/agent markdown in scope (AGENTS.md, CLAUDE.md, GEMINI.md, all 5 .agents/skills/*/SKILL.md, the 4 .agents/agents/*.md, conductor/workflow.md, product.md, product-guidelines.md, tech-stack.md, index.md, tracks.md, edit_workflow.md, the 2 existing code_styleguides/*.md, and the 4 .agents/policies/*.toml + 7 .agents/tools/*.json). Cross-referenced each against the 7 new session artifacts (nagent_review, 3 docs guides, ASCII-sketch workflow, SSDL digest, C11 interop v1+v2, 2 new tracks) and the 3 user-correction patterns (duffle-as-style-ref, v2 request/response model, "only under hard constraint"). The 10 recommendations: 1 (HIGH) Update architecture-fallback with new docs 2 (HIGH) Document ASCII-sketch workflow in workflow.md 3 (HIGH) Document SSDL digest in product-guidelines.md 4 (HIGH) Add user_corrections_log to State.toml Template 5 (MED) Document contingency track pattern 6 (MED) Update Compaction Recovery to reference session_synthesis 7 (MED) Document v1->v2 framing iteration anti-pattern 8 (MED) Document preserve-before-compact archive pattern 9 (LOW) Document MiniMax understand_image for ASCII verification 10 (LOW) Document per-proposal commit chain with git notes 4 HIGH-priority = ~75 min to act on. All 10 = ~2-3 hours. The audit is conservative: it does NOT recommend changing TDD, the per-task commit discipline, the 4-tier MMA model, product.md, tech-stack.md, the existing styleguides, or adding new audit scripts. The session did not surface conflicts with any of these. Meta-pattern: workflow/agent markdown is the theoretical contract; session artifacts are the empirical evidence; when the two diverge, update the theory to match the evidence. This session's evidence (new methodology, new vocabulary, new patterns, new anti-patterns) drives the 10 recommendations. |
||
|
conductor-tier2
|
999fdea467 |
docs(c11-interop): cross-reference SSDL digest in See Also
The SSDL digest (docs/reports/computational_shapes_ssdl_digest_20260608.md, 504 lines, 30KB) is the theoretical foundation for the chunkification pattern. Per the digest's Technique 5 "Assume-away (Xar)" in §2.2 and the "Xar-style chunked arrays" recommendation in §5.2, the chunkification track is a *direct application* of the SSDL's "assume as much as possible" lens (§4). This commit adds the SSDL digest to the See Also of the v1+v2 C11-Python interop assessment (front-matter Cross-references line). The same cross-reference is also being added to: - conductor/tracks/chunkification_optimization_20260608_PLACEHOLDER/spec.md (in a new §6.1 "SSDL alignment" subsection) - conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/spec.md (in §5 Architectural Reference + §6 See Also + a new §2.6 "SSDL cross-reference" section that distinguishes GUI ASCII vocabulary from SSDL vocabulary) No code modified. Cross-reference only. Also: small update to conductor/tracks.md to add the 2 new tracks (manual_ux_validation_20260608_PLACEHOLDER as Active; chunkification_optimization_20260608_PLACEHOLDER as Backlog/Contingency). |
||
|
conductor-tier2
|
5b3c11a0f3 |
conductor(track): manual_ux_validation_20260608_PLACEHOLDER - ASCII-sketch workflow + first-target redesign
The user said (verbatim): "On number 1. I love the idea and definitely
see poitental." This commit creates a full track that promotes the
ASCII-sketch UX ideation workflow
(docs/reports/ascii_sketch_ux_workflow_20260608.md, 340 lines) to
a real track with a concrete first target.
The track complements (does not replace) the existing
manual_ux_validation_20260302 track (which is a general UX review
track; this 2026-06-08 track is *focused* on the ASCII-sketch
workflow specifically).
Files (5 total, ~52KB, 12,000+ words):
- spec.md (186 lines, 9 sections) - track design, 5 open
questions, first target analysis, SSDL cross-reference
- plan.md (~280 lines, 4 phases, 21 tasks) - TDD-style with
WHERE/WHAT/HOW/SAFETY annotations
- metadata.json (~120 lines) - structured metadata, 5 open
questions with defaults, 5 SSDL principles available
- state.toml (~95 lines) - per-task tracking + phase status
- index.md (~50 lines) - track context + related docs
Key design decisions captured:
1. Two distinct vocabularies are conflated at first glance:
- GUI ASCII (the workflow) for panel sketches
- SSDL (computational shapes digest) for internal code sketches
Spec §2.6 makes the distinction explicit; both are useful for
this track (GUI ASCII for Phase 2 design; SSDL for Phase 3
internal refactoring documentation).
2. The 5 open questions from the workflow report (Q1 vocabulary,
Q2 comparison policy, Q3 storage location, Q4 tooling,
Q5 frequency) are documented with sensible defaults in
spec.md §2.1-2.5 and metadata.json. The user can override
any of them; defaults pre-stage the work.
3. First target is src/gui_2.py:3770 render_discussion_entry
(Discussion Hub per-entry panel). Rationale:
- Most-edited surface (every AI/user message)
- User has strong opinions (per nagent_review_20260608 3 rounds
of corrections)
- 23-op matrix A1-A7 is the source of truth
- ImGui layout maps cleanly to ASCII
- SSDL defusing techniques can guide the internal refactoring
4. 4 phases: 1=resolve 5 questions, 2=execute workflow on first
target (1-3 ASCII rounds), 3=implement per design contract
(TDD with 7 test files for A1-A7 operations),
4=document the pattern + propose 5-7 next targets.
Cross-references added throughout:
- docs/reports/computational_shapes_ssdl_digest_20260608.md
(the SSDL digest, with explicit "this is a different vocabulary
for a different purpose" note in spec §2.6)
- docs/reports/ascii_sketch_ux_workflow_20260608.md (the workflow)
- docs/guide_discussions.md (the 23-op matrix A1-A7)
- conductor/tracks/nagent_review_20260608/ (the source of the
user's editable-discussion corrections)
- conductor/tracks/manual_ux_validation_20260302/ (complementary
general UX review track)
- conductor/tracks/chunkification_optimization_20260608_PLACEHOLDER/
(the contingency track; referenced in spec §2.6 SSDL cross-ref)
No code modified. Track is active; Phase 1 (5 user-questions) is
the current phase. User-confirmed worth doing in the prior turn.
|
||
|
conductor-tier2
|
816e9f2f5c |
conductor(track): chunkification_optimization_20260608_PLACEHOLDER - 1-page contingency document
The user's third correction this session changed the framing from "build a stateful C extension" to "wait for a hard constraint, then build a request/response blob pipeline." This commit creates a 1-page contingency document (no plan.md, no implementation) that captures: - The threshold: "only worth it under a hard constraint that no existing Python package can solve" - The shape when activated: subprocess-launch C11 binary with request/response blob wire format (NOT stateful CPython C extension) - The 2 cited candidates (markdown parsing into aggregate markdown, context snapshot processing) are NOT currently bottlenecks per src/aggregate.py:380-454 (pure-Python string concat, zero third-party markdown deps in pyproject.toml:6-27) and src/history.py:1-141 (bounded ~500KB at 100-snapshot capacity, debounced) - The SSDL digest's Technique 5 "Assume-away (Xar)" in §2.2 + "Xar-style chunked arrays" recommendation in §5.2 pre-support this track Files (4 total, 227+ lines of contingency document): - conductor/tracks/chunkification_optimization_20260608_PLACEHOLDER/spec.md - conductor/tracks/chunkification_optimization_20260608_PLACEHOLDER/metadata.json - conductor/tracks/chunkification_optimization_20260608_PLACEHOLDER/state.toml - conductor/tracks/chunkification_optimization_20260608_PLACEHOLDER/index.md Cross-references added: - docs/reports/computational_shapes_ssdl_digest_20260608.md (the SSDL digest is the theoretical foundation; explicitly cited in the spec's §6.1 "SSDL alignment" and in metadata.json external) - docs/reports/c11_python_interop_assessment_20260608.md (the v1+v2 assessment; explicitly cited in spec's §6 See Also) No code modified. Track does NOT appear in the active queue of conductor/tracks.md; appears in the Backlog / Contingency section as a reference, not a commitment. Activation criteria (per metadata.json): 1. Profiling shows a real bottleneck in a target code path 2. The bottleneck cannot be solved with existing Python packages 3. The user explicitly approves activation Without all 3, this track stays deferred. Default action is don't. |
||
|
conductor-tier2
|
12311190b3 |
docs(interop-v2): part 3 revises the recommendation after user's threshold-shift + shape-change corrections
The user pushed back on the v1 recommendation (commit
|
||
|
conductor-tier2
|
68354841cb |
docs(interop-assessment): C11 <-> Python interop design space for chunkification_optimization
The user asked a sharp, skeptical question: can a chunk-based C11 data structure actually interop with Python's runtime in a way that's useful for Manual Slop? They explicitly corrected my first-draft framing (the duffle.h + pikuma ps1 files are a C11 *style reference*, not an interop pattern). The assessment investigates honestly and reports tractable-vs-not. docs/reports/c11_python_interop_assessment_20260608.md (564 lines, 38KB): Part 1: C11 style reference summary - 11 style observations from reading duffle.h + main.c + pikuma ps1 duffle/ + hello_gte.c end-to-end - Byte-width typedef convention (U1/U2/U4/U8, S1/S2/S4/S8, B1-B8, F4/F8) - The macro meta-DSL (Struct_/Enum_/Array_/Slice_/Opt_/Ret_) - The I_/IA_/N_ inline discipline - The r/v pointer rule (restrict OR volatile, never both, never const) - Slice + Slice_T as the data-structure primitive - FArena as the allocation primitive (single-buffer, NOT chunked) - defer/defer_rewind/scope as the cleanup primitive - KTL (linear key-value table) as the "assume small N" pattern - What a chunk-array in duffle.h style would look like Part 2: Interop design space (the actual question) - 5 candidate interop layers: ctypes, cffi, pybind11, custom CPython C extension, NumPy wrap - Honest assessment matrix: build cost, per-op overhead, style fit, lego-set pattern support - Verdict: custom CPython C extension is most tractable; pybind11 is style-mismatched; ctypes/cffi work for non-hot-path - What "MVP chunked C11 package" requires (~500-1000 LOC total) - 5 questions to ask the user before this becomes a track - Crucial insight: the user's "unorthodox" interop is most likely duffle.h-style C11 + thin PyTypeObject glue at the bottom of the same .h file. Tractable, style-fit high. Cross-references the 5 sources: - docs/transcripts/i-h95QIGchY (Reece's Xar reference impl) - docs/ideation/ed_chunk_data_structures_20260523.md - docs/reports/session_synthesis_20260608.md (the original proposal) - src/app_controller.py:716 (the comms.log target) - The user's local forth_bootslop + pikuma ps1 repos (read in full) This is a follow-on to the synthesis's 2 proposed tracks (manual_ux_validation_20260608_PLACEHOLDER + chunkification_optimization_20260608_PLACEHOLDER). The user's question resolved the "skeptical of #2" concern by scoping the tractable path: CPython C extension in duffle.h style. The "lego-set of user-defined Python->C11 chunk ops" is NOT tractable without a Python->C11 AST emitter, which is a different (much larger) track. |
||
|
conductor-tier2
|
77d7dff5ff |
docs(session-synthesis): preserve-before-compact archive of the 2026-06-08 session
The user explicitly requested the biggest in-depth report I can muster at 478,992 tokens (94% of context window). The next session will start with a fresh context; these two documents are the minimum-sufficient anchor. docs/reports/session_synthesis_20260608.md (579 lines, 40KB): - 12 sections covering every artifact this session produced - The 5 sources loaded: 2 YouTube transcripts + 2 Fleury articles + user's chunk-ideation archive - The 10 commits in the session's commit chain (with the user's test-fragility work adjacent but not mine) - The 4 audit-time heuristics derived from the 5-source lens - The "what the user should know" section for next session docs/reports/proposed_new_tracks_20260608.md (190 lines, 12KB): - 2 new tracks proposed (manual_ux_validation_20260608_PLACEHOLDER, chunkification_optimization_20260608_PLACEHOLDER) with spec-ready detail - 8 non-recommendations (so the user knows what I'm NOT suggesting) - A "what I'd recommend" section with one-tracks-when sequencing No code modified. Both are session-final artifacts, not tracks. They live in docs/reports/ alongside the other session outputs (SSDL digest, ASCII-sketch workflow, chunk ideation archive). Cross-references the 5 sources (all committed to docs/transcripts/ and docs/ideation/ in earlier user commits): - docs/transcripts/wo84LFzx5nI_big_oops_casemuratori.txt - docs/transcripts/i-h95QIGchY_assuming_as_much_as_possible_andrewreece.txt - docs/ideation/ed_chunk_data_structures_20260523.md - docs/reports/computational_shapes_ssdl_digest_20260608.md - docs/reports/ascii_sketch_ux_workflow_20260608.md These 5 documents are the session's "thinking-aid" corpus. The synthesis is the *index*; together they're the minimum-sufficient context to re-anchor any future session. |
||
|
conductor-tier2
|
a9333bbb59 |
conductor(track-update): code_path_audit_20260607 - post-4-tracks timing + 5-source framing
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.
|
||
|
conductor-tier2
|
8a597d1832 |
conductor(track-update): mcp_architecture_refactor - list_tool_schemas + security-as-contract
4 surgical additions to the spec, no task changes: 1. list_tool_schemas on the SubMCP Protocol: Added the method to §3.1 (The SubMCP Protocol). Per nagent_review Pitfall #6 (hard-coded tool discovery) and takeaway #5 (self-describing tools), each sub-MCP advertises its own capabilities via list_tool_schemas() rather than relying on a central registry. This is the equivalent of nagent's collect_bin_tool_descriptions per sub-MCP. The MCPController.get_tool_schemas() becomes a simple aggregator. 2. Security model is the contract: Added a new Important note to §3.3 (The 3-Layer Security Model). The 3 layers (Allowlist Construction -> Path Validation -> Resolution Gate, per docs/guide_mcp_client.md) are not just refactored - they are the CONTRACT between MCPController and the sub-MCPs. Sub-MCPs receive a pre-validated Path and trust it. They do NOT re-validate. The refactor is structural, not security-changing. 3. Docs touchpoint in Phase 7: Added the docs touchpoint to Phase 7 per the docs Refresh Protocol. The update to docs/guide_mcp_client.md should add a Sub-MCP Architecture section, link the list_tool_schemas pattern to 3-Layer Security Model, and cross-link the 3 new guides from the 2026-06-08 docs refresh. 4. See Also cross-references: Added 8 new entries to §12.2: - docs/guide_context_aggregation.md (FileItem consumer) - docs/guide_state_lifecycle.md (App state delegation) - docs/guide_discussions.md (23-operation matrix) - conductor/tracks/qwen_llama_grok_integration_20260606/ (Result return type coordination) - conductor/tracks/nagent_review_20260608/{report,takeaways}.md - (2 specific data_oriented_error_handling and data_structure_strengthening cross-refs) No plan.md changes. |
||
|
conductor-tier2
|
1fb0d79c0d |
conductor(track-update): data_structure_strengthening - HistoryMessage vs ProviderHistoryMessage split
4 surgical additions to the spec, no task changes: 1. ProviderHistoryMessage: Added a new alias to §3.1 (The Aliases). Per nagent_review Pitfall #4 (provider history divergence), the UI/curation layer (HistoryMessage, edited via disc_entries[i].content) and the SDK layer (ProviderHistoryMessage, the bytes actually replayed to the LLM) are *distinct*. Conflating them via a single alias perpetuates the bug. The new alias is documented as a separate concept with its own use sites (_anthropic_history, _deepseek_history, _minimax_history, _grok_history, _llama_history). The follow-up public_api_migration_20260606 track is the natural moment to unify the two layers; this spec just makes the distinction explicit. 2. FileItem alias points to the existing models.FileItem dataclass, not Metadata. Per docs/guide_context_aggregation.md (added 2026-06-08), FileItem is a 9-field dataclass (path, auto_aggregate, force_full, view_mode, selected, ast_signatures, ast_definitions, ast_mask, custom_slices, injected_at) with a __post_init__ normalizer. Aliasing it to dict[str, Any] would lose the type safety. The 9 other aliases remain dict aliases for round-trip compatibility. 3. gui_2.py and mcp_client.py as follow-up: Added a Note (dated 2026-06-08) to the Out of Scope section. The 23 lower-impact files (deferred) are dominated by gui_2.py (26+ weak sites per guide_state_lifecycle.md) and mcp_client.py (will be touched heavily by the parallel mcp_architecture_refactor_20260606). The deferral is correct but the follow-up should explicitly call out these two files as the next targets, rather than implying they're handled. 4. See Also cross-references: Added 7 new entries to §12.2: - docs/guide_models.md (FileItem dataclass source) - docs/guide_context_aggregation.md (FileItems consumer) - docs/guide_discussions.md (HistoryMessage shape) - docs/guide_state_lifecycle.md (state delegation) - conductor/tracks/mcp_architecture_refactor_20260606/ - conductor/tracks/nagent_review_20260608/{report,takeaways}.md No plan.md changes. |
||
|
conductor-tier2
|
0471440c68 |
conductor(track-update): data_oriented_error_handling - nagent_review + docs refresh
3 surgical additions to the spec, no task changes: 1. New ErrorKind: Added PROVIDER_HISTORY_DIVERGED_FROM_UI to the ErrorKind enum. Per nagent_review Pitfall #4 (provider history divergence: user edits disc_entries[i].content via the discussion UI but ai_client._<provider>_history still replays the original). The new kind makes the divergence *detectable* and *reportable* so the follow-up public_api_migration_20260606 track can collapse the two history layers. The Result pattern from this track is the natural carrier for the signal. 2. State-delegation regression tests: Added mandatory regression tests to the testing strategy in §6 for the ai_client refactor (highest-risk phase). The new tests exercise: - app.temperature = 0.5 round-trips through App.__getattr__/ __setattr__ delegation (per gui_2.py:666-675) - controller.disc_entries[i].content is reflected in the next send_result()'s messages parameter - The 3 per-provider history locks serialize correctly under concurrent send_result() calls The reason this is mandatory: per guide_state_lifecycle.md (added 2026-06-08), the App.__getattr__/__setattr__ pattern means a partial refactor manifests as silent AttributeError deep in test code, not at the refactor commit boundary. 3. See Also cross-references: Added 6 new entries to §12.3: - docs/guide_ai_client.md (per-provider history globals) - docs/guide_mcp_client.md (3-layer security model) - docs/guide_state_lifecycle.md (3 per-thread + 7-lock pattern) - docs/guide_discussions.md (23-operation matrix) - docs/guide_context_aggregation.md (build_discussion_section) - conductor/tracks/mcp_architecture_refactor_20260606/ - conductor/tracks/nagent_review_20260608/{report,takeaways}.md No plan.md changes. Plan tasks are task-level and will flow from the spec changes when the track is re-planned. |
||
|
conductor-tier2
|
77ae2ec7a8 |
conductor(track-update): qwen_llama_grok - spec notes for nagent_review + docs refresh
4 surgical additions to the spec, no task changes: 1. Result return type: Added a coordination note in §3.1 (Data- Oriented Design) explaining that the shared send_openai_compatible helper should return Result[NormalizedResponse, ErrorInfo] from day 1, not NormalizedResponse + ProviderError raise. This is so the downstream data_oriented_error_handling_20260606 track is a small mechanical pass over new code, not a second migration. References nagent_review Pitfall #4 (provider history divergence) and the ErrorKind.PROVIDER_HISTORY_DIVERGED_FROM_UI use case. 2. Declarative read, not behavioral dispatch: Added clarification to §6 (UX Adaptation) that the capability matrix is a *read* of declarative data, not a new dispatch layer. Per nagent_review Pitfall #1 (opaque function calling in the Application is the correct choice; nagent-style protocol is for Meta-Tooling), UI elements are visible/enabled/disabled/hidden but the *behavior* they invoke is unchanged. Three concrete examples added: screenshot button, cost panel, cache panel. 3. PROVIDERS source of truth: Added a NOTE in §3.2 (Module Layout) that src/models.py:79-86 PROVIDERS is the existing single source of truth for the (vendor, model) enumeration. The capability registry reads from this constant rather than introducing a parallel list. Cross-references docs/guide_models.md. 4. Docs touchpoint: Expanded Phase 6 (Docs + Archive) in §9 to note that docs/guide_ai_client.md needs the new providers + the shared helper documented, and that docs/guide_context_aggregation.md (added 2026-06-08) is the reference for the aggregate.py pipeline that all new providers use. 5. See Also cross-references: Added 3 new entries to §13.2: - docs/guide_context_aggregation.md (the new pipeline guide) - conductor/tracks/nagent_review_20260608/report.md (§1, §5, §15) - conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md (§1, §2, §9) No plan.md changes. Plan tasks are task-level and will flow from the spec changes when the track is re-planned. |
||
|
conductor-tier2
|
161ebb0da6 |
docs(fix): correct nav link case + relative-path level
Gitea (and any case-sensitive filesystem) was rendering the [Top]
nav links in /docs as broken because of two bugs:
1. Case-sensitivity: 22 links used '../README.md' (all-uppercase)
but the actual file is 'docs/Readme.md' (capital R, lowercase
rest). 21 guide_*.md nav bars were affected, plus 1 internal
cross-link in Readme.md itself. Works on Windows (case-
insensitive) but broken on Linux/Gitea.
Fix: 22 occurrences across 22 files changed
'../README.md' -> '../Readme.md'
2. Wrong relative-path level: 16 links used '../../conductor/...'
from 'docs/guide_*.md' to reach 'conductor/'. This goes up 2
levels to 'projects/', which doesn't exist. The correct path
from 'docs/guide_*.md' to 'conductor/' is 1 level up
('../conductor/...'). 12 unique patterns across 10 files
affected.
Fix: 16 occurrences across 10 files changed
'../../conductor/' -> '../conductor/'
3. Bonus: 1 planned-guide link in guide_context_curation.md
referenced a never-written 'guide_context_presets.md'. The
ContextPreset schema is now fully covered in the new
'guide_context_aggregation.md' (per the 2026-06-08 docs
refresh). Fix: link target updated.
No content was changed, only link paths. 24 files, 37 link
replacements, 37 deletions.
Verification:
- All .md links in docs/ now resolve to existing files
(validated by path-resolution check from each file's directory)
- The 3 new guides from the previous docs refresh commit
(guide_discussions.md, guide_state_lifecycle.md,
guide_context_aggregation.md) had the case bug inherited from
guide_architecture.md's existing nav pattern; their top-of-file
nav bars are now correct
- The 21 pre-existing guide nav bars that had the same bug
(all 21 of them, except the 3 that used the correct case:
guide_mma.md, guide_simulations.md, guide_tools.md) are now
also fixed
- Inter-guide links (e.g. [Discussions](guide_discussions.md))
were not affected; they were always correct because both the
link text and the actual filename are lowercase
This is a docs-only fix. No code modified.
|
||
|
conductor-tier2
|
ba05168493 |
docs(refresh): 3 new guides + cross-links from nagent_review
Per the docs Refresh Protocol (conductor/workflow.md), after a
reference/analysis track ships, the affected guides must be updated
to reflect new module structure or new conventions. The nagent_review
track (
|
||
|
conductor-tier2
|
9cc51ca9af |
conductor(track): nagent review - deep-dive + 6 pitfalls + 10 actionable takeaways
Reference/analysis track. Produces 0 code changes. Artifacts (conductor/tracks/nagent_review_20260608/): - spec.md (240 lines) - track wrapper with Application/Meta-Tooling framing - report.md (571 lines) - 14-section deep-dive; primary deliverable - comparison_table.md (79 lines) - flat side-by-side reference - decisions.md (286 lines) - 10 future-track candidates with priority matrix - nagent_takeaways_20260608.md (363 lines) - 10 actionable patterns grounded in code (file:line refs into nagent source and Manual Slop source) - metadata.json (132 lines) - structured metadata + verification criteria - state.toml (113 lines) - per-task tracking + user-corrections log (7 entries) 14 nagent principles covered in report.md (durable work, text-in/text-out, editable state, visible protocol, the loop, per-file memory, repo history, neighborhoods, sub-conversations, controlled writes, large files, tool discovery, framework differences, build your own). 6 pitfalls (revised from 8 after user-corrections): 1. No structured output protocol in Application AI (opaque function calling) 2. Provider-specific history in process globals (ai_client._anthropic_history + _deepseek_history + _minimax_history) 3. RAG is not 'history as data' (fuzzy, not auditable) 4. AI client is a stateful singleton (2,685-line ai_client.py) 5. No non-MMA disposable sub-conversations (1:1 gap; user-flagged want) 6. Hard-coded tool discovery (45-tool if/elif in mcp_client.py) User-corrections applied (3 rounds, 7 total corrections recorded): - Editable discussions: PARTIAL -> PARITY (DIFFERENT FOCUS) with full A1-A7 per-entry + B1-B11 discussion-level + C1-C5 undo/redo operation matrix - Per-file memory: DOMAIN MISMATCH -> MANUAL SLOP IS STRONGER IN CURATION DIMENSION (FileItem + ContextPreset vs nagent's inode-keyed conversation log; complementary, not equivalent) - Sub-conversations: MMA has it; 1:1 does not -> 'PARITY for MMA; GAP for 1:1 discussions' (user wants this) - RAG: opt-in, not gap; user wants pre-staging via sub-conversation - Personas: config bundling (can opt out via AI settings) - Tool discovery: deferred (user has 'intent based DSL' idea but 'no where near that ideation yet') 10 actionable takeaways (separate from the 6 pitfalls - those are diagnosis, these are prescription): 1. State visibility (UI inspector for in-process state) 2. Readable conversation log (text-greppable, not just JSON-L) 3. Sub-agents for 1:1 (HIGH priority - user-flagged) 4. File-identity over file-path (st_dev:st_ino rename-safe) 5. One loop shape visible in diagnostics 6. Visible retry on protocol failure 7. Meta-Tooling DSL (intent-based, deferred) 8. Self-describing tools (subsumed by mcp_architecture_refactor_20260606) 9. Single source of truth for disc_entries + provider history 10. Sub-agent return type constraint (bake into candidate #1 spec) Domain classification: every recommendation tagged Application / Meta-Tooling / Both per docs/guide_meta_boundary.md. nagent lives in the Meta-Tooling domain; Manual Slop's Application AI is a different kind of thing. No code modified by this track (reference/analysis only). All 7 files parse cleanly (JSON, TOML, Markdown). All internal cross-links resolve. Track is 'active' awaiting human review; future-track candidates live in decisions.md and nagent_takeaways_20260608.md. |
||
|
Conductor
|
58cd759968 |
fix(markdown): strip blank between bullet and indented continuation paragraph
ROOT CAUSE: imgui_md (mekhontsev/imgui_md) BLOCK_P does NOT call ImGui::NewLine()
when m_list_stack is non-empty (verified in imgui_md.cpp). So a multi-paragraph
list item like:
- bullet text (long, wraps to 2 lines)
continuation paragraph
renders BOTH paragraphs at the same Y because the second BLOCK_P enters/exits
without advancing the cursor. The continuation crashes into the previous
paragraph's last wrapped line.
FIX: Add MarkdownRenderer._normalize_list_continuations preprocessor that
strips blank lines between a list item and its indented continuation. The
continuation then becomes a lazy continuation of the first paragraph (single
BLOCK_P in imgui_md, proper text wrapping, no overlap). Trade-off: users
cannot have separate paragraphs within a single list item. Acceptable.
Also: fixed a pre-existing bug in _normalize_nested_list_endings where a
duplicate conditional caused the function to return empty string (the
out.append(line) was inside the wrong scope). It was silently corrupting
all list content since
|
||
|
Conductor
|
fd5f4d0eda |
fix(markdown): strip backticks in table cells + add nested-list overlap workaround
FIX 1 (src/markdown_table.py): Cells now use imgui_md.render(c) instead of imgui.text_wrapped(c). imgui_md uses MD4C which strips backtick-delimited inline code spans BEFORE rendering, so backticks no longer appear as literal characters in cell content. Side benefit: inline emphasis (*foo*, **bar**) now renders in cells too. FIX 2 (src/markdown_helper.py): Added MarkdownRenderer._normalize_nested_list_endings. Upstream imgui_md (mekhontsev/imgui_md) BLOCK_UL exit only calls ImGui::NewLine() for top-level list endings. For nested list endings, no NewLine is emitted, so the next text starts at the same Y as the last list item, causing visual overlap. The preprocessor inserts a blank line before any line that follows a list item with MORE indent than itself, forcing a paragraph break. Cannot fix the C++ from Python. Tests: - test_markdown_table_wrapped.py: updated to assert imgui_md.render is called for cell content (not imgui.text_wrapped). - test_markdown_helper_bullets.py: added 4 tests for the new preprocessors (nested-list blank insertion + bullet delimiter conversion + edge cases). 20/20 markdown unit tests pass. 1-space indentation throughout. KNOWN LIMITATIONS (cannot fix without forking imgui_md C++): - Inline code spans render as plain text (no monospace font in cells) - The ' * ' bullet delimiter has a Y-overlap bug upstream (workaround: pre-convert to '- ' via _normalize_bullet_delimiters) - Nested list ending overlap (workaround: insert blank line via _normalize_nested_list_endings) |
||
|
Conductor
|
feed18eb0f |
fix(markdown): remove table double-header + add imgui_md bullet workaround
Table fix (src/markdown_table.py):
- Add TableColumnFlags_.width_stretch to each table_setup_column call
(was missing — columns had no width to wrap against, so text_wrapped
couldn't grow row height → all rows squished together)
- Remove the explicit for-h-in-headers: table_next_column + text_wrapped(h)
loop. table_headers_row() already renders the header from the
table_setup_column() names; the explicit loop was drawing it AGAIN on
top → double-rendered header rows.
Bullet fix (src/markdown_helper.py):
- Revert _render_md_no_bullet_overlap → simple imgui_md.render(chunk);
imgui.spacing() (the original
|
||
|
Conductor
|
919d28e950 | test(markdown): add live_gui smoke test for markdown table + bullet rendering | ||
|
Conductor
|
d15fdcdb05 | fix(markdown): revert table to simple form with text_wrapped + add regression tests |