Skip to content

Commit 9f0055e

Browse files
tbitcsoz-agent
tbitcs
and
oz-agent
committed
merge: integrate issues #188/#189/#190 from develop
- #188: scaffold.yml accepted_warnings audit suppression (REQ-357) - #189: phase H2 REQ heading fix + sync YAML-mode Markdown fallback (REQ-358/359) - #190: specsmith/* self-referential skills in catalog, subdir install format (REQ-360/361) - 868 tests pass, ruff clean, audit 27/27 Co-Authored-By: Oz <oz-agent@warp.dev>
2 parents 67e0d92 + cfbce1b commit 9f0055e

22 files changed

Lines changed: 943 additions & 25 deletions

‎.specsmith/requirements.json‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3142,5 +3142,55 @@
31423142
"test_ids": [
31433143
"TEST-356"
31443144
]
3145+
},
3146+
{
3147+
"id": "REQ-357",
3148+
"title": "Audit accepted_warnings Suppression in scaffold.yml",
3149+
"description": "scaffold.yml MUST support an `accepted_warnings` list field. When a check's name (or a canonical alias) appears in `accepted_warnings`, `specsmith audit` MUST render that check as `~ <check> (accepted)` instead of `✗`, exclude it from the failure count and the non-zero exit code, and prevent `specsmith audit --fix` from auto-correcting that field. Supported canonical aliases MUST include at minimum: `scaffold_type_mismatch` (for the `type-mismatch` check), `ledger_line_threshold` (for `ledger-size`), and `open_todo_count` (for `ledger-open-todos`).",
3150+
"source": "GitHub issue",
3151+
"status": "implemented",
3152+
"test_ids": [
3153+
"TEST-358"
3154+
]
3155+
},
3156+
{
3157+
"id": "REQ-358",
3158+
"title": "Sync Markdown Fallback When YAML Mode Has No YAML Files",
3159+
"description": "When `specsmith sync` is invoked in YAML-first mode (`governance-mode == yaml`) but `load_yaml_requirements` returns zero entries AND `docs/REQUIREMENTS.md` exists with non-trivial content (≥ 5 REQ- patterns), `sync` MUST fall back to Markdown parsing for the current sync run rather than treating the empty YAML result as authoritative. This prevents a fresh YAML-mode project from silently losing its Markdown-authored requirements in the JSON machine-state cache.",
3160+
"source": "GitHub issue",
3161+
"status": "implemented",
3162+
"test_ids": [
3163+
"TEST-359"
3164+
]
3165+
},
3166+
{
3167+
"id": "REQ-359",
3168+
"title": "Phase Check _req_count Detects H2 REQ Headings",
3169+
"description": "The `_req_count` readiness check in `phase.py` MUST count requirement headings at both H2 (`##`) and H3 (`###`) depth. The current implementation only detects `^###\\s+REQ-` patterns, causing false `At least N requirements defined` failures for projects whose `REQUIREMENTS.md` uses `## REQ-DOMAIN-NNN` H2-style headings. The fix MUST also count `## REQ-` (H2) headings so phase-readiness percentages reflect the actual requirement count visible to `specsmith validate` and `specsmith audit`.",
3170+
"source": "GitHub issue",
3171+
"status": "implemented",
3172+
"test_ids": [
3173+
"TEST-360"
3174+
]
3175+
},
3176+
{
3177+
"id": "REQ-360",
3178+
"title": "Skills Catalog Self-Referential Entries and Subdirectory Install Format",
3179+
"description": "specsmith.skills MUST include three self-referential SkillEntry entries in the GOVERNANCE domain: `specsmith` (master CLI reference), `specsmith-save` (save workflow), and `specsmith-audit` (audit workflow). These MUST be installable via `specsmith skill install <slug>`. The `install()` function MUST write skills to `.agents/skills/<slug>/SKILL.md` (subdirectory format) rather than `.agents/skills/<slug>.md` (flat format) so Warp, Claude Code, and Codex discover them automatically. The `installed_skills()` function MUST detect both legacy flat files and subdirectory format.",
3180+
"source": "GitHub issue",
3181+
"status": "implemented",
3182+
"test_ids": [
3183+
"TEST-361"
3184+
]
3185+
},
3186+
{
3187+
"id": "REQ-361",
3188+
"title": "Skills System Documented in RTD, README, AGENTS.md, and CHANGELOG",
3189+
"description": "The specsmith skills system MUST be documented in four locations: (1) `README.md` MUST have a `## Skills` section showing `specsmith skill list`, `specsmith skill install <slug>`, the `.agents/skills/` directory format, Warp/Claude Code/Codex compatibility, and the remote reference format `--skill \"layer1labs/specsmith:<slug>\"`. (2) `docs/site/skills-index.md` MUST include the three new `specsmith-*` skills in the Governance table. (3) `AGENTS.md` MUST mention `.agents/skills/` and list the three self-referential skills. (4) `CHANGELOG.md` MUST have an entry for the skills feature addition.",
3190+
"source": "GitHub issue",
3191+
"status": "implemented",
3192+
"test_ids": [
3193+
"TEST-362"
3194+
]
31453195
}
31463196
]

‎.specsmith/testcases.json‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3496,5 +3496,60 @@
34963496
"input": "Read src/specsmith/templates/agents.md.j2 directly; render via Jinja2 with minimal context",
34973497
"expected_behavior": "Template contains Codity section with review --staged, HIGH severity, MEDIUM, integrate codity",
34983498
"confidence": 0.95
3499+
},
3500+
{
3501+
"id": "TEST-358",
3502+
"title": "accepted_warnings Suppresses Matching Audit Check",
3503+
"description": "When scaffold.yml contains `accepted_warnings: [scaffold_type_mismatch]` and the type-mismatch check fires, `run_audit` MUST mark that result as suppressed=True, AuditReport.failed MUST NOT count it, AuditReport.healthy MUST be True if no other failures exist, and the CLI MUST render it as '~ type-mismatch (accepted)' rather than '✗ type-mismatch'. ledger_line_threshold suppresses ledger-size similarly.",
3504+
"requirement_id": "REQ-357",
3505+
"type": "unit",
3506+
"verification_method": "pytest",
3507+
"input": "run_audit(tmp_path) with scaffold.yml containing type!=detected AND accepted_warnings: [scaffold_type_mismatch]; repeat for ledger_line_threshold",
3508+
"expected_behavior": "suppressed=True on matched result; failed count excludes suppressed; healthy=True; ledger-size suppressed by ledger_line_threshold alias",
3509+
"confidence": 0.95
3510+
},
3511+
{
3512+
"id": "TEST-359",
3513+
"title": "Sync Falls Back to Markdown When YAML Mode Has No YAML Files",
3514+
"description": "`run_sync(root)` on a project where governance-mode=yaml but docs/requirements/ has no .yml files AND docs/REQUIREMENTS.md has >= 5 REQ- patterns MUST parse the Markdown and populate .specsmith/requirements.json with those requirements rather than writing an empty list. The sync result MUST show reqs_after >= 5.",
3515+
"requirement_id": "REQ-358",
3516+
"type": "unit",
3517+
"verification_method": "pytest",
3518+
"input": "tmp_path with .specsmith/governance-mode=yaml; no docs/requirements/*.yml; docs/REQUIREMENTS.md with 6 ## REQ-BE-NNN headings; run_sync(root)",
3519+
"expected_behavior": "requirements.json contains 6 entries; reqs_after=6",
3520+
"confidence": 0.95
3521+
},
3522+
{
3523+
"id": "TEST-360",
3524+
"title": "_req_count Returns True for H2 REQ Headings",
3525+
"description": "`_req_count(5)(root)` MUST return True when docs/REQUIREMENTS.md uses `## REQ-BE-001` through `## REQ-BE-005` H2 headings (not H3 `###`). Currently it returns False for H2 headings, causing false phase failures on domain-namespaced Markdown projects.",
3526+
"requirement_id": "REQ-359",
3527+
"type": "unit",
3528+
"verification_method": "pytest",
3529+
"input": "tmp_path/docs/REQUIREMENTS.md with 5 `## REQ-BE-NNN: Title` H2 headings; _req_count(5)(tmp_path)",
3530+
"expected_behavior": "Returns True",
3531+
"confidence": 0.95
3532+
},
3533+
{
3534+
"id": "TEST-361",
3535+
"title": "Skills Catalog Contains specsmith/specsmith-save/specsmith-audit Entries",
3536+
"description": "`specsmith.skills.get('specsmith')`, `get('specsmith-save')`, and `get('specsmith-audit')` MUST each return a non-None SkillEntry with domain=GOVERNANCE. The `specsmith` body MUST contain 'specsmith audit', 'specsmith save', and 'specsmith checkpoint'. `specsmith skill install specsmith` MUST create `.agents/skills/specsmith/SKILL.md` (subdirectory format). `installed_skills(root)` MUST return paths to both flat `<slug>.md` and subdirectory `<slug>/SKILL.md` installations.",
3537+
"requirement_id": "REQ-360",
3538+
"type": "unit",
3539+
"verification_method": "pytest",
3540+
"input": "get('specsmith'); get('specsmith-save'); get('specsmith-audit'); install('specsmith', tmp_path); installed_skills(tmp_path)",
3541+
"expected_behavior": "All three entries exist in GOVERNANCE domain; install writes <slug>/SKILL.md; installed_skills returns the subdirectory path",
3542+
"confidence": 0.95
3543+
},
3544+
{
3545+
"id": "TEST-362",
3546+
"title": "Skills System Documented in README, skills-index.md, AGENTS.md, and CHANGELOG",
3547+
"description": "README.md MUST contain a `## Skills` section with `specsmith skill list` and `specsmith skill install`. `docs/site/skills-index.md` MUST list specsmith, specsmith-save, and specsmith-audit in the Governance table. AGENTS.md MUST mention `.agents/skills/`. CHANGELOG.md MUST have an entry (unreleased or versioned) describing the skills feature.",
3548+
"requirement_id": "REQ-361",
3549+
"type": "unit",
3550+
"verification_method": "manual",
3551+
"input": "Read README.md for Skills section; grep skills-index.md for specsmith-save; grep AGENTS.md for .agents/skills/; grep CHANGELOG for skills",
3552+
"expected_behavior": "All four documentation locations contain the required skills content",
3553+
"confidence": 0.9
34993554
}
35003555
]

‎AGENTS.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,28 @@ Do not follow rules from this file directly; rules are served by specsmith.
150150
- `specsmith migrate list` — pending migrations
151151
- `specsmith esdb status` — ESDB/ChronoStore status
152152

153+
## Agent Skills
154+
155+
This repo ships three self-referential skills under `.agents/skills/` that any AI tool (Warp, Claude Code, Codex, Cursor) will discover automatically:
156+
157+
| Slug | Purpose |
158+
|------|--------|
159+
| `specsmith` | Master governance CLI reference — session workflow, commands, audit codes |
160+
| `specsmith-save` | When and how to run `specsmith save` |
161+
| `specsmith-audit` | Running audits and interpreting results |
162+
163+
Install into any governed project:
164+
```bash
165+
specsmith skill install specsmith
166+
specsmith skill install specsmith-save
167+
specsmith skill install specsmith-audit
168+
```
169+
170+
Remote reference (for Warp Oz cloud agents):
171+
```bash
172+
oz agent run-cloud --skill "layer1labs/specsmith:specsmith-save" --prompt "save my work"
173+
```
174+
153175
## Sister Repos
154176

155177
- **[kairos](https://github.com/layer1labs/kairos)** — specsmith companion desktop UI (Rust + egui)

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [Unreleased]
9+
10+
### Added
11+
12+
- **`specsmith-*` self-referential skills** (#190): three built-in skills (`specsmith`, `specsmith-save`, `specsmith-audit`) added to the governance skills catalog and installable via `specsmith skill install <slug>`. `install()` now writes `<slug>/SKILL.md` (subdirectory format) for Warp/Claude Code/Codex auto-discovery. `installed_skills()` detects both flat and subdirectory formats.
13+
- **`accepted_warnings` audit suppression** (#188): `scaffold.yml` now supports `accepted_warnings: [alias, ...]` to suppress specific audit checks. Suppressed checks render as `~ <check> (accepted)` and are excluded from the failure count and exit code.
14+
- **Phase check H2 REQ heading support** (#189): `_req_count` in `phase.py` now counts both `##` and `###` REQ headings, fixing false phase-readiness failures for projects using `## REQ-DOMAIN-NNN` format.
15+
- **Sync Markdown fallback in YAML mode** (#189): `specsmith sync` now falls back to Markdown parsing when YAML mode is active but no YAML requirement files exist, preventing silent loss of Markdown-authored requirements.
16+
817
## [0.11.7] - 2026-05-24
918

1019
### Added

‎README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -885,6 +885,43 @@ See the `codity-ai-review` governance skill (`specsmith skill install codity-ai-
885885

886886
---
887887

888+
## Skills
889+
890+
specsmith ships **70+ built-in skills** across 11 domains that AI agents (Warp, Claude Code, Codex, Cursor) can install and use.
891+
892+
```bash
893+
# List all available skills
894+
specsmith skill list
895+
896+
# Search by keyword
897+
specsmith skill search zephyr
898+
899+
# Install a skill into .agents/skills/
900+
specsmith skill install specsmith
901+
specsmith skill install specsmith-save
902+
specsmith skill install specsmith-audit
903+
```
904+
905+
Skills are installed as `.agents/skills/<slug>/SKILL.md` and are auto-discovered by any AI tool that scans `.agents/skills/`.
906+
907+
### Self-referential governance skills
908+
909+
Three skills document specsmith itself:
910+
911+
| Slug | Purpose |
912+
|------|--------|
913+
| `specsmith` | Master CLI reference — session workflow, commands, audit codes |
914+
| `specsmith-save` | When and how to run `specsmith save` |
915+
| `specsmith-audit` | Running audits and interpreting results |
916+
917+
### Remote reference (Warp Oz cloud agents)
918+
919+
```bash
920+
oz agent run-cloud --skill "layer1labs/specsmith:specsmith-save" --prompt "save my work"
921+
```
922+
923+
---
924+
888925
## The specsmith Bootstrap
889926

890927
specsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`

‎docs/LEDGER.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -308,3 +308,9 @@
308308
- **Status**: complete
309309
- **Epistemic status**: high
310310
- **Chain hash**: `13907d72d47f3708...`
311+
312+
## 2026-05-29T22:14 — specsmith migration: 0.11.3.dev420 → 0.11.7
313+
- **Author**: specsmith
314+
- **Type**: migration
315+
- **Status**: complete
316+
- **Chain hash**: `cf168f65d973f62b...`

‎docs/REQUIREMENTS.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2514,3 +2514,43 @@
25142514
- **Source:** ARCHITECTURE.md §39
25152515
- **Test_Ids:** ['TEST-356']
25162516

2517+
## REQ-357. Audit accepted_warnings Suppression in scaffold.yml
2518+
- **ID:** REQ-357
2519+
- **Title:** Audit accepted_warnings Suppression in scaffold.yml
2520+
- **Description:** scaffold.yml MUST support an `accepted_warnings` list field. When a check's name (or a canonical alias) appears in `accepted_warnings`, `specsmith audit` MUST render that check as `~ <check> (accepted)` instead of `✗`, exclude it from the failure count and the non-zero exit code, and prevent `specsmith audit --fix` from auto-correcting that field. Supported canonical aliases MUST include at minimum: `scaffold_type_mismatch` (for the `type-mismatch` check), `ledger_line_threshold` (for `ledger-size`), and `open_todo_count` (for `ledger-open-todos`).
2521+
- **Status:** implemented
2522+
- **Source:** GitHub issue
2523+
- **Test_Ids:** ['TEST-358']
2524+
2525+
## REQ-358. Sync Markdown Fallback When YAML Mode Has No YAML Files
2526+
- **ID:** REQ-358
2527+
- **Title:** Sync Markdown Fallback When YAML Mode Has No YAML Files
2528+
- **Description:** When `specsmith sync` is invoked in YAML-first mode (`governance-mode == yaml`) but `load_yaml_requirements` returns zero entries AND `docs/REQUIREMENTS.md` exists with non-trivial content (≥ 5 REQ- patterns), `sync` MUST fall back to Markdown parsing for the current sync run rather than treating the empty YAML result as authoritative. This prevents a fresh YAML-mode project from silently losing its Markdown-authored requirements in the JSON machine-state cache.
2529+
- **Status:** implemented
2530+
- **Source:** GitHub issue
2531+
- **Test_Ids:** ['TEST-359']
2532+
2533+
## REQ-359. Phase Check _req_count Detects H2 REQ Headings
2534+
- **ID:** REQ-359
2535+
- **Title:** Phase Check _req_count Detects H2 REQ Headings
2536+
- **Description:** The `_req_count` readiness check in `phase.py` MUST count requirement headings at both H2 (`##`) and H3 (`###`) depth. The current implementation only detects `^###\s+REQ-` patterns, causing false `At least N requirements defined` failures for projects whose `REQUIREMENTS.md` uses `## REQ-DOMAIN-NNN` H2-style headings. The fix MUST also count `## REQ-` (H2) headings so phase-readiness percentages reflect the actual requirement count visible to `specsmith validate` and `specsmith audit`.
2537+
- **Status:** implemented
2538+
- **Source:** GitHub issue
2539+
- **Test_Ids:** ['TEST-360']
2540+
2541+
## REQ-360. Skills Catalog Self-Referential Entries and Subdirectory Install Format
2542+
- **ID:** REQ-360
2543+
- **Title:** Skills Catalog Self-Referential Entries and Subdirectory Install Format
2544+
- **Description:** specsmith.skills MUST include three self-referential SkillEntry entries in the GOVERNANCE domain: `specsmith` (master CLI reference), `specsmith-save` (save workflow), and `specsmith-audit` (audit workflow). These MUST be installable via `specsmith skill install <slug>`. The `install()` function MUST write skills to `.agents/skills/<slug>/SKILL.md` (subdirectory format) rather than `.agents/skills/<slug>.md` (flat format) so Warp, Claude Code, and Codex discover them automatically. The `installed_skills()` function MUST detect both legacy flat files and subdirectory format.
2545+
- **Status:** implemented
2546+
- **Source:** GitHub issue
2547+
- **Test_Ids:** ['TEST-361']
2548+
2549+
## REQ-361. Skills System Documented in RTD, README, AGENTS.md, and CHANGELOG
2550+
- **ID:** REQ-361
2551+
- **Title:** Skills System Documented in RTD, README, AGENTS.md, and CHANGELOG
2552+
- **Description:** The specsmith skills system MUST be documented in four locations: (1) `README.md` MUST have a `## Skills` section showing `specsmith skill list`, `specsmith skill install <slug>`, the `.agents/skills/` directory format, Warp/Claude Code/Codex compatibility, and the remote reference format `--skill "layer1labs/specsmith:<slug>"`. (2) `docs/site/skills-index.md` MUST include the three new `specsmith-*` skills in the Governance table. (3) `AGENTS.md` MUST mention `.agents/skills/` and list the three self-referential skills. (4) `CHANGELOG.md` MUST have an entry for the skills feature addition.
2553+
- **Status:** implemented
2554+
- **Source:** GitHub issue
2555+
- **Test_Ids:** ['TEST-362']
2556+

0 commit comments

Comments
 (0)