@danmoisan/drm-copilot-mcp 0.0.1

package/resources/customizations/.github/skills/pr-context-artifacts/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: pr-context-artifacts
+description: 'PR context artifact locations and refresh rules. Use when generating, reading, or inlining pr_context summary/appendix artifacts.'
+---
+
+# PR Context Artifacts
+
+Canonical locations and usage rules for PR context artifacts.
+
+## When to Use This Skill
+
+Use this skill when:
+- You generate or refresh PR context artifacts.
+- You reference PR context summary/appendix as evidence.
+- You inline PR context artifacts into remediation handoffs.
+
+## Canonical Artifact Locations
+
+- Summary: `artifacts/pr_context.summary.txt`
+- Appendix: `artifacts/pr_context.appendix.txt`
+
+## Refresh Rule
+
+If the artifacts are missing or stale relative to the current branch state, re-generate them using the repo’s PR context collector.
+
+- When `PRBaseBranch` is supplied explicitly, use that exact branch for refresh.
+- When `PRBaseBranch` is missing or ambiguous, resolve it first with `pr-base-branch-merge-base` before running the collector.
+- Do not infer the refresh base from the repository default branch unless merge-base resolution fails for all candidates.
+- Treat an already-fresh artifact pair as authoritative; do not refresh solely because no explicit `PRBaseBranch` input was provided.

package/resources/customizations/.github/skills/remediation-handoff-atomic-planner/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: remediation-handoff-atomic-planner
+description: 'Reusable remediation trigger and atomic_planner handoff steps. Use when audits require remediation inputs and a delegated remediation plan.'
+---
+
+# Remediation Handoff to atomic_planner
+
+Shared remediation workflow and handoff expectations for agents that delegate to `atomic_planner`.
+
+## When to Use This Skill
+
+Use this skill when:
+- Audit findings require remediation.
+- You must create remediation inputs and delegate plan creation to `atomic_planner`.
+
+## Trigger Conditions (Generic)
+
+Trigger remediation when any of these are true:
+- Audit artifacts contain FAIL or meaningful PARTIAL findings.
+- Toolchain checks fail.
+- Acceptance criteria are not met.
+
+## Required Remediation Inputs
+
+Create `remediation-inputs.<timestamp>.md` with:
+- Enumerated fix list with file paths, expected behavior, and verification commands.
+- A “do not do” list (no scope creep, no policy weakening, no silent skips).
+
+## Plan Creation and Handoff
+
+1) Create a remediation plan target file using the repo’s plan template.
+2) Delegate to `atomic_planner` with:
+   - `${spec}` pointing to remediation inputs (authoritative)
+   - `${file}` pointing to the remediation plan target file
+3) Require `atomic_planner` to output a deterministic, atomic plan with phases and `[P#-T#]` IDs.
+
+## Context Package (When Required)
+
+If the calling agent requires a context package, inline the specified audit artifacts, PR context artifacts, and any relevant plan files in the delegated prompt.

package/resources/customizations/.github/skills/skill-canonical-location-audit/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: skill-canonical-location-audit
+description: 'Audit skills for canonical-location duplication. Use when ensuring a canonical location for a given item is defined in exactly one skill and duplicates are flagged.'
+---
+
+# Skill Canonical-Location Audit
+
+Audit skills to ensure canonical locations for the same item are not defined in multiple places.
+
+## When to Use This Skill
+
+Use this skill when:
+- You add or update skills that define canonical locations.
+- You want to verify that canonical paths live in exactly one skill.
+- You need a duplication report listing which skills conflict.
+
+## Scope
+
+- Applies to all skills under `.github/skills/**/SKILL.md`.
+- Focuses on canonical locations (paths, folders, or file names) for a given item (e.g., PR context artifacts, evidence locations, issue mirrors).
+
+## Audit Workflow
+
+1) Inventory canonical-location statements
+   - Read each `SKILL.md` and extract explicit canonical location statements (paths, folders, file names).
+   - Group statements by the item they describe (e.g., “PR context summary”, “baseline evidence”).
+
+2) Detect duplicates
+   - For each item group, verify that exactly one skill defines its canonical location.
+   - If two or more skills define the same item’s canonical location, flag it as a duplication.
+
+3) Report results
+   - Produce a short report listing:
+     - The item with duplicated canonical location
+     - The conflicting skills
+     - A recommendation for consolidation (name the single skill to keep as source-of-truth)
+
+## Output Template (Suggested)
+
+- Item: <canonical item name>
+  - Skills with definitions: <skill A>, <skill B>, ...
+  - Recommendation: Keep <skill X> as canonical; remove duplicates from others.
+
+## Notes
+
+- If a skill references a canonical location indirectly (e.g., “see evidence-and-timestamp-conventions”), do NOT treat that as a duplication.
+- Only treat explicit canonical paths or filenames as definitions.
+

package/resources/feature-templates/bug/plan.yyyy-MM-ddTHH-mm.md

@@ -0,0 +1,44 @@
+# <bug-name> (Plan)
+
+- **Issue:** <issue>
+- **Parent (optional):** <parent-id>
+- **Owner:** <name>
+- **Last Updated:** <yyyy-MM-ddTHH-mm>
+- **Status:** <template>
+- **Version:** <version_number>
+
+**Fail-closed evidence rule:** Include explicit baseline artifact tasks, final-QA artifact tasks, and coverage-comparison tasks for each in-scope language when policy requires coverage. If any required baseline artifact, QA artifact, or coverage-comparison artifact is missing, the audit verdict must be BLOCKED or INCOMPLETE, never PASS.
+
+**Evidence accounting rule:** Record the expected artifact path or location in each evidence-producing task. Do not mark evidence-backed work complete without the artifact.
+
+
+**Phase 0 — Context & Inputs**
+- [ ] [P0-T1] Link approved spec: <spec link>
+- [ ] [P0-T2] Record branch/commit baseline: <branch/commit>
+- [ ] [P0-T3] List required environment/fixtures/data: <notes>
+
+**Phase 1 — Preparation**
+- [ ] [P1-T1] Confirm scope is locked for this fix (no open spec gaps)
+- [ ] [P1-T2] Sync workspace to target branch and ensure tooling is available
+
+**Phase 2 — Regression Test (must fail first)**
+- [ ] [P2-T1] [expect-fail] Add a small, deterministic regression test in the standard module file (use `tests/bugs/<YYYY>/<issue>-<desc>.py` only if no clear home exists)
+- [ ] [P2-T2] [expect-fail] Run the regression to confirm it fails and captures the repro
+
+**Phase 3 — Minimal Fix**
+- [ ] [P3-T1] Apply the smallest change needed to make the regression test pass; avoid opportunistic refactors
+
+**Phase 4 — Verification Loop**
+- [ ] [P4-T1] Re-run repro and regression test to confirm expected behavior
+- [ ] [P4-T2] Run formatter → linter → type checker → tests; restart loop if any step changes files or fails
+- [ ] [P4-T3] Record baseline, post-change, and comparison artifact paths for each in-scope language where coverage is required
+
+**Phase 5 — Documentation & Status**
+- [ ] [P5-T1] Update spec/issue with outcomes, decisions, and any deviations from scope
+
+**Phase 6 — PR & Handoff**
+- [ ] [P6-T1] Prepare PR notes (summary, risks, validation performed, links to tests) and request review
+
+**Phase 7 — Rollout / Follow-up**
+- [ ] [P7-T1] Capture deployment/rollout notes and post-fix monitoring items
+- [ ] [P7-T2] Record links (issue, PRs, related docs) for traceability

package/resources/feature-templates/bug/potential_bug.md

@@ -0,0 +1,59 @@
+# <bug-name> (Potential Bug)
+
+- Date captured: YYYY-MM-DD
+- Author: name
+- Status: Draft
+
+> Automation note: Keep the section headings below unchanged; the promotion tooling maps each of them into the GitHub bug issue template.
+
+## Summary
+
+One or two sentences on what is broken.
+
+## Environment
+
+- OS/version:
+- Python version:
+- Command/flags used:
+- Data source or fixture:
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened (include key error text).
+
+## Logs / Screenshots
+
+- [ ] Attached minimal logs or screenshot
+- Snippet:
+
+## Impact / Severity
+
+- [ ] Blocker
+- [ ] High
+- [ ] Medium
+- [ ] Low
+
+## Suspected Cause / Notes
+
+Optional early hunches, related changes, or files to inspect.
+
+## Proposed Fix / Validation Ideas
+
+- [ ] Unit coverage areas
+- [ ] Integration scenario to retest
+- [ ] Manual verification notes
+
+## Next Step
+
+- [ ] Promote to GitHub issue (bug-report template)
+- [ ] Move to active fix folder / branch

package/resources/feature-templates/bug/spec.md

@@ -0,0 +1,99 @@
+# <bug-name> (Spec)
+
+- **Issue:** <issue>
+- **Parent (optional):** <parent-id>
+- **Owner:** <name>
+- **Last Updated:** <yyyy-MM-ddTHH-mm>
+- **Status:** <status>
+- **Version:** <version_number>
+
+## Context
+- Summary of the bug and its impact (link to repro/playbook entry).
+- Observed environment(s):
+- Customer impact and severity (who is affected, how often, how bad):
+- First observed date and version(s) impacted:
+
+## Repro & Evidence
+- Steps to reproduce (with data/flags/inputs):
+- Expected vs actual behavior:
+- Logs/screenshots/error snippets:
+- Frequency / determinism (always, intermittent, data-dependent):
+
+## Scope & Non-Goals
+- In scope:
+- Out of scope / non-goals:
+- Explicitly excluded systems, integrations, or datasets:
+
+## Root Cause Analysis
+- Current hypothesis or confirmed root cause:
+- Signals/evidence supporting it:
+- Affected components/modules (paths, services, pipelines):
+
+## Proposed Fix
+
+### Design summary (what changes where):
+
+### Boundaries and invariants to preserve:
+
+### Dependencies or blocked work:
+
+### Implementation strategy (what changes, not sequencing):
+	
+#### Files/modules to change:
+
+#### Functions/classes/CLI commands impacted:
+
+#### Data flow and validation changes:
+
+#### Error handling and logging updates:
+
+#### Rollback/feature-flag considerations (if applicable):
+
+### Technical specifications (interfaces/contracts):
+
+#### Inputs/outputs and formats:
+
+#### Required configuration keys and defaults:
+
+#### Backward-compatibility expectations:
+
+#### Performance constraints (latency/throughput/memory):
+
+## Assumptions, Constraints, Dependencies
+- Assumptions (environment, data, access):
+- Constraints (budget, performance, compatibility):
+- External dependencies (services, libraries, releases):
+
+## Data / API / Config Impact
+- User-facing or API changes:
+- Data or migration considerations:
+- Logging/telemetry updates (if any):
+- Compatibility notes (CLI flags, config schemas, versioning):
+
+## Test Strategy
+- Regression tests to add or update:
+- Unit tests (pytest) for the fixed behavior and boundaries:
+- Edge cases and negative scenarios (invalid inputs, missing data, boundary values):
+- Error handling and logging verification:
+- Coverage impact and targets for changed lines/modules:
+- Toolchain commands to run (format → lint → type-check → test):
+- Manual validation steps (if required):
+
+## Acceptance Criteria
+- [ ] Repro steps now produce the expected behavior in all documented environments.
+- [ ] Regression test(s) added and passing (list file path and test name).
+- [ ] Edge cases and invalid inputs are handled with correct errors or fallbacks.
+- [ ] No unintended behavior changes outside the defined scope.
+- [ ] Required logs/telemetry updated and validated (if applicable).
+- [ ] Performance constraints met or explicitly waived with rationale.
+- [ ] Full toolchain pass completed (format → lint → type-check → test).
+- [ ] Docs/config references updated to match the new behavior.
+
+## Risks & Mitigations
+- Technical or operational risks:
+- Mitigations and rollbacks:
+
+## Rollout & Follow-up
+- Release/rollout steps:
+- Post-fix monitoring or clean-up tasks:
+- Links: issue, PRs, related docs

package/resources/feature-templates/epic/initiative.md

@@ -0,0 +1,43 @@
+# <epic-name> - Initiative Overview
+
+- Issue: #<tracking-issue>
+- Owner: <name>
+- Last Updated: YYYY-MM-DD
+
+## Goal & Outcomes
+
+State the objective and the measurable outcomes for this initiative. Keep it user/impact oriented, not implementation detail.
+
+## Decomposition (Child Features/Workstreams)
+
+- <Workstream A> (Issue #<id>) - `../<child-folder>/`
+- <Workstream B> (Issue #<id>) - `../<child-folder>/`
+- <Workstream C> (Issue #<id>) - `../<child-folder>/`
+
+Dependencies: Describe ordering or coupling between child items (e.g., A → B → C).
+
+## Cross-Cutting Constraints & Assumptions
+
+- Shared behaviors/algorithms that must stay aligned
+- Determinism/performance/compatibility guarantees
+- Data/artifact locations, formats, or tooling expectations
+- Compliance/legal/licensing boundaries
+- Quality gates (tests/lint/type-checks) required across all children
+
+## Milestones & Status
+
+- M1 <Name> - <Not started | In progress | Done> (criteria)
+- M2 <Name> - <Not started | In progress | Done>
+- M3 <Name> - <Not started | In progress | Done>
+- CLI/UX alignment or other cross-initiative milestones
+
+## Initiative-Level Validation
+
+- End-to-end: <Describe end-to-end validation that proves the initiative outcome>
+- Integration: <Cross-layer checks to ensure child workstreams fit together>
+- Determinism/Regression: <What needs to remain stable; how to detect drift>
+- Error handling/Resilience: <Key failure modes and expected handling>
+
+## Notes / Follow-Ups
+
+Capture decisions, risks, and future adjustments to decomposition/milestones.

package/resources/feature-templates/feature/plan.yyyy-MM-ddTHH-mm.md

@@ -0,0 +1,53 @@
+# <feature-name> - Plan
+
+- **Issue:** <issue>
+- **Parent (optional):** <parent-id>
+- **Owner:** <name>
+- **Last Updated:** <yyyy-MM-ddTHH-mm>
+- **Status:** <template>
+- **Version:** <version_number>
+
+## Required References
+
+- General Coding Standards: [`.github/instructions/general-code-change.instructions.md`](../../../../.github/instructions/general-code-change.instructions.md)
+- General Unit Test Policy: [`.github/instructions/general-unit-test.instructions.md`](../../../../.github/instructions/general-unit-test.instructions.md)
+- (Add language-specific policies as needed, e.g. `python-code-change.instructions.md`)
+
+**All work must comply with these policies; do not duplicate their content here.**
+
+## Implementation Plan (Atomic Tasks)
+
+> **Instructions for this section:**
+> - Break work into **Phases** (broad buckets) and **Atomic Tasks** (binary, 5-30 min units).
+> - Use `- [ ] [P#-T#]` for every task.
+> - Start every task with a **strong verb** (Implement, Create, Update, Verify).
+> - No "bucket" tasks like "Refactor module" or "Write tests"; split them into specific, verifiable steps.
+> - **Self-Validating Phases:** Include necessary test creation/update tasks *within* the phase that implements the code. Do not defer verification to a final "Testing" phase.
+> - Include explicit baseline artifact tasks, final-QA artifact tasks, and coverage-comparison tasks for every language in scope when policy requires coverage.
+> - Name the expected artifact path or location in each evidence-producing task's acceptance criteria.
+> - If any required baseline artifact, QA artifact, or coverage-comparison artifact is missing, the audit verdict must be BLOCKED or INCOMPLETE, never PASS.
+
+### Phase 0: Compliance & Context
+- [ ] [P0-T1] Confirm alignment with repo policies by reading `.github/instructions/general-code-change.instructions.md`, `.github/instructions/python-code-change.instructions.md`, `.github/instructions/general-unit-test.instructions.md`, and `.github/instructions/python-unit-test.instructions.md` before touching code
+  - Acceptance: Development log contains policy review timestamp prior to Phase 1 commits
+
+### Phase 1: <Phase Name>
+- [ ] [P1-T1] <Atomic task with strong verb>
+- [ ] [P1-T2] <Atomic task>
+  - Preconditions: <optional>
+  - Acceptance: <optional>
+
+### Phase 2: <Phase Name>
+- [ ] [P2-T1] <Atomic task>
+- [ ] [P2-T2] <Atomic task>
+
+## Test Plan
+
+- Unit: ...
+- Integration: ...
+- Manual/CLI: ...
+- Coverage evidence: list baseline artifact paths, post-change artifact paths, and comparison artifact paths for each in-scope language
+
+## Open Questions / Notes
+
+- ...

package/resources/feature-templates/feature/spec.md

@@ -0,0 +1,66 @@
+# <feature-name> — Spec
+
+- **Issue:** <issue>
+- **Parent (optional):** <parent-id>
+- **Owner:** <name>
+- **Last Updated:** <yyyy-MM-ddTHH-mm>
+- **Status:** <status>
+- **Version:** <version_number>
+
+## Overview
+
+Brief summary of the behavior and scope.
+- Target users/personas and primary use cases:
+- Success metrics or expected impact:
+
+## Behavior
+
+Describe how the feature should behave end-to-end.
+- Main user flow (happy path):
+- Alternate/edge flows:
+- Error handling and recovery behavior:
+
+## Inputs / Outputs
+
+- Inputs (CLI flags, files, env vars)
+- Outputs (artifacts, logs, telemetry)
+- Config keys and defaults:
+- Versioning or backward-compatibility constraints:
+
+## API / CLI Surface
+
+List commands, flags, request/response shapes, and examples.
+- Example invocations with expected outputs (concise):
+- Contracts and validation rules:
+
+## Data & State
+
+Data flow, storage, or state changes introduced by this feature.
+- Data transformations and invariants:
+- Caching or persistence details:
+- Migration or backfill requirements (if any):
+
+## Constraints & Risks
+
+Performance, compatibility, security, rollout constraints.
+- Limits (latency/throughput/memory) and acceptable trade-offs:
+- Security/privacy considerations:
+- Operational/rollout risks and mitigations:
+
+## Implementation Strategy
+
+- Implementation scope (what changes, not sequencing):
+- New classes/functions/commands to add or update:
+- Dependency changes (new/removed packages) and rationale:
+- Logging/telemetry additions and locations:
+- Rollout plan (feature flags, staged deploys, fallback path):
+
+## Definition of Done
+
+- [ ] Acceptance criteria documented and mapped to tests or demos
+- [ ] Behavior matches acceptance criteria in all documented environments
+- [ ] Tests updated/added (unit/integration as applicable)
+- [ ] Edge cases and error handling covered by tests
+- [ ] Docs updated (README, docs/features/active/... links)
+- [ ] Telemetry/logging added or updated (if applicable)
+- [ ] Toolchain pass completed (format → lint → type-check → test)

package/resources/feature-templates/feature/user-story.md

@@ -0,0 +1,42 @@
+# `<feature-name>` — User Story
+
+- Issue: #`<id>`
+- Owner: name
+- Status: Draft | In Progress | Complete
+- Last Updated: YYYY-MM-DD
+
+## Story Statement
+
+- As a ..., I want ..., so that ...
+- As a ..., I want ..., so that ...
+
+## Problem / Why
+
+What customer/user problem does this solve?
+
+## Personas & Scenarios
+
+- Persona: ...
+  - who the user is
+  - what they care about
+  - their constraints
+  - their goals and frustrations
+  - their context and motivations
+- Scenario: ...
+  - A concrete, step-by-step narrative that describes how a user accomplishes a goal in a real-world context using the system.
+  - who is acting?
+  - what triggered the action?
+  - what steps do they take?
+  - what obstacles or decisions occur?
+  - what outcome do they expect?
+
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Non-Goals
+
+Call out what is explicitly excluded from this feature.

package/resources/feature-templates/potential/template.md

@@ -0,0 +1,33 @@
+# <feature-name> (Potential)
+
+- Date captured: YYYY-MM-DD
+- Author: name
+- Status: Draft
+
+## Problem / Why
+
+What need or gap does this idea address?
+
+## Proposed Behavior
+
+What should the feature do at a high level?
+
+## Acceptance Criteria (early draft)
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Constraints & Risks
+
+List notable constraints (performance, compatibility, scope) or risks.
+
+## Test Conditions to Consider
+
+- [ ] Unit coverage areas
+- [ ] Integration scenarios
+- [ ] CLI/API examples
+
+## Next Step
+
+- [ ] Promote to GitHub issue (feature request template)
+- [ ] Create `docs/features/active/<feature-name>/` folder from the template

package/resources/feature-templates/refactor/plan.yyyy-MM-ddTHH-mm.md

@@ -0,0 +1,52 @@
+# <refactor-name> - Refactor Plan
+
+- **Issue:** <issue>
+- **Parent (optional):** <parent-id>
+- **Owner:** <name>
+- **Last Updated:** <yyyy-MM-ddTHH-mm>
+- **Status:** <template>
+- **Version:** <version_number>
+
+## Required References (read, do not restate)
+
+- Coding workflow and standards: [`docs/code-change.instructions.md`](../../code-change.instructions.md)
+- Unit test policy: [`docs/unit-test-policy.md`](../../unit-test-policy.md)
+
+## Strategy
+
+Brief approach to reach the target structure while keeping behavior stable.
+
+Fail-closed evidence rule: include explicit baseline artifact tasks, final-QA artifact tasks, and coverage-comparison tasks for each in-scope language when policy requires coverage. If any required baseline artifact, QA artifact, or coverage-comparison artifact is missing, the audit verdict must be BLOCKED or INCOMPLETE, never PASS.
+
+Evidence accounting rule: record the expected artifact path or location in each evidence-producing task. Do not mark evidence-backed work complete without the artifact.
+
+## Work Breakdown
+
+### Phase 1: Inventory & Plan [0%]
+- [ ] Enumerate current entry points/paths/imports to touch
+- [ ] Confirm invariants and non-goals
+
+### Phase 2: Execute Structural Changes [0%]
+- [ ] Apply moves/renames to reach the target layout
+- [ ] Update imports/tooling/entry points
+- [ ] Remove or redirect legacy paths
+
+### Phase 3: Verification & Cleanup [0%]
+- [ ] Run tests/type checks; fix fallout
+- [ ] Update docs/tasks/initiative references
+- [ ] Final pass for stray references to old locations
+
+## Test Plan
+
+- Unit/Integration: impacted modules and any regression tests for invariants
+- CLI/Workflow: end-to-end commands/tasks expected to remain stable
+- Tooling: lint/type checks after path updates
+- Coverage evidence: list baseline artifact paths, post-change artifact paths, and comparison artifact paths for each in-scope language
+
+## Rollback / Contingency
+
+How to revert or isolate if the refactor breaks downstream consumers (e.g., keep branch snapshot, git move plan).
+
+## Open Questions / Notes
+
+Capture decisions, risks, and follow-ups.

package/resources/feature-templates/refactor/spec.md

@@ -0,0 +1,69 @@
+# <refactor-name> - Refactor Spec
+
+- **Issue:** <issue>
+- **Parent (optional):** <parent-id>
+- **Owner:** <name>
+- **Last Updated:** <yyyy-MM-ddTHH-mm>
+- **Status:** <status>
+- **Version:** <version_number>
+
+## Intent & Outcomes
+
+Why this refactor is needed (maintainability, consistency, scalability) and the desired end-state.
+- Target users/personas impacted (if any) and expected impact:
+- Success metrics or measurable outcomes:
+
+## Invariants (must not change)
+
+List the behaviors, contracts, and external surfaces that must remain identical (CLIs, APIs, outputs, data formats, paths).
+- Performance characteristics to preserve (latency/throughput/memory):
+- Compatibility guarantees (CLI flags, config schemas, versions):
+
+## Scope (structural changes)
+
+- What is being moved/renamed/re-organized
+- Target module/package layout and entry points
+- Any cleanup/removals included
+- New internal boundaries or module ownership changes:
+
+## Non-Goals
+
+What is explicitly out of scope (new behavior, perf changes, UX changes, flags).
+
+## Dependencies / Touchpoints
+
+Upstream/downstream modules, CLIs, data paths, automation, or external consumers that rely on current structure.
+- Required coordination (other teams, CI/CD, release tooling):
+
+## Risks & Mitigations
+
+Call out breakage risks (imports, paths, packaging, tooling) and how you will guard against them.
+- Rollback or fallback strategy:
+
+## Technical Specifications
+
+- Files/modules expected to change:
+- Public interfaces/contracts affected (even if behavior is unchanged):
+- Data flow or validation adjustments:
+- Logging/telemetry updates (if any):
+- Migration or backfill needs (if any):
+
+## Test Strategy
+
+- Regression tests to add or update:
+- Invariant validation tests (ensuring outputs/behavior unchanged):
+- Edge cases and negative scenarios (import/path stability, CLI flags):
+- Error handling and logging verification:
+- Coverage impact and targets for changed lines/modules:
+- Toolchain commands to run (format → lint → type-check → test):
+- Manual validation steps (if required):
+
+## Definition of Done
+
+- [ ] Structure matches this spec; legacy paths retired or redirected
+- [ ] Invariants validated with tests or comparisons
+- [ ] Imports/tooling/entry points updated
+- [ ] Edge cases and error handling verified
+- [ ] Tests, linting, and type checks clean
+- [ ] Docs updated (initiative/README/tasks as needed)
+- [ ] Toolchain pass completed (format → lint → type-check → test)