Skip to content

Commit 4787aa7

Browse files
davidleedavidlee
committed
feat: token cache boot
1 parent 0e680e3 commit 4787aa7

14 files changed

Lines changed: 849 additions & 309 deletions

File tree

‎.spec-driver/backlog/improvements/IMPR-016-add_vector_search_to_memories_artifacts_with_voyageai_sdk/IMPR-016.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
id: IMPR-016
3+
name: add vector search to memories, artifacts with voyageai sdk
4+
created: '2026-03-12'
5+
updated: '2026-03-12'
6+
status: idea
7+
kind: improvement
8+
---
9+
10+
# add vector search to memories, artifacts with voyageai sdk
11+

‎.spec-driver/backlog/issues/ISSUE-050-can_t_tag_requirements/ISSUE-050.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
id: ISSUE-050
3+
name: can't tag requirements
4+
created: '2026-03-10'
5+
updated: '2026-03-10'
6+
status: open
7+
kind: issue
8+
categories: []
9+
severity: p3
10+
impact: user
11+
---
12+
13+
# can't tag requirements
14+

‎.spec-driver/backlog/issues/ISSUE-051-sync_does_not_prune_stale_requirements_from_registry/ISSUE-051.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
id: ISSUE-051
3+
name: sync does not prune stale requirements from registry
4+
created: '2026-03-10'
5+
updated: '2026-03-10'
6+
status: open
7+
kind: issue
8+
categories: []
9+
severity: p2
10+
impact: user
11+
---
12+
13+
# sync does not prune stale requirements from registry
14+
15+
## Observed
16+
17+
`spec-driver sync` (including `--force`) does not remove entries from
18+
`.spec-driver/registry/requirements.yaml` when the corresponding requirement
19+
is deleted from spec markdown.
20+
21+
Orphaned requirements persist silently, polluting coverage checks and
22+
verification gates.
23+
24+
## Expected
25+
26+
Sync should detect requirements present in the registry but absent from their
27+
owning spec and either prune them automatically or surface them as warnings.
28+
29+
## Workaround
30+
31+
Manually delete the stale entry from `requirements.yaml`.
32+
33+
## Provenance
34+
35+
Observed in [davidlee/ligma](https://github.com/davidlee/ligma) during DE-001
36+
(SPEC-001.NF-005 persisted after removal from spec).

‎.spec-driver/backlog/issues/ISSUE-052-create_phase_appends_duplicate_entry_to_ip_phases_list_and_uses_inconsistent_id_format/ISSUE-052.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
id: ISSUE-052
3+
name: create phase appends duplicate entry to IP phases list and uses inconsistent
4+
ID format
5+
created: '2026-03-11'
6+
updated: '2026-03-11'
7+
status: open
8+
kind: issue
9+
categories: []
10+
severity: p2
11+
impact: user
12+
---
13+
14+
# create phase appends duplicate entry to IP phases list and uses inconsistent ID format
15+
16+
## Observed
17+
18+
When an IP already has manually-written phase entries (e.g. `IP-004-P01` through
19+
`IP-004-P04`), running `spec-driver create phase` on that IP:
20+
21+
1. Generates a phase with a different ID format (`IP-004.PHASE-01` vs `IP-004-P01`)
22+
2. Appends the new ID to the IP's `phases:` list without detecting the existing
23+
entries, resulting in duplicates
24+
25+
The agent then has to manually reconcile the phases list every time.
26+
27+
## Expected
28+
29+
- `create phase` should use a single canonical ID format (decide: dotted or hyphenated)
30+
- If the IP already has phase entries, `create phase` should either detect and
31+
reuse the existing convention or warn about the conflict
32+
- Should not append if an equivalent phase already exists
33+
34+
## Provenance
35+
36+
Observed in [davidlee/ligma](https://github.com/davidlee/ligma) during DE-004
37+
IP-004 phase creation. Reported as recurring ("happens every time").

‎.spec-driver/deltas/DE-090-cli_relational_navigation_filters_show_output_and_cross_entity_queries/DE-090.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
id: DE-090
3+
slug: cli_relational_navigation_filters_show_output_and_cross_entity_queries
4+
name: 'Delta - CLI relational navigation: filters, show output, and cross-entity queries'
5+
created: '2026-03-12'
6+
updated: '2026-03-12'
7+
status: draft
8+
kind: delta
9+
aliases: []
10+
relations:
11+
- type: relates_to
12+
target: PROD-010
13+
description: CLI UX improvements for relational navigation
14+
context_inputs: []
15+
applies_to:
16+
specs:
17+
- PROD-010
18+
- SPEC-110
19+
requirements:
20+
- PROD-010.FR-005
21+
---
22+
23+
# DE-090 – CLI relational navigation: filters, show output, and cross-entity queries
24+
25+
```yaml supekku:delta.relationships@v1
26+
schema: supekku.delta.relationships
27+
version: 1
28+
delta: DE-090
29+
revision_links:
30+
introduces: []
31+
supersedes: []
32+
specs:
33+
primary:
34+
- PROD-010
35+
collaborators:
36+
- SPEC-110
37+
requirements:
38+
implements:
39+
- PROD-010.FR-005
40+
updates: []
41+
verifies: []
42+
phases: []
43+
```
44+
45+
## 1. Summary & Context
46+
- **Product Spec(s)**: PROD-010 – CLI UX (reverse relationship queries, filtering)
47+
- **Technical Spec(s)**: SPEC-110 – supekku/cli Specification
48+
- **Implementation Plan**: [IP-090](./IP-090.md)
49+
- **Change Drivers**: Systematic exploration of CLI relational navigation gaps
50+
51+
## 2. Motivation
52+
53+
The CLI has good foundational relational filters (`--related-to`, `--implements`
54+
on `list deltas`; `--spec` on `list requirements/revisions/audits`; `--refs`
55+
column), but coverage is uneven across entity types. Common governance and
56+
navigation questions require manual cross-referencing or multi-command pipelines
57+
that should be single-query operations.
58+
59+
Key pain points:
60+
- "Which deltas implement this spec?" requires `--related-to` (no `--spec` on deltas)
61+
- "Which audit covers this delta?" requires name-substring guessing
62+
- "Which issues relate to this spec?" is not possible
63+
- "Which completed deltas have no audit?" is not possible
64+
- `show spec` output is sparse — no relations, requirements, or reverse lookups
65+
- `show delta` rendered output drops relation types ("- : ISSUE-007")
66+
- `list backlog --json` strips relational fields that `show issue --json` includes
67+
68+
## 3. Scope & Objectives
69+
70+
### P0 — Bugs
71+
1. Fix `show delta` relation type display in rendered output
72+
2. Fix `show spec` to include relations in both rendered and JSON output
73+
3. Make `list plans` resilient to YAML parse errors (skip + warn)
74+
75+
### P1 — Relational filters (extend existing patterns)
76+
4. `list audits --delta <ID>` — audits covering a delta
77+
5. `list revisions --delta <ID>` — revisions from a delta
78+
6. `list requirements --implemented-by <ID>` — requirements a delta implements
79+
7. `list deltas --spec <ID>` — deltas touching a spec (dedicated, consistent with revisions/audits)
80+
8. `list backlog --related-to <ID>` / `list issues --related-to <ID>` — backlog items referencing an entity
81+
82+
### P2 — Richer `show` output
83+
9. `show spec` should summarise requirements (count + optional list) and show related deltas/revisions/audits
84+
10. `show delta` should show linked audit(s) and revision(s) via reverse lookup
85+
11. Consistent JSON schema between `list --json` and `show --json` for backlog items (include relational fields in list output)
86+
87+
### P3 — Governance queries
88+
12. `list deltas --unaudited` — completed deltas with no associated audit
89+
13. `list requirements --unimplemented` — requirements with empty `implemented_by`
90+
91+
### P4 — Graph/neighbourhood view
92+
14. `show <kind> <id> --related` — display all entities referencing or referenced by the target
93+
94+
- **Operational Constraints**: Each priority tier is independently shippable
95+
- **Dependencies**: None
96+
97+
## 4. Out of Scope
98+
- TUI relational navigation (already addressed by DE-087)
99+
- New entity types or schema changes
100+
- Backlog frontmatter schema enforcement (separate concern)
101+
102+
## 5. Approach Overview
103+
- **System Touchpoints**: `supekku/scripts/lib/formatters/`, CLI commands in `supekku/cli/`, registries
104+
- **Key Changes**:
105+
- Formatter fixes for relation type display and spec show output
106+
- New filter flags on existing `list` commands using established patterns
107+
- Reverse-lookup helpers in registries for cross-entity queries
108+
- `--related` flag on `show` commands for neighbourhood view
109+
110+
## 6. Verification Strategy
111+
- **Requirements Coverage**: PROD-010.FR-005 (reverse relationship queries)
112+
- **Acceptance Criteria**:
113+
- All P0 bugs fixed with regression tests
114+
- Each new filter flag has tests and works with `--json`, `--format=tsv`, table output
115+
- `show` output includes relational sections with tests
116+
- Existing tests unbroken
117+
118+
## 7. Risks & Mitigations
119+
- **Risk**: Performance of reverse lookups on large workspaces – *Likelihood*: low – *Impact*: medium – *Mitigation*: Lazy evaluation; existing registry indices
120+
- **Risk**: Scope creep across tiers – *Likelihood*: medium – *Impact*: low – *Mitigation*: Each P-tier is a separate phase; ship incrementally
121+
122+
## 8. Follow-ups & Tracking
123+
- **Future Phases / Deltas**: P4 (graph view) may warrant its own delta if complexity warrants
124+
- **Open Decisions / Questions**: None currently

‎.spec-driver/deltas/DE-090-cli_relational_navigation_filters_show_output_and_cross_entity_queries/DR-090.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
id: DR-090
3+
slug: cli_relational_navigation_filters_show_output_and_cross_entity_queries
4+
name: 'Design Revision - CLI relational navigation: filters, show output, and cross-entity
5+
queries'
6+
created: '2026-03-12'
7+
updated: '2026-03-12'
8+
status: draft
9+
kind: design_revision
10+
aliases: []
11+
owners: []
12+
relations:
13+
- type: implements
14+
target: DE-090
15+
delta_ref: DE-090
16+
source_context: []
17+
code_impacts: []
18+
verification_alignment: []
19+
design_decisions: []
20+
open_questions: []
21+
---
22+
23+
# DR-090 – CLI relational navigation: filters, show output, and cross-entity queries
24+
25+
## 1. Executive Summary
26+
- **Delta**: [DE-090](./DE-090.md)
27+
- **Status**: draft (update when approved)
28+
- **Owners / Team**: <names or teams accountable>
29+
- **Last Updated**: 2026-03-12
30+
- **Synopsis**: <one-liner describing the architectural shift>
31+
32+
## 2. Problem & Constraints
33+
- **Current Behaviour**: <describe pain, instability, or limitation>
34+
- **Drivers / Inputs**: <link research, decisions, audits that justify the work>
35+
- **Constraints / Guardrails**: <operational limits, rollout boundaries, observability, compliance>
36+
- **Out of Scope**: <explicit non-goals, deferred ideas>
37+
38+
## 3. Architecture Intent
39+
- **Target Outcomes**:
40+
- <Outcome 1 tied to requirement/spec>
41+
- <Outcome 2>
42+
- **Guiding Principles**: <service boundaries, coupling choices, failure modes>
43+
- **State Transitions / Lifecycle Impact**: <how lifecycle/status values evolve>
44+
45+
## 4. Code Impact Summary
46+
| Path | Current State | Target State |
47+
| --- | --- | --- |
48+
| `src/example/module.py` | <behaviour today> | <behaviour after change> |
49+
50+
> Capture each affected component with concise before/after statements. Align this table with the `code_impacts` frontmatter entries.
51+
52+
## 5. Verification Alignment
53+
| Verification | Impact | Notes |
54+
| --- | --- | --- |
55+
| VT-XXX | regression | <existing coverage that must be updated> |
56+
| VA-YYY | new | <new artefact or analysis to add> |
57+
58+
> Keep the table in sync with `verification_alignment` metadata so tooling can audit impacts.
59+
60+
## 6. Supporting Context
61+
- **Research**: RC-### – <insight or takeaway>
62+
- **Hypotheses**: PROD-###.HYP-## – <assumption being validated>
63+
- **Related Deltas / Specs**: DE-###, SPEC-### – <traceability notes>
64+
65+
## 7. Design Decisions & Trade-offs
66+
- DEC-### – <decision summary, rationale, consequences>
67+
- <Additional decisions, even if pending approval>
68+
69+
## 8. Open Questions
70+
- [ ] Question text – Owner (@name) – due YYYY-MM-DD
71+
- [ ] …
72+
73+
## 9. Rollout & Operational Notes
74+
- **Migration / Backfill**: <data movements, toggles, sequencing>
75+
- **Observability / Alerts**: <metrics, telemetry changes, dashboards>
76+
- **Recovery / Rollback**: <how to detect bad rollout and undo>
77+
78+
## 10. References & Links
79+
- Diagrams: <link to draw.io/miro>
80+
- Demo / Prototype: <link>
81+
- Additional Reading: <links>
82+
83+
> Keep this document as the living design record for the delta. Update frontmatter fields (`owners`, `code_impacts`, `verification_alignment`, `design_decisions`, `open_questions`) as the design evolves.

0 commit comments

Comments
 (0)