Skip to content

Commit 761fee8

Browse files
bntvllntbntvllnt
committed
chore(specs): archive shipped specs to specs/shipped, add backlog specs
- mcp-only (shipped 2026-03-03, PR #3), cli-mode (shipped 2026-03-12, PR #16), config-rules-engine (shipped 2026-06-10, PR #42) moved to specs/shipped with status frontmatter + history.log entries - add three 2026-04-29 backlog specs (module-depth, find-seams, forces signals)
1 parent 795edd9 commit 761fee8

7 files changed

Lines changed: 517 additions & 2 deletions

‎specs/backlog/2026-04-29-add-analyze-module-depth.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Add analyze_module_depth tool with CLI parity
3+
status: backlog
4+
created: 2026-04-29
5+
estimate: 1d
6+
tier: standard
7+
---
8+
9+
# Add analyze_module_depth tool with CLI parity
10+
11+
## Goal
12+
Add a focused tool for ranking modules by architectural depth.
13+
14+
## Scope
15+
Add both interfaces:
16+
- MCP tool: `analyze_module_depth`
17+
- CLI command: `module-depth`
18+
19+
## Output
20+
For each module return:
21+
- `path`
22+
- `interfaceSize`
23+
- `implementationSize`
24+
- `depthScore`
25+
- `leverageScore`
26+
- `localityScore`
27+
- `verdict`: `DEEP | SHALLOW | MIXED`
28+
- short `evidence[]`
29+
30+
## Heuristics
31+
- **Interface size**: exported symbols, public entry points, config surface
32+
- **Implementation size**: internal files/symbols/LOC hidden behind the public surface
33+
- **Depth score**: hidden behavior divided by interface cost
34+
- **Leverage score**: useful behavior reused by many callers
35+
- **Locality score**: change and knowledge concentrated in one place
36+
37+
## Acceptance Criteria
38+
- MCP tool returns ranked modules with stable JSON shape
39+
- CLI command supports table output and `--json`
40+
- command/tool support `--limit` / `limit`
41+
- docs updated in `docs/mcp-tools.md` and `docs/cli-reference.md`
42+
- tests cover one deep-module example and one shallow-module example
43+
44+
## Notes
45+
This should be a narrow, high-signal tool. Avoid mixing in seam detection or force-analysis summary.

‎specs/backlog/2026-04-29-add-find-seams-and-adapters.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Add find_seams tool and adapter detection with CLI parity
3+
status: backlog
4+
created: 2026-04-29
5+
estimate: 1d
6+
tier: standard
7+
---
8+
9+
# Add find_seams tool and adapter detection with CLI parity
10+
11+
## Goal
12+
Help agents find where behavior can vary and which concrete adapters exist.
13+
14+
## Scope
15+
Add both interfaces:
16+
- MCP tool: `find_seams`
17+
- CLI command: `seams`
18+
19+
## Output
20+
Return:
21+
- `seams[]`
22+
- `name`
23+
- `contract`
24+
- `callers`
25+
- `adapters[]`
26+
- `status`: `HYPOTHETICAL | REAL | LEAKY`
27+
- `evidence[]`
28+
- `adapterPatterns[]`
29+
- `summary`
30+
31+
## Rules
32+
- **Hypothetical seam**: one adapter behind a contract
33+
- **Real seam**: two or more adapters behind a contract
34+
- **Leaky seam**: callers know adapter-specific details they should not need to know
35+
36+
## Detection Signals
37+
- shared interface/type used by multiple implementations
38+
- sibling files with same role but different backing dependencies
39+
- injected dependencies or provider-style construction
40+
- duplicated exported API shape across files
41+
42+
## Acceptance Criteria
43+
- MCP tool returns seam/adapter analysis in JSON
44+
- CLI command prints concise seam summaries and supports `--json`
45+
- every seam includes evidence for why it was detected
46+
- docs updated in `docs/mcp-tools.md` and `docs/cli-reference.md`
47+
- tests cover one hypothetical seam and one real seam case
48+
49+
## Notes
50+
Prefer confidence + evidence over aggressive detection. False positives will reduce trust quickly.

‎specs/backlog/2026-04-29-extend-analyze-forces-architecture-signals.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Extend analyze_forces with architecture signals
3+
status: backlog
4+
created: 2026-04-29
5+
estimate: 1d
6+
tier: standard
7+
---
8+
9+
# Extend analyze_forces with architecture signals
10+
11+
## Goal
12+
Make `analyze_forces` more useful for architecture review by adding simple derived signals instead of only cohesion/tension/extraction output.
13+
14+
## Scope
15+
Update both interfaces:
16+
- MCP: extend existing `analyze_forces`
17+
- CLI: extend existing `forces` command
18+
19+
## Add
20+
- `shallowModules[]`
21+
- `deepModules[]`
22+
- `seamCandidates[]`
23+
- `localityRisks[]`
24+
25+
## Heuristics
26+
- **Shallow module**: interface surface is large relative to hidden behavior
27+
- **Deep module**: small public surface, large hidden behavior, reused by many callers
28+
- **Seam candidate**: clear interface point where behavior could vary
29+
- **Locality risk**: understanding or changing one concept requires bouncing across many files
30+
31+
## Acceptance Criteria
32+
- `analyze_forces` returns the new fields in MCP JSON
33+
- `forces --json` returns the same fields
34+
- human CLI output prints short sections for shallow/deep/seam/locality
35+
- existing force analysis output remains intact
36+
- docs updated in `docs/mcp-tools.md` and `docs/cli-reference.md`
37+
- tests cover at least one shallow-module and one locality-risk case
38+
39+
## Notes
40+
Keep heuristics simple and explainable. Every flagged item should include evidence, not just a score.

‎specs/history.log‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
2026-02-18 | shipped | 3d-code-mapper-v1 | 10h→2h | 1d | 3D codebase visualizer with 6 views, 6 MCP tools, 75 tests
22
2026-03-02 | shipped | mcp-parity-readme-sync | 3h→2h | 1d | 100% MCP-REST parity: +2 tools, enhanced 3 tools, 15 tool descriptions, README sync, 21 new tests
3+
2026-03-03 | shipped | mcp-only | 3h→- | - | Dropped web UI & REST API — MCP stdio only. PR #3. (archived retroactively)
34
2026-03-11 | shipped | fix-dead-export-false-positives | 2h→1.5h | 1d | Fix 33% false positive rate: merge duplicate imports, include same-file calls, call graph consumption. 8 regression tests.
45
2026-03-11 | shipped | fix-error-handling | 1h→0.5h | 1d | Consistent impact_analysis error handling, LOC off-by-one fix, empty file guard. 17 regression tests.
56
2026-03-11 | shipped | fix-metrics-test-files | 2h→1.5h | 1d | Exclude test files from coverage/coupling metrics, isTestFile detection, coupling formula fix. 19 regression tests.
67
2026-03-11 | shipped | feat-metric-quality | 3h→2h | 1d | LEAF verdict for single-file modules, tension suppression for type hubs/entry points, file_context path normalization. 20 regression tests.
8+
2026-03-12 | shipped | cli-mode | 8h→- | - | CLI parity with MCP: 15 commands, shared core extraction, AGENTS.md + llms.txt + cli-reference docs. PR #16. (archived retroactively)
79
2026-05-30 | shipped | feat-agent-adoption-init | 3h→1h | 1d | `init` command: idempotent managed-block instructions for 6 agents + portable skill + registry SKILL.md. 18 tests, docs + CHANGELOG. PR #34.
10+
2026-06-10 | shipped | config-rules-engine | -→- | - | Declarative config + ESLint-style rules engine + `check` command CI gate. PR #42. (archived retroactively)

specs/active/2026-03-03-mcp-only.md renamed to specs/shipped/2026-03-03-mcp-only.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: Drop Web UI & REST API — MCP Only
3-
status: active
3+
status: shipped
4+
shipped: 2026-03-03
45
created: 2026-03-03
56
estimate: 3h
67
tier: standard

0 commit comments

Comments
 (0)