Skip to content

Commit 5c8e431

Browse files
committed
docs(task): split implementation audit out of post-split cleanup
- move implementation-audit notes into a separate task directory - keep post-split-cleanup focused on SVC v9.3 docs adoption - note that some audit mismatches may come from outdated docs or local guides
1 parent 9b31773 commit 5c8e431

File tree

4 files changed

+120
-62
lines changed

4 files changed

+120
-62
lines changed
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Implementation Audit Scope Boundary
2+
3+
## Purpose
4+
5+
Record the implementation drifts discovered while checking `docs/30-unit-tdd/business-pipeline-and-authority.md` and related local guides against code, in a task that is explicitly separate from `core-py-post-split-cleanup`.
6+
7+
## Decision
8+
9+
This task is a separate follow-up.
10+
11+
`core-py-post-split-cleanup` remains a SVC v9.3 adoption task about shared baseline consumption, Unit TDD admission, and local `AGENTS.md` strengthening.
12+
13+
Any code changes or implementation verification work should happen here instead of being folded back into that post-split cleanup task.
14+
15+
## Important Caution
16+
17+
Not every issue found during the audit should be assumed to be a code bug. Some apparent mismatches may come from outdated docs, stale local guides, or legacy notes that no longer describe the current implementation correctly.
18+
19+
So every follow-up item below must be re-verified before code changes are made. The decision shape should be:
20+
21+
- code is wrong and should change, or
22+
- docs / local guides are outdated and should change, or
23+
- both drifted and need to be realigned together
24+
25+
## Why
26+
27+
The drifts found during implementation review are real signals, but they are not automatically durable-doc placement work.
28+
29+
Under SVC v9.3, code bugs and legacy implementation seams should not be "fixed" by rewriting durable docs to mirror the bug. They should either:
30+
31+
- be corrected in code and tests in a separate execution task, or
32+
- be reclassified as documentation drift if the code is actually the more current source of truth
33+
34+
## Audit Leads
35+
36+
### 1. Embedding upsert call shape
37+
38+
- `app/business/info_base/block.py` currently calls `EmbeddingManager.upsert_block_embedding(...)` with positional arguments that appear not to match the current signature in `app/business/sink/embedding.py`.
39+
- This may be a real implementation bug, or a sign that the documented/assumed call contract needs re-verification.
40+
41+
### 2. Extension running-state checks
42+
43+
- `app/business/extension/main.py` checks `RUNNING_EXTENSIONS` using the extension class object, while the registry is keyed by extension ID.
44+
- This looks like a runtime lifecycle bug, but should still be re-verified against the intended registry contract before changing code.
45+
46+
### 3. Legacy resolver/storage API remnants
47+
48+
- several built-in resolvers still look shaped for older storage APIs or incomplete resolver contracts
49+
- this includes missing/legacy methods in built-in resolver files and stale references to storage helpers that no longer match the current storage manager shape
50+
- part of this may be code drift, part of it may be local guide / note drift
51+
52+
### 4. Source scheduling remains undecided
53+
54+
- the current dual-path source scheduling situation was reconfirmed
55+
- but the scheduling cleanup decision remains a separate design/execution question and should not be silently collapsed into this audit
56+
57+
## Explicit Non-Actions
58+
59+
- do not change `docs/30-unit-tdd/` to normalize temporary broken behavior into durable architecture
60+
- do not rewrite local `AGENTS.md` to preserve a bug as if it were stable truth
61+
- do not assume every mismatch is a code bug before re-checking whether the docs are outdated
62+
63+
## Follow-Up Shape
64+
65+
If this work proceeds later, split it into separate execution slices such as:
66+
67+
1. code/task for embedding and extension lifecycle correctness
68+
2. code/task for resolver/storage legacy cleanup
69+
3. separate decision task for source scheduling convergence
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Status
2+
3+
## Purpose
4+
5+
This directory holds the implementation-audit follow-up that was split out of `tasks/core-py-post-split-cleanup/`.
6+
7+
## Current State
8+
9+
Status: `not started; audit notes separated from post-split cleanup scope`
10+
11+
## Why It Was Split Out
12+
13+
`core-py-post-split-cleanup` is about applying SVC v9.3 to `core-py` through:
14+
15+
- shared baseline consumption
16+
- Unit TDD admission
17+
- local `AGENTS.md` strengthening
18+
- routing / setup doc cleanup
19+
20+
Implementation drift work would make that task boundary muddy, so it now lives here.
21+
22+
## Important Caution
23+
24+
Some issues noticed during the audit may be true code bugs, but some may only be symptoms of outdated docs or stale local guides. Re-verify each item before changing code.
25+
26+
## Read Order
27+
28+
1. `tasks/core-py-business-pipeline-implementation-audit/STATUS.md`
29+
2. `tasks/core-py-business-pipeline-implementation-audit/50-implementation-audit-scope-boundary.md`
30+
3. `docs/30-unit-tdd/business-pipeline-and-authority.md`
31+
4. relevant local guides under `app/business/**/AGENTS.md`
32+
5. target implementation files in `app/business/**`
33+
34+
## Scope Reminder
35+
36+
This task is the correct place for any future execution work around:
37+
38+
- embedding upsert correctness
39+
- extension running-state bookkeeping
40+
- resolver/storage legacy drift
41+
- re-verification of whether mismatches are code drift or doc drift

tasks/core-py-post-split-cleanup/50-implementation-audit-scope-boundary.md

Lines changed: 0 additions & 56 deletions
This file was deleted.

tasks/core-py-post-split-cleanup/STATUS.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,15 @@ Admitted structure:
4545

4646
Local `docs/00-meta/` was explicitly **not** admitted for `core-py` at this stage.
4747

48-
### Implementation Audit Boundary
48+
### Implementation Follow-Up Split
4949

50-
An implementation audit against business-pipeline docs found real code drifts, but they are explicitly left in `tasks/` and out of scope for this cleanup slice:
50+
Implementation audit work is no longer tracked inside this cleanup slice.
5151

52-
- see `50-implementation-audit-scope-boundary.md`
52+
If implementation verification or code changes are needed later, use:
53+
54+
- `tasks/core-py-business-pipeline-implementation-audit/`
55+
56+
Some mismatches noticed during the audit may be code bugs, but some may also come from outdated docs or local guides, so that follow-up must re-verify both sides before changing code.
5357

5458
## What Was Explicitly Rejected
5559

@@ -66,9 +70,8 @@ These remain tactical or unstable and should stay out of `docs/30-unit-tdd/` unl
6670
2. `tasks/core-py-post-split-cleanup/00-meta.md`
6771
3. `tasks/core-py-post-split-cleanup/30-phase-3-4-execution-output.md`
6872
4. `tasks/core-py-post-split-cleanup/40-phase-5-meta-gap-decision.md`
69-
5. `tasks/core-py-post-split-cleanup/50-implementation-audit-scope-boundary.md`
70-
6. `docs/30-unit-tdd/business-pipeline-and-authority.md`
71-
7. relevant local guides under `app/business/**/AGENTS.md`
73+
5. `docs/30-unit-tdd/business-pipeline-and-authority.md`
74+
6. relevant local guides under `app/business/**/AGENTS.md`
7275

7376
## Resume Conditions
7477

@@ -84,6 +87,7 @@ Only reopen this task if one of these happens:
8487
These are not required to consider this task complete, but are the most plausible next work:
8588

8689
- audit whether `app/business/AGENTS.md` should become thinner now that routing is stronger below it
90+
- use `tasks/core-py-business-pipeline-implementation-audit/` if implementation-vs-doc drift needs follow-up
8791
- revisit source scheduling only when the TODO in `app/business/source/main.py` is actually being resolved
8892
- revisit `docs/30-unit-tdd/` only if another slow-moving structural truth clearly survives locality
8993

0 commit comments

Comments
 (0)