Skip to content

Commit 21f7c58

Browse files
bntvllntbntvllnt
authored
chore: housekeeping — gitignore local artifacts, archive shipped specs (#46)
## Summary Working-tree housekeeping batch: **.gitignore** — three groups added: - analysis + coverage artifacts (`.code-visualizer/`, `coverage/`) - local agent state (`.claude/`) - self-dogfood `init` outputs stay local, consistent with #35 being closed unmerged (`.cursor/`, `.pi/`, `GEMINI.md`, `CONVENTIONS.md`, `.github/copilot-instructions.md`) **specs/** — archive shipped, commit backlog: - `mcp-only` → shipped (2026-03-03, #3) - `cli-mode` → shipped (2026-03-12, #16) — was untracked despite all 10 scope items done - `config-rules-engine` → shipped (2026-06-10, #42) - status frontmatter updated + 3 `history.log` entries (marked *archived retroactively*; actuals unknown, left as `-`) - 3 untracked 2026-04-29 backlog specs committed (module-depth, find-seams, forces signals) Docs/config only — no source changes. ## Not touched (follow-up decision) 7 remaining `specs/active/` entries from the pre-MCP-only UI era (analytics-v2, nextjs-migration, e2e-playwright, group-metrics-legend, agent-intelligence-roadmap, symbol-level-ui, group-spatial-clustering) look obsolete (dropped, not shipped) — archiving them to `specs/dropped/` needs a judgment call per spec.
1 parent 8cd099d commit 21f7c58

8 files changed

Lines changed: 531 additions & 2 deletions

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,17 @@ next-env.d.ts
1010
.vllnt/
1111
test-results/
1212
scripts/
13+
14+
# analysis + coverage artifacts
15+
.code-visualizer/
16+
coverage/
17+
18+
# local agent state
19+
.claude/
20+
21+
# self-dogfood `init` outputs stay local (PR #35 closed unmerged)
22+
.cursor/
23+
.pi/
24+
GEMINI.md
25+
CONVENTIONS.md
26+
.github/copilot-instructions.md

‎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)