diff --git a/TODO.md b/TODO.md index 7ce22cb..64fb1a6 100644 --- a/TODO.md +++ b/TODO.md @@ -2,6 +2,11 @@ ## Active tickets +- [ ] [`ticket-031`](project/ticket-031/README.md) — restore the semantic + similarity score contribution dropped during the linker split. Current + state: `IN_PROGRESS / VALIDATION`; one production file changed, no threshold + or test expectation changes, and all seven targeted failures are removed. + - [ ] [`ticket-019`](project/ticket-019/README.md) — publish the dependency-free Python SDK as the root PyPI distribution `todo2code` through `goal -a`, with one root `pyproject.toml` and SDK-only artifacts. Current state: diff --git a/project/TICKETS.md b/project/TICKETS.md index 071ccc8..a5cc99d 100644 --- a/project/TICKETS.md +++ b/project/TICKETS.md @@ -27,4 +27,5 @@ of `project/README.md`, which remains a generated technical-analysis artifact. | **ticket-019** | [`README.md`](./ticket-019/README.md) | [`preprompt.md`](./ticket-019/preprompt.md) | - | [`ai-codex.md`](./ticket-019/ai-codex.md) | [`ai-codex-logs.txt`](./ticket-019/ai-codex-logs.txt) | [`changelog.md`](./ticket-019/changelog.md) | | **ticket-020** | [`README.md`](./ticket-020/README.md) | [`preprompt.md`](./ticket-020/preprompt.md) | - | [`ai-codex.md`](./ticket-020/ai-codex.md) | [`ai-codex-logs.txt`](./ticket-020/ai-codex-logs.txt) | [`changelog.md`](./ticket-020/changelog.md) | | **ticket-022** | [`README.md`](./ticket-022/README.md) | [`preprompt.md`](./ticket-022/preprompt.md) | - | [`ai-codex.md`](./ticket-022/ai-codex.md) | [`ai-codex-logs.txt`](./ticket-022/ai-codex-logs.txt) | [`changelog.md`](./ticket-022/changelog.md) | +| **ticket-031** | [`README.md`](./ticket-031/README.md) | [`preprompt.md`](./ticket-031/preprompt.md) | - | [`ai-codex.md`](./ticket-031/ai-codex.md) | [`ai-codex-logs.txt`](./ticket-031/ai-codex-logs.txt) | [`changelog.md`](./ticket-031/changelog.md) | diff --git a/project/ticket-031/README.md b/project/ticket-031/README.md new file mode 100644 index 0000000..12a8d91 --- /dev/null +++ b/project/ticket-031/README.md @@ -0,0 +1,67 @@ +# Ticket 031: Restore semantic similarity contribution after linker refactor + +- **ID**: ticket-031 +- **Owner**: unresolved:human +- **Status**: IN_PROGRESS +- **Workflow state**: VALIDATION +- **Created**: 2026-08-04 + +## Goal and scope + +Restore the semantic score contribution accidentally dropped while +`scorePair` was split into focused helpers. The helper still computes and +records object/text similarity, but the caller no longer adds its numeric +value to the aggregate score. Exact path evidence therefore stops at `0.28` +or `0.41` and valid cross-source relations fall below the `0.42` threshold. + +This is a bounded regression repair, not a change to the scoring model. The +architecture remains: candidate selection in `linker-candidates.ts`, scoring +in `linker.ts`, and relation direction in `linker-relations.ts`. Only +`src/graph/linker.ts` may change. No threshold, fixture, gold expectation or +generated analysis artifact may be edited. Expected implementation time is +under 30 minutes. + +## Planned changed paths + +- `src/graph/linker.ts`: add the already computed object-similarity value to + the aggregate score exactly once. +- `project/ticket-031/**`, `TODO.md`, `project/TICKETS.md`: intent and evidence. + +## Acceptance criteria + +- [x] AC-01: Scope is approved by a human owner. +- [x] AC-02: `scorePair` adds object/text similarity to the aggregate score and + continues to expose the same value as `textScore`. +- [x] AC-03: The shared-path plan/AST and configuration/document regression + tests pass without lowering the `0.42` relation threshold. +- [x] AC-04: The versioned gold evaluation returns to its accepted precision, + recall, known-gap and v1-compatibility results. +- [x] AC-05: The full suite reduces by the seven linker-related failures; no + unrelated test or fixture is weakened. +- [x] AC-06: Clean build, focused tests, `git diff --check` and governance are + recorded with inherited blockers kept separate. + +## Participants + +- Human participant: unresolved; no user-* file was created by this script. +- Agent participant: [ai-codex.md](ai-codex.md) + +## Approval boundary + +- Current state: `IN_PROGRESS / VALIDATION` after implementing and testing the + bounded repair. +- Chat approval authorizes this interactive implementation only. +- Trusted merge evidence still requires an independent protected review or + signed attestation bound to the final head SHA. + +## Validation evidence + +- `npm run build`: PASS. +- Focused AST, linker-pairing and gold evaluation: 27 passed, 0 failed. +- Full fresh suite: 338 tests, 333 passed, 4 failed and one skipped. The seven + linker failures are gone. The remaining failures are the three separately + diagnosed communication regressions plus the confidence-hierarchy test + repaired independently by ticket-030/PR #7. +- `git diff --check`: PASS. +- `make governance`: reports only the four inherited ticket-018/ticket-019 + diagnostics; ticket-031 adds no scope or workstream finding. diff --git a/project/ticket-031/ai-codex-logs.txt b/project/ticket-031/ai-codex-logs.txt new file mode 100644 index 0000000..ee40dd0 --- /dev/null +++ b/project/ticket-031/ai-codex-logs.txt @@ -0,0 +1,12 @@ +2026-08-04 planning +- Fresh base `caf6551`: build PASS; full suite 338 total, 327 pass, 10 fail, 1 skip. +- Seven failures trace to one omission: `scoreObjectSimilarity(...)` is computed but not added to aggregate `score` after the linker split. +- No production source edited; state remains `WAIT_FOR_APPROVAL`. +- Human response `kontynuuj` authorized the bounded ticket-031 implementation; + transitioned to `IN_PROGRESS / EDIT`. +- `npm run build`: PASS. +- Focused `ast`, `linker-pairing`, `gold-evaluation`: PASS (27/27). +- Fresh full suite: 338 total, 333 pass, 4 fail, 1 skip; all seven linker + regressions removed. Remaining: three communication tests and ticket-030. +- `git diff --check`: PASS. +- `make governance`: four inherited ticket-018/ticket-019 errors, no ticket-031 finding. diff --git a/project/ticket-031/ai-codex.md b/project/ticket-031/ai-codex.md new file mode 100644 index 0000000..918126c --- /dev/null +++ b/project/ticket-031/ai-codex.md @@ -0,0 +1,42 @@ +--- +participant-id: agent:codex +participant: codex +role: agent +ticket: ticket-031 +--- +# Participant: codex (AI agent) + +## Understanding + +The refactor preserved `scoreObjectSimilarity(...)` and its evidence basis but +assigned its return value only to `objectSimilarity`; the aggregate `score` +never receives it. This single semantic omission explains seven fresh-suite +failures: two direct linker cases, the AST integration case and four gold +evaluation cases. Restoring the addition is safer than changing thresholds or +test expectations because it recreates the pre-refactor algorithm. + +## Execution plan + +1. Wait for explicit human approval; do not edit production source beforehand. +2. Add the computed similarity contribution exactly once in `scorePair`. +3. Run build plus focused AST, linker-pairing and gold-evaluation tests. +4. Run the full suite and verify that only the three separately diagnosed + communication failures remain. +5. Run diff/scope checks and governance; publish only with truthful evidence. + +## Actual changes + +- The human explicitly approved ticket-031 by replying `kontynuuj`; the + interactive implementation may enter `EDIT`. +- Restored the pre-refactor scoring contract in `src/graph/linker.ts`: raw + similarity remains available to relation classification, while its weighted + `0.48` contribution is added exactly once to the aggregate score. +- Clean build and all 27 focused AST/linker/gold tests pass. The full suite no + longer contains any of the seven linker failures and stops only on three + communication regressions plus ticket-030's independently repaired test. + +## Blockers + +- Repository governance already has four unrelated ticket-018/ticket-019 + blockers; ticket-031 must not rewrite them. +- Trusted merge approval for the final head SHA is still required. diff --git a/project/ticket-031/changelog.md b/project/ticket-031/changelog.md new file mode 100644 index 0000000..64eb77b --- /dev/null +++ b/project/ticket-031/changelog.md @@ -0,0 +1,16 @@ +# Ticket Changelog (ticket-031) + +## [0.1.0] - 2026-08-04 + +- Initial governance scaffold created. +- No human participant identity or content was generated. +- Renumbered the unpublished scaffold from 023 to 031 because remote PR #3 + already owns ticket-023. +- Documented the pre-implementation regression evidence and bounded repair. + +## [0.2.0] - 2026-08-04 + +- Restored raw object/text similarity as relation-classification evidence and + its weighted contribution to the aggregate linker score. +- Removed seven fresh-suite regressions without changing thresholds, fixtures + or gold expectations; focused verification passes 27/27. diff --git a/project/ticket-031/intent.json b/project/ticket-031/intent.json new file mode 100644 index 0000000..d19d847 --- /dev/null +++ b/project/ticket-031/intent.json @@ -0,0 +1,17 @@ +{ + "schema": "new-project.intent/v2", + "ticket": "ticket-031", + "summary": "Restore semantic similarity contribution after linker refactor", + "workstream": "core-dsl", + "allowedPaths": [ + "src/graph/linker.ts", + "project/ticket-031/**", + "TODO.md", + "project/TICKETS.md" + ], + "forbiddenPaths": ["project/ticket-*/user-*.md"], + "stacks": ["node"], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null +} diff --git a/project/ticket-031/preprompt.md b/project/ticket-031/preprompt.md new file mode 100644 index 0000000..0c52ee1 --- /dev/null +++ b/project/ticket-031/preprompt.md @@ -0,0 +1,8 @@ +# Ticket preprompt + +- **Task ID**: ticket-031 +- **Task title**: Restore semantic similarity contribution after linker refactor +- **Created**: 2026-08-04T12:07:14Z + +Keep executable implementation outside this governance/evidence directory. +Read a human-owned user-*.md file only when one exists. diff --git a/src/graph/linker.ts b/src/graph/linker.ts index 24eb08e..57a8c37 100644 --- a/src/graph/linker.ts +++ b/src/graph/linker.ts @@ -151,6 +151,7 @@ function scorePair( score += scoreSharedPath(left, right, resolvableBasenames, basis); score += scoreSameAction(left, right, basis); const objectSimilarity = scoreObjectSimilarity(leftKeywords, rightKeywords, basis); + score += objectSimilarity * 0.48; score += scoreSharedTopics(left, right, leftKeywords, rightKeywords, basis); score += scoreSourceKindPenalty(left, right); return { @@ -215,7 +216,7 @@ function scoreObjectSimilarity( : 0; if (objectSimilarity >= 0.2) { basis.push(`text_similarity:${objectSimilarity.toFixed(3)}`); - return objectSimilarity * 0.48; + return objectSimilarity; } return 0; }