Orchestrata Ultimate › Plans › evidence › d2-traceability
D2 Evidence Pack — Traceability Quintuple Collapse
Source: plans/evidence/d2-traceability.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-05 · 90 lines.
Prose pending.
Plan text
D2 Evidence Pack — Traceability Quintuple Collapse
Source: auditor agent W3.E2 (2026-07-06), verified with corrections by the orchestrator (see "Verification notes"). Decision: plan §D, D2. Blocks W3.2.
Verification notes (orchestrator)
- ✅ CONFIRMED: Arabic-word corruption in the RTM markdown header —
core/tracing/traceability.py:231emits"# محسوب Requirements Traceability Matrix (Auto-Generated)". That module is imported by production code (session/kg_sync/_common.py:10,_stage_docs.py:6). - ❌ REFUTED: the pack's "Python 2 syntax bug / never exercised" claim.
except SyntaxError, UnicodeDecodeError:(verification/traceability.py:417) is valid PEP 758 syntax on Python 3.14 (unparenthesized multi-exception withoutas). File compiles (py_compileOK) and is imported byverification/__init__.py:9. Also the claimed twin attraceability_utils.py:326does not exist (clean parenthesized code there). Portability nit only: PEP 758 form is 3.14+-only — fine (pyproject pins >=3.14).
1. API inventory
| Module | Lines | Key exports |
|---|---|---|
core/base/traces.py |
72 | traces() decorator + id-pattern validation. Zero imports — layer-0. Docstring: built to eliminate layer-0 upward imports. 444/671 modules import it. |
core/traceability/__init__.py |
511 | REDEFINES traces() (114–156); TraceInfo/ValidationReport, collect_traces, generate_rtm (347, JSON list), generate_rtm_markdown (392), validate_traces (466) |
core/traceability_utils.py |
514 | Docstring claims "zero orchestrata imports — copied into generated project workspaces". REDEFINES traces(); own Requirement/UserStory/RTMReport; scan_traces (326), generate_rtm (357), save_rtm |
core/tracing/traceability.py |
~331 | Pre-port residue (docstring references monorepo orchestrata.core.traceability; "Armada" typo). REDEFINES traces(); generate_rtm (167), generate_rtm_markdown (212, corrupted header line 231) |
verification/traceability.py |
612 | "Migrated from spike/traceability.py". Only one of the 5 that imports the canonical decorator (from ...core.base.traces import traces, line 25). Same Requirement/RTMReport shape as traceability_utils. scan_traces (398), generate_rtm (439), save_rtm (526) |
2. Twin analysis — generate_rtm_markdown
core/traceability/__init__.py:392 vs core/tracing/traceability.py:212:
71-line bodies, byte-identical except one line — the corrupted Arabic header
(above). Copy-paste twins with one-sided corruption.
3. Consumer map (import-line evidence)
core/base/traces.py← 444/671 modules (the de-facto canon).core/traceability/__init__.py←scripts/generate_traced_rtm_simple.py:13(the only RTM-tooling script importing any of the 5 as a library);drivers/claude_code_driver.py:14(productiontracesimport NOT from base);rtm/scripts/generate_module.py:144,rtm/scripts/add_traces.py:59,135-137.core/traceability_utils.py←agents/volks/compliance/_pipeline.py:51,108,149,286(production — CONTRADICTS its "standalone copy-target only" docstring contract);rtm/scripts/generate_rtm.py:7,10,13.core/tracing/traceability.py←session/kg_sync/_common.py:10,session/kg_sync/_stage_docs.py:6(production; the corrupted-header path).verification/traceability.py←verification/__init__.py:9+ its tests.- Independent reimplementations importing NONE of the 5:
scripts/generate_rtm.py(~1035 lines),serialize_codebase_ast.py check-traces,rtm/scripts/generate_rtm.py,rtm/scripts/reconcile_rtm.py. - Broken imports (dead code):
rtm/scripts/parse_requirements.py:9andrtm/scripts/serialize_codebase_ast.py:108importorchestrata_ultimate.core.traceability.traceability_utils— a path that does not exist. First-party acknowledgment exists:rtm/scripts/sync_ast_to_neo4j.py:43comment about the broken import chain.
4. Risks (verified subset)
- 3-way REQ/US regex divergence across the redefined
traces()decorators — an id can validate under one module and be orphaned by another's scanner. (Directly relevant to RTM correctness; verify exact patterns during W3.2.) - Corrupted RTM header in a production path (§2).
- Self-tracing noise:
verification/traceability.pydecorates ~10 of its own symbols with the same REQ-097-001 tuple → duplicate-location noise per scan. - Contract violation: traceability_utils used as a production library.
5. Recommendation (auditor, orchestrator-endorsed)
- Canonical decorator:
core/base/traces.py(already 444-importer fact). - Canonical JSON RTM engine:
core/traceability/__init__.py; canonical Requirement/RTMReport engine:verification/traceability.py(already on the canonical decorator; lowest migration cost). - Sequence (mirrors interfaces→protocols collapse):
- Fix the corrupted header + make all redefining modules import
tracesfromcore.base.traces(thin aliases). - Collapse
core/tracing/traceability.pyinto a re-export shim ofcore/traceability. - Repoint
session/kg_sync/_common.py:10,_stage_docs.py:6; fix the two brokenrtm/scriptsimports. - DECISION FORK (Mohamed): does the "copy traceability_utils into generated projects" mechanism stay physically standalone (then compliance/_pipeline.py must stop importing it) or copy-from-canonical at generation time (then traceability_utils becomes the alias)? Determines survivor between traceability_utils / verification.traceability.
- Delete
core/tracing/traceability.pyonce shim importers reach zero.
- Fix the corrupted header + make all redefining modules import
- Blast radius: base.traces 0; tracing shim 2 call sites; utils/verification merge ≥4 call sites + the fork above.
- Out of scope, noted: whether scripts/generate_rtm.py + rtm/scripts family fold into the canonical engine (they duplicate scanning logic independently).