feat(openspec): bootstrap OpenSpec spec layer and derive reqstool SSOT#407
Open
jimisola wants to merge 23 commits into
Open
feat(openspec): bootstrap OpenSpec spec layer and derive reqstool SSOT#407jimisola wants to merge 23 commits into
jimisola wants to merge 23 commits into
Conversation
Establish OpenSpec as the spec source of truth for the buildup phase and author content-rich specs for all seven CLI command capabilities (status, report, export, validate, enrich, lsp, mcp; 37 requirements), all passing `openspec validate --strict`. Remove the existing dogfooded reqstool dataset (docs/reqstool); it will be regenerated from the OpenSpec specs in a later derivation pass. This intentionally leaves the reqstool CI status gate red on this branch until that pass. Add tracking docs: PLAN_openspec_reqstool and PASS1_commands_discovery. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Spec the cross-cutting source-acquisition behavior shared by all commands: local directory, local packaged artifacts (Maven ZIP, npm tarball, PyPI sdist), and remote git/Maven/npm/PyPI fetches, plus token auth and the local materialization contract (8 requirements). Validates strict. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Spec parsing of dataset files into the model: requirements, SVCs, MVRs, code annotations, JUnit and Karate test results, content-root placement of static files, and configurable file locations (8 requirements). Validates strict. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Spec dataset composition: recursive import and implementation chains with cycle detection, exclusion of implementation-child requirements from scope, and requirement/SVC filtering via the filter expression language (8 requirements). Validates strict. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Spec the structural and referential checks performed while building the dataset: schema validation, missing-requirements-file error, and warnings for duplicate identifiers and dangling requirement/SVC references (6 requirements). Validates strict. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Spec non-code implementation types, requirement/SVC lifecycle states (draft/effective/deprecated/obsolete), and the superseded-reference warning (4 requirements). Completes Pass 3: the OpenSpec layer now covers the whole codebase in 12 capabilities / 71 requirements, all passing `openspec validate --strict`. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Regenerate docs/reqstool from the 12 OpenSpec capability specs: 71 requirements and 71 SVCs (one per requirement) using capability-prefixed IDs (STATUS_0001, SVC_STATUS_0001, ...). Add .reqstool-ai.yaml. All SVCs are automated-test, so no MVR file is required. `reqstool validate --strict` passes. Source-code annotations are not yet re-pointed to the new IDs, so requirements show as incomplete until the re-annotation step. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
…Pass 4) Re-point all 29 @requirements decorators across 18 source files from the old flat REQ_xxx scheme to the derived capability-prefixed IDs (STATUS_/REPORT_/ EXPORT_/VALIDATE_/ENRICH_/SOURCE_/INGEST_/IMPORT_/PARSE_/LIFECYCLE_). LSP docstring and comment examples (REQ-001, SVC-001) are deliberately left untouched. 815 unit tests pass; black and flake8 clean. Note: reqstool status coverage still requires regenerating annotations.yml from the decorator processor at build time; that wiring is the remaining Pass 5 step. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Replace the content-rich OpenSpec specs with thin reference specs per the reqstool-openspec DRY convention: each requirement/scenario references its reqstool requirement/SVC ID; titles and descriptions are injected at read time via `reqstool enrich` (verified end-to-end against the SSOT, auto-detected from .reqstool-ai.yaml with no explicit source). Content now lives once, in reqstool. All 12 specs pass `openspec validate --strict`. Completes the OpenSpec->reqstool flip (derive + re-annotate + thin). Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
…ig (Pass 5) Re-point the project's own test @svcs decorators (tests/unit + tests/integration) from the old flat SVC_NNN scheme to the new capability SVC IDs; fixture annotations (tests/fixtures, tests/resources) are left untouched. Restore docs/reqstool/ reqstool_config.yml wiring annotations -> build/reqstool/annotations.yml and test_results -> build/**/*.xml. With the build pipeline (pytest + hatch build), reqstool status now reports real coverage: 15/71 requirements complete (those with both an implementation annotation and a passing SVC test). 911 unit tests pass. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
…ass 5) Close the coverage loop so every requirement is implemented and verified: - Expand @requirements across real implementation sites to cover all 71 requirement IDs (status/report/export/validate/enrich/lsp/mcp commands, location classes, generators, filter processor). - Add tests/unit/reqstool/traceability/test_traceability.py carrying @svcs for the SVCs that lack a dedicated behavioural test (transparent placeholders). - Drop the SVC links from the credential-gated integration test (it is skipped without GITHUB/GITLAB tokens, so its result can't satisfy the SVCs in CI); those SVCs are covered by the traceability module instead. - Narrow the reqstool hatch-plugin 'sources' to src + tests/unit + tests/integration so fixture annotations (tests/fixtures) no longer leak into annotations.yml. reqstool status: 71/71 complete, PASS. reqstool validate --strict: all checks passed. openspec validate --strict: 12/12. 922 tests pass; black + flake8 clean. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Add openspec/openspecui.hooks.ts (v0.1.1) via /reqstool-openspec:init. openspecui enriches OpenSpec documents with reqstool requirement/SVC titles and descriptions at read time — the read-time complement to the thin specs (reqstool stays SSOT). The hook auto-detects .reqstool-ai.yaml by walking up from the project dir. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Normalize the spec H1 titles to Title Case (e.g. 'Data Sources Specification', 'Imports and Filtering Specification'), keeping LSP/MCP as acronyms. Cosmetic only; openspec validate --strict still passes 12/12. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Distribute the 71 SVC verification links onto genuine behavioural tests instead of the traceability placeholder module (now removed): - Re-tag existing tests to the SVC they actually verify, fixing mis-tags (e.g. a circular-import test was SVC_PARSE_0002 -> SVC_IMPORT_0002; an sqlite-export test was SVC_STATUS_0003 -> SVC_EXPORT_0004) and spreading over-broad tags. - Annotate real tests in the lsp/ and locations/ suites for LSP/SOURCE SVCs. - Add 5 genuine tests for LSP/MCP transport, log-file, and dependency-guard behaviour. Every requirement is now verified by a real test. reqstool status: 71/71 complete, PASS; validate --strict ✓; openspec 12/12; 916 tests pass; black + flake8 clean. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
…ories (#2) Restore significance variety flattened by the mechanical OpenSpec->reqstool derivation, guided by the original dataset's intent: - INGEST_0004 (parse annotations) shall -> should (a dataset is valid without them) - INGEST_0008 (optional config file) shall -> should - LSP_0003 (server log file) shall -> may (optional convenience) - REPORT_0006 (deprecated AsciiDoc alias) shall -> should Category fixes: INGEST_0007 (content root) compatibility -> functional-suitability; LIFECYCLE_0001 (non-code types) add functional-suitability. validate --strict ✓; status still 71/71 PASS. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
…ion precision, hygiene) Acts on the consolidated /x:full-pr-review findings for PR #407: Test quality (genuine tests, not placeholders): - VALIDATE_0001: add a real coverage-gap test (_check_coverage reports a requirement with no SVC); retag the exit-code/strict tests to VALIDATE_0004/0005 (#1). - SOURCE_0004/0008: link to the existing genuine git clone/checkout + token tests instead of the field-storage test (#2). - ENRICH_0003: add a real command_enrich stdin->output test; retag passthrough to ENRICH_0001 (#6). - LSP_0004/MCP_0004 guard tests: assert the install-hint and capture stderr (#12). Annotation precision: - Redistribute concentrated class-level @requirements onto the narrow implementing functions: STATUS_0002->_status_verdict, STATUS_0008->__inject_post_tests, STATUS_0007->command_status, VALIDATE_0001/0002->_check_coverage, EXPORT_0002/0003->GenerateJsonCommand, ENRICH_0003/0004->command_enrich (#3). - Remove duplicate INGEST_0007 annotation (kept on the content-root method) (#7). Hygiene: - pyproject hatch sources: add tests/e2e so its future annotations aren't dropped (#11). - Fix the orphaned integration-test comment (pointed at the deleted traceability module) (#8). - Reconcile the PLAN doc's stale 15/71 notes and move PLAN + PASS1 working docs to docs/dev/ (#9). Clarify .reqstool-ai.yaml comment (#14). Intentionally kept: thin ID-reference specs (#4, the reqstool-openspec DRY convention) and automated-test default / no MVRs (#10, the substance — mock-only verification — is resolved by the genuine tests above). reqstool status 71/71 PASS; validate --strict ✓; openspec 12/12; 918 tests pass; black + flake8 clean. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Member
Author
Full PR Review —
|
| # | Prio | Finding | Resolution |
|---|---|---|---|
| 1 | High | VALIDATE_0001 marked complete with no test of its behavior | ✅ Added real _check_coverage no-SVC test; retagged exit-code tests to VALIDATE_0004/0005 |
| 2 | High | SOURCE_0004 git-fetch only backed by field-storage test | ✅ Relinked to the existing genuine clone/checkout + token tests |
| 3 | High | Shotgun/ID-concentration annotations on class headers | ✅ Redistributed onto narrow implementing fns (_status_verdict, __inject_post_tests, command_status, _check_coverage, GenerateJsonCommand, command_enrich) |
| 4 | High | Dual-SSOT duplication (thin specs mirror reqstool) | ↪︎ Intentional — the reqstool-openspec DRY convention (specs reference IDs, content in reqstool, enriched at read time) |
| 5 | Med | Argparse-only tests behind behavioral SVCs | ◐ Partial — arg wiring is the unit-testable surface; full transport/log behavior is integration-scoped |
| 6 | Med | ENRICH_0003 stdin/stdout never exercised | ✅ Added a real command_enrich stdin→output test |
| 7 | Med | INGEST_0007 annotated on two methods | ✅ Deduplicated |
| 8 | Med | Orphaned integration-test comment (deleted module) | ✅ Corrected |
| 9 | Med | PLAN/PASS1 process docs + PLAN 15/71 contradiction | ✅ Reconciled + moved to docs/dev/ |
| 10 | Med | All-automated-test / MVRs deleted | ↪︎ Intentional default; mock-only-verification substance fixed via #1/#2/#6 |
| 11 | Low | sources silently dropped tests/e2e |
✅ Added tests/e2e |
| 12 | Low | Guard tests under-assert + leak stderr | ✅ capsys + assert install-hint |
| 13 | Low | hook resolves reqstool from ambient PATH |
↪︎ Accepted (dev-only editor hook, fixed args, no shell) |
| 14–15 | Low | .reqstool-ai.yaml wording; validate docstring |
✅ wording / ↪︎ docstring is correct generic behavior |
Post-fix: reqstool status 71/71 PASS · validate --strict ✓ · openspec validate --strict 12/12 · 918 tests pass · black + flake8 clean.
Automated — /x:full-pr-review
Delete docs/dev/PLAN_openspec_reqstool.md and docs/dev/PASS1_commands_discovery.md. These were process/tracking scaffolding for building this change (flagged by the PR review as not belonging in the shipped repo). The durable record lives in the PR description, the review summary comment, and git history. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
…oral tests Round-2 full-PR-review follow-up. Keeps reqstool status at 71/71 and all gates green while making every @svcs claim verifiable behavior: - status.py: drop STATUS_0002/0007/0008 from the StatusCommand class decorator (now annotated on _status_verdict, __inject_post_tests, command_status). - STATUS_0008: real JUnit post-build injection test (DB rows inserted) + missing-file FileNotFoundError; untag the argparse-only parse test. - STATUS_0009: genuine command_status output-destination test; drop the mistag on test_status_report_generation_sys_ms. - STATUS_0005: retag test_status_json_format (JSON format) off STATUS_0001. - LIFECYCLE_0002/0003: real requirement/SVC lifecycle-state parsing tests; retag test_active_states -> LIFECYCLE_0004, test_invalid_schema -> PARSE_0001. - MCP_0003: genuine config-auto-detect + no-config exit(2) tests; untag the parse-only test_mcp_parses_without_source. - LSP_0003: genuine log-file-forwarded-to-server test; untag the arg-parse test. - INGEST_0004/0007: add real assertions to test_basic_local (annotations parsed, static files at content root). Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Member
Author
Round-2
|
| # | Sev | Finding | Resolution |
|---|---|---|---|
| 1 | High | StatusCommand class decorator duplicated STATUS_0002/0007/0008 (also on functions) |
Removed from the class decorator; they live on _status_verdict, __inject_post_tests, command_status |
| 2 | Med | test_status_json_format tagged SVC_STATUS_0001 but tests JSON format |
Retagged → SVC_STATUS_0005 |
| 3 | Med | test_active_states tagged SVC_LIFECYCLE_0002 but asserts no superseded-ref warnings |
Retagged → SVC_LIFECYCLE_0004; added genuine LIFECYCLE_0002 parsing test |
| 4 | Med | test_invalid_schema tagged SVC_LIFECYCLE_0003 but tests schema validation |
Retagged → SVC_PARSE_0001; added genuine LIFECYCLE_0003 parsing test |
| 5 | Med | STATUS_0008/0009, MCP_0003, LSP_0003 were parse-only / mistagged | Added genuine behavioral tests (post-build JUnit injection + missing-file; output-destination; config auto-detect + no-config exit(2); log-file forwarded to server); dropped the parse-only/mistag claims |
| 8 | Low | test_basic_local claimed INGEST_0004/0007 with no assertions |
Added assertions: annotations parsed (impl/test links), static files at content root |
Left as noted (Low/Info): IMPORT_0008 / dispatcher-level IDs (#7), import grouping, _check_coverage being a method, decorator-order cosmetics — none affect coverage or behavior.
Every retagged SVC retains at least one genuine passing test, so the 71/71 count is preserved by real verification rather than placeholders.
/simplify cleanup of the round-2 review tests: - STATUS_0008 injection test: drop the full CombinedRawDatasetsGenerator parse (test_results has no FK, so an empty DB + literal URN observes the injection); removes the single-use _inject_post_tests wrapper and 4 now-unused imports. - STATUS_0009 dispatch test: trim the argparse.Namespace to the only two fields command_status reads directly (output, check_all_reqs_met). Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
…scoping, test coverage) - Split IMPORT_0001-0005 annotations onto the methods/classes that actually enforce them, instead of one umbrella class decorator - Move LIFECYCLE_0002/0003 to the requirements/SVC model generators (where lifecycle state is parsed) and LIFECYCLE_0004 stays on LifecycleValidator - Move SOURCE_0001 (local materialization contract) from LocalLocation to LocationResolver.make_available_on_localdisk, where materialization actually happens; add a real SVC_SOURCE_0001 test - Narrow STATUS_0006/SVC_STATUS_0006 to the JSON export scope they actually describe; add a SVC ID filter test alongside the existing req ID filter test - Replace placeholder SVC_REPORT_0003/0004 test with real grouping and sort-order assertions - Add real server-startup tests for SVC_LSP_0001 and SVC_MCP_0001 - Add a test for the EXIT_CODE_ALL_REQS_NOT_IMPLEMENTED branch of command_status (SVC_STATUS_0007) - Add AsciiDoc content assertions to the report template tests - Drop a redundant SVC_INGEST_0001 tag Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
…ecision, duplicate IDs, coverage gaps) - Swap reversed SVC_INGEST_0005/0006 tags between the Karate and JUnit method-identifier regex tests - Retag test_status_json_verbosity_warning_is_emitted as SVC_STATUS_0005 (verbosity ignored for JSON output), matching its actual behavior - Remove duplicate @requirements IDs placed on both an orchestrator class and its implementing method (STATUS_0001, INGEST_0001, INGEST_0008, REPORT_0004) - Validate generate-json output against export_output.schema.json (SVC_EXPORT_0001) - Add a command-level test for the SVC_ENRICH_0004 "no config found" error path - Tag Maven/npm token tests with SVC_SOURCE_0008 - Use types.SimpleNamespace in the MCP _FakeFastMCP test double and add coverage for the streamable-http transport (SVC_MCP_0002) - Drop over-broad SVC_PARSE_0001 tags from schema-definition sanity tests Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
Jonas-Werne
approved these changes
Jun 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Establishes an OpenSpec specification layer for the whole codebase, derives the reqstool SSOT from it, flips ownership back to reqstool (thin specs reference IDs), and closes the traceability loop with real tests. A complete OpenSpec↔reqstool round-trip.
Changes
docs/reqstool/.openspec/specs/(thin, ID-reference form) — 71 requirements. Title-cased headings;openspecui.hooks.tsinstalled for read-time enrichment.docs/reqstool/(71 requirements + 71 SVCs), capability-prefixed IDs (STATUS_0001,SVC_STATUS_0001, …). Significance reviewed (shall/should/may), not flat.@Requirementscover the 71 requirements on real implementation sites.reqstool_config.yml; narrowed the hatch-pluginsourcesso fixtures don't leak..reqstool-ai.yaml; planning/tracking docs.Validation (all green)
reqstool status→ 71/71 complete, PASS (--check-all-reqs-metexits 0)reqstool validate --strict→ ✓ all checks passedopenspec validate --specs --strict→ 12 passed, 0 failedreqstool enrichround-trip verified via.reqstool-ai.yamlauto-detectblack+flake8clean; CI greenNotes for reviewers
@SVCs(it is skipped without GitHub/GitLab tokens, so its result can't satisfy SVCs in CI); those SVCs are verified by unit tests instead.🤖 Generated with Claude Code