Bootstrap formal specification infrastructure, agent skills, and codebase reference docs#1142
Draft
ahouseholder wants to merge 14 commits into
Draft
Bootstrap formal specification infrastructure, agent skills, and codebase reference docs#1142ahouseholder wants to merge 14 commits into
ahouseholder wants to merge 14 commits into
Conversation
Reorganize specs/ into seven topic-focused files, each with atomic, verifiable requirements and no cross-file redundancy. Changes to existing files: - spec-registry.yaml (SR): split SR-01-002 (combined two requirements) into SR-01-002 (file must have ≥1 group) and SR-01-003 (group must have ≥1 spec); renumber SR-01-003–SR-01-005 → SR-01-004–SR-01-006 New spec files: - domain-model.yaml (DM, kind=domain): object identity, DecisionPoint, DecisionTable, Outcome, and mixin composition requirements - registry.yaml (RG, kind=implementation): SsvcObjectRegistry structure, registration behavior, and lookup behavior - api.yaml (AP, kind=implementation): FastAPI structure, response format, and error handling requirements - testing.yaml (TS, kind=language): test organisation, isolation, and quality standards - ci.yaml (CI, kind=general): CI gates (pytest, spec-lint, markdownlint) and deployment (GitHub Pages, PyPI) requirements - codegen.yaml (GN, kind=implementation): source authority and artifact generation requirements for data/json/, data/csv/, and namespace_patterns.py New files: - README.md: describes all spec files, ID prefix convention, SpecKind tiers, tooling usage, and a requirement authoring checklist All files pass ssvc-spec-lint with exit code 0 (no errors, no warnings). All 254 existing tests continue to pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The ssvc package lives under src/ssvc/ but pyproject.toml had where=["."],
causing setuptools editable-install to produce an empty MAPPING and making
the package unimportable ("No module named 'ssvc'"). Setting where=["src"]
fixes editable installs and unblocks uv run ssvc-spec-dump.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Ports the load-specs skill from vultron_pub, adapted for SSVC: - command is `uv run ssvc-spec-dump` (not spec-dump) - example IDs reference SSVC spec topics (AP, SR, CI, TS) - cross-cutting spec list updated for SSVC's spec files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add specs/versioning.yaml (VR): formalises ADR-0002/0005/0006/0013/0015
into testable requirements covering decision point SemVer rules, decision
point group SemVer rules, JSON schema SchemaVer rules, and project CalVer
- Add specs/namespaces.yaml (NS): formalises ADR-0012 into requirements for
registered namespaces and extension namespace format (x_ prefix)
- Extend specs/domain-model.yaml (DM):
- DM-02-005/006: description fields MUST NOT embed worked examples (ADR-0007)
- DM-06: ordering constraints for decision point values and outcome sets
(ADR-0008, ADR-0009)
- DM-07: separation of concerns — DecisionTable must not embed OutcomeSet
or policy mappings (ADR-0010)
- Extend specs/codegen.yaml (GN):
- GN-02-004: JSON schema files MUST use SchemaVer in schemaVersion/
(ADR-0015)
- Add notes/versioning-rules.md: prose companion with worked examples for
the layered versioning strategy
- Add notes/namespaces.md: practical guide for namespace usage and adopter
extension patterns
- Add notes/terminology.md: decision table vs. decision tree cheat sheet
for documentation authors (ADR-0014)
- Update specs/README.md with rows for new VR and NS spec files
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add .agents/skills/ingest-idea/ and study-project-docs/ skill definitions used during session workflows - Add docs/reference/codebase/ architecture blueprint (ARCHITECTURE, CONCERNS, CONVENTIONS, INTEGRATIONS, STACK, STRUCTURE, TESTING) generated by the architecture-blueprint-generator skill - Add plan/PRIORITIES.md and plan/BUILD_LEARNINGS.md project planning files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Adapted from vultron_pub/.agents/skills/process-concerns - Updated repo constants: CERTCC/SSVC, node ID MDEwOlJlcG9zaXRvcnkyMzU4MDkzNTU= - Concern type ID IT_kwDOAjf0s84B_2VT is the same as Vultron - Replaced table-based parsing with prose/narrative parsing to match SSVC's CONCERNS.md format (numbered items under section headings, not markdown tables) - Added section → severity/category mapping for SSVC's four sections - Added explicit skip rule for 'Safe operating advice' section - Replaced Vultron-specific label/repo references throughout - Added GraphQL workaround note: gh issue list --json issueType is unsupported for this repo; use GraphQL API to list Concern issues - Removed Phase 4 ASK USER handling (SSVC CONCERNS.md has no such section) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace section-name-based parsing with semantic extraction so the skill works regardless of how the generated file is structured on any given run. - Phase 2 now reads the whole file and identifies concern topics by content rather than by matching specific section headings - Severity is inferred from any explicit language or section placement cues, defaulting to 'medium' when absent - Category is mapped from keyword signals in the title/narrative rather than from fixed section names - Constraints now explicitly forbid hard-coding section names from a prior run - Checklist updated to reflect format-agnostic parsing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ahouseholder
requested review from
cgyarbrough,
j--- and
sei-vsarvepalli
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Bootstraps a formal specification infrastructure for SSVC: introduces a structured YAML spec registry under specs/, a Python package (ssvc.metadata.specs) with Pydantic schema, registry loader, linter, renderer, and LLM-optimized exporter, plus pre-commit/CLI integration. Also adds extensive agent skills under .agents/skills/, codebase reference docs under docs/reference/codebase/, notes on namespaces/terminology/versioning, and fixes the setuptools packages.find where setting so ssvc is importable from src/.
Changes:
- Adds
ssvc.metadata.specsPython package (schema, registry, lint, render, llm_export) with unit tests and two console scripts (ssvc-spec-lint,ssvc-spec-dump). - Adds 10 YAML spec files under
specs/plus a README, plus agent skill markdown files and codebase reference docs. - Fixes
pyproject.tomlto point setuptools atsrc/and addspyyamldependency.
Reviewed changes
Copilot reviewed 41 out of 42 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| pyproject.toml | Fix setuptools where=["src"], add pyyaml dep and two console_scripts |
| uv.lock | Pick up new pyyaml dependency |
| src/ssvc/metadata/init.py, base.py | New metadata tooling layer with NonEmptyStr alias |
| src/ssvc/metadata/specs/init.py | Package surface and UnknownSpecIdWarning helper |
| src/ssvc/metadata/specs/schema.py | Pydantic schema for spec YAML; possible validator-override issue between StatementSpec and BehavioralSpec |
| src/ssvc/metadata/specs/registry.py | Spec loader, graph build, inheritance resolution, cross-ref validation |
| src/ssvc/metadata/specs/lint.py | CLI linter with hard errors and advisory warnings |
| src/ssvc/metadata/specs/render.py | Markdown/JSON/YAML/llm-json renderers and CLI entry points |
| src/ssvc/metadata/specs/llm_export.py | Flat JSON projection for agents; minor enum .value inconsistency |
| src/test/metadata/specs/* | Unit tests for schema, registry, lint and shared fixtures |
| specs/*.yaml + specs/README.md | New normative YAML spec files and authoring guide |
| docs/reference/codebase/*.md | Codebase-reference docs for agent context |
| notes/.md, plan/.md | Project-level notes and queue files |
| .agents/skills/**/SKILL.md | Agent skill definitions |
| .pre-commit-config.yaml | Spec lint hook wired to ssvc-spec-lint |
- Add VR-05 group to specs/versioning.yaml with VR-05-001 through VR-05-007 covering DecisionTable SemVer identity, major/minor/patch triggers, pre-stability (v0.x), and optional status field - Downgrade VR-01-006 from SHOULD to MAY (status field) - Tighten VR-02 to cover only DecisionPointGroup; remove stale 'or DecisionTable' clause and incorrect 'successor' framing - Update file-level description to mention decision tables - Archive idea #1143 to plan/history/ideas.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…pec inherited-field tests - Rename BehavioralSpec._nonempty_if_present to _behavioral_lists_nonempty so it no longer shadows the identically-named parent validator on StatementSpec; in Pydantic v2 a subclass method with the same name silently replaces the parent decorator entry, which caused scope/tags/relationships/lint_suppress to pass empty-list validation on BehavioralSpec instances - Change _topic_record to emit file.kind.value instead of the bare StrEnum member, consistent with every other enum serialisation site in llm_export.py and render.py - Add test_behavioral_spec_inherited_empty_list_rejected parametrized over scope/tags/relationships/lint_suppress to lock the inherited validator behaviour Addresses copilot-pull-request-reviewer comments on PR #1142. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…LL.md - Add specs/skills.yaml (SK-01 through SK-03, 10 requirements) - Add notes/skills.md with decision table, directory layout, and CI guidance - Restructure .agents/skills/: move 4 dev skills to dev/ subtier - Add .agents/skills/ssvc/evaluate-decision-point/SKILL.md (WIP stub) - Normalise load-specs frontmatter to canonical name+description format - Add .agents/skills/README.md documenting two-tier split - Add .github/workflows/validate_skills.yml for SKILL.md CI enforcement - Update specs/README.md with SK entry - Archive idea #1151 to plan/history/ideas.md Addresses #1151 as part of #1142 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
4 tasks
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…ntain permissions' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
sei-renae
requested changes
Jun 8, 2026
sei-renae
left a comment
sei-renae
left a comment
Contributor
There was a problem hiding this comment.
Suggest dividing this into multiple PRs:
- .agents/skills
- notes/
- specs/
- src/
- everything else
| --- | ||
| name: ingest-idea | ||
| description: > | ||
| Process a raw design idea from a GitHub Idea-type issue into formal specs |
| docs/adr/, notes/, and docs/reference/code/, and scans src/ssvc/ and | ||
| src/test/. | ||
|
|
||
| Answer questions from exploration rather than asking the user where possible. |
Contributor
There was a problem hiding this comment.
Does the LLM process this instruction well?
| - Add notes/<topic>.md with implementation guidance | ||
| - Archive idea #<IDEA_NUMBER> to plan/history/ideas.md | ||
|
|
||
| Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" |
Contributor
There was a problem hiding this comment.
Will this hardcode to copilot?
| IMPL_ISSUE_NUMBER=$(gh api graphql -f query=" | ||
| mutation { | ||
| createIssue(input: { | ||
| repositoryId: \"MDEwOlJlcG9zaXRvcnkyMzU4MDkzNTU=\" |
Contributor
There was a problem hiding this comment.
This also looks like a problem for hardcoding.
|
|
||
| - **Spec file names**: use the topic name, lowercase hyphenated with `.yaml` | ||
| extension (e.g., `exploitation.yaml`, `decision-points.yaml`) | ||
| - **ID prefix**: derive from the topic abbreviation (e.g., `EX`, `DP`) |
Contributor
There was a problem hiding this comment.
Where are topic abbreviations defined?
Comment on lines
+138
to
+142
| priority: MUST | ||
| statement: > | ||
| SK-02-006 `SKILL.md` MUST contain a `## Purpose` section and at | ||
| least one procedural section (e.g., `## Procedure` or | ||
| `## Workflow`) after the front-matter block. |
Contributor
There was a problem hiding this comment.
I don't think all of the .agents/skills/ have purpose at a minimum.
| - id: TS-02-001 | ||
| priority: MUST | ||
| statement: > | ||
| TS-02-001 Each test class setUp MUST call registry.reset(force=True) |
Contributor
There was a problem hiding this comment.
Is setUp a function in a pytest?
| priority: SHOULD | ||
| statement: > | ||
| TS-03-002 Decision point and decision table modules SHOULD include | ||
| tests that verify JSON schema round-trip serialisation. |
Contributor
There was a problem hiding this comment.
I think @sei-vsarvepalli should look at this one
| - id: DM-04-001 | ||
| priority: MUST | ||
| statement: > | ||
| DM-04-001 Each outcome set MUST define at least one outcome value. |
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
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.
Summary
This branch bootstraps a formal specification infrastructure for the SSVC project — introducing structured YAML spec files, a spec registry and linter, agent skills for working with specs, and codebase reference documentation.
Why
The project lacked a machine-readable, AI-navigable specification layer. Decisions were captured ad hoc in notes, ADRs, and code. This PR establishes the scaffolding needed to track requirements, validate them programmatically, and export them for consumption by coding agents.
What Changed
Spec Infrastructure (
specs/,src/ssvc/metadata/specs/)specs/spec-registry.yamlas the master registry of all spec filessrc/ssvc/metadata/specs/Python package with:schema.py— Pydantic models for spec YAML structureregistry.py— loads and indexes spec fileslint.py— validates specs against schema rulesllm_export.py— flat JSON export for AI agent consumptionrender.py— human-readable renderingsrc/test/metadata/specs/)Agent Skills (
.agents/skills/)load-specs— exports all project specs as flat, inheritance-resolved JSON for coding agentsstudy-project-docs— loads specs and reads key project context files before implementation workprocess-concerns— batch-processesCONCERNS.mdinto GitHub Issues (format-agnostic parser)ingest-idea— processes GitHub Idea issues into formal specs and implementation notesCodebase Reference Docs (
docs/reference/codebase/)ARCHITECTURE.md,CONCERNS.md,CONVENTIONS.md,INTEGRATIONS.md,STACK.md,STRUCTURE.md,TESTING.mdNotes and Versioning
notes/namespaces.md,notes/terminology.md,notes/versioning-rules.mdspecs/namespaces.yamlandspecs/versioning.yamlfrom ADR gap analysisPackaging Fix
pyproject.toml: setsetuptoolspackages.find where=["src"]so thessvcpackage is importable when installedTesting
src/test/metadata/specs/Closes #1153