From 14d8a2e849123ab588fd2ec4e1960882eac0adbf Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 9 May 2026 12:50:13 -0400 Subject: [PATCH] chore(conductor): Add new track 'Structural Dependency Mapping (SDM) Docstrings' --- conductor/tracks.md | 5 +++ .../tracks/sdm_docstrings_20260509/index.md | 5 +++ .../sdm_docstrings_20260509/metadata.json | 8 ++++ .../tracks/sdm_docstrings_20260509/plan.md | 23 +++++++++++ .../tracks/sdm_docstrings_20260509/spec.md | 39 +++++++++++++++++++ 5 files changed, 80 insertions(+) create mode 100644 conductor/tracks/sdm_docstrings_20260509/index.md create mode 100644 conductor/tracks/sdm_docstrings_20260509/metadata.json create mode 100644 conductor/tracks/sdm_docstrings_20260509/plan.md create mode 100644 conductor/tracks/sdm_docstrings_20260509/spec.md diff --git a/conductor/tracks.md b/conductor/tracks.md index 8e85b11..8067f0c 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -180,3 +180,8 @@ This file tracks all major tracks for the project. Each track has its own detail ### Earlier Archives - [x] **Track: Robust Live Simulation Verification** + +--- + +- [ ] **Track: Structural Dependency Mapping (SDM) Docstrings** +*Link: [./tracks/sdm_docstrings_20260509/](./tracks/sdm_docstrings_20260509/)* diff --git a/conductor/tracks/sdm_docstrings_20260509/index.md b/conductor/tracks/sdm_docstrings_20260509/index.md new file mode 100644 index 0000000..43fe59d --- /dev/null +++ b/conductor/tracks/sdm_docstrings_20260509/index.md @@ -0,0 +1,5 @@ +# Track sdm_docstrings_20260509 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) diff --git a/conductor/tracks/sdm_docstrings_20260509/metadata.json b/conductor/tracks/sdm_docstrings_20260509/metadata.json new file mode 100644 index 0000000..27c1d68 --- /dev/null +++ b/conductor/tracks/sdm_docstrings_20260509/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "sdm_docstrings_20260509", + "type": "refactor", + "status": "new", + "created_at": "2026-05-09T16:45:00Z", + "updated_at": "2026-05-09T16:45:00Z", + "description": "Add structural dependency mapping (SDM) docstrings to state variables, methods, and functions across the codebase." +} diff --git a/conductor/tracks/sdm_docstrings_20260509/plan.md b/conductor/tracks/sdm_docstrings_20260509/plan.md new file mode 100644 index 0000000..f8233d4 --- /dev/null +++ b/conductor/tracks/sdm_docstrings_20260509/plan.md @@ -0,0 +1,23 @@ +# Implementation Plan: Structural Dependency Mapping (SDM) Docstrings + +## Phase 1: Convention & Documentation +- [ ] Task: Update `conductor/product-guidelines.md` with SDM convention +- [ ] Task: Update `conductor/code_styleguides/python.md` with SDM convention +- [ ] Task: Conductor - User Manual Verification 'Phase 1: Convention' (Protocol in workflow.md) + +## Phase 2: Tooling & Pilot +- [ ] Task: Research AST-based mapping logic (identify mutation points and callers) +- [ ] Task: Create a pilot script `scripts/sdm_mapper.py` to generate SDM tags for a single module (`src/models.py`) +- [ ] Task: Manually verify generated tags for `src/models.py` +- [ ] Task: Conductor - User Manual Verification 'Phase 2: Tooling' (Protocol in workflow.md) + +## Phase 3: Global Rollout (Core Logic) +- [ ] Task: Run `sdm_mapper.py` on all files in `./src` +- [ ] Task: Agent review of generated tags for core modules (`app_controller.py`, `gui_2.py`) +- [ ] Task: Inject tags into `./src` docstrings +- [ ] Task: Conductor - User Manual Verification 'Phase 3: Rollout' (Protocol in workflow.md) + +## Phase 4: Full Codebase & Finalization +- [ ] Task: Run rollout for `./simulation` and `./tests` +- [ ] Task: Run full test sweep to ensure no regressions [checkpoint: ] +- [ ] Task: Conductor - User Manual Verification 'Phase 4: Finalization' (Protocol in workflow.md) diff --git a/conductor/tracks/sdm_docstrings_20260509/spec.md b/conductor/tracks/sdm_docstrings_20260509/spec.md new file mode 100644 index 0000000..4778287 --- /dev/null +++ b/conductor/tracks/sdm_docstrings_20260509/spec.md @@ -0,0 +1,39 @@ +# Specification: Structural Dependency Mapping (SDM) Docstrings + +## Overview +Introduce a project-wide convention for "Structural Dependency Mapping" (SDM) in Python docstrings. This convention requires that all state variable declarations, methods, and functions include terse metadata indicating their usage, mutation points, and callers. This ensures that AI agents can accurately assess the impact of refactors beyond immediate scope. + +## Goals +- Improve AI agent context regarding non-local dependencies in a dynamic language (Python). +- Minimize token burn through a terse, standardized tag format. +- Ensure the convention is self-sustaining by documenting it in the project's core guidelines. + +## SDM Tag Convention +Docstrings will include specific tags at the bottom: +- **For Functions/Methods:** `[C: Caller1, Caller2]` (List of primary calling functions/methods). +- **For State Variables:** `[M: FileA:Line, MethodB]` (List of mutation points/files) and `[U: FileC]` (Major codepaths of use). + +Example: +```python +def update_registry(self, data: dict) -> None: + """ + Updates the central provider registry. + [C: _cb_load_config, start_services] + """ + ... +``` + +## Functional Requirements +- **Update Guidelines:** Add the SDM convention to `conductor/product-guidelines.md` and `conductor/code_styleguides/python.md`. +- **Codebase Rollout:** Perform a global batch update of `./src`, `./simulation`, and `./tests` to inject SDM tags into existing definitions. +- **Verification:** Ensure the batch update does not introduce syntax errors or logical regressions. + +## Implementation Strategy +- **Hybrid Automation:** Use a Tier 4 QA sub-agent or a specialized static analysis script (leveraging `tree-sitter` or the project's existing AST tools) to generate the initial mapping. +- **Human/Agent Review:** A reasoning-heavy agent must review the generated tags before final injection to ensure accuracy. + +## Acceptance Criteria +- [ ] SDM convention is documented in `product-guidelines.md` and `python.md`. +- [ ] All major state variables, methods, and functions in `./src` have SDM tags. +- [ ] Full test suite passes after injection. +- [ ] AI agents (Tier 2/3) demonstrate awareness of the tags in a sample refactor turn.