specsmith 0.11.7.dev462__tar.gz → 0.11.8__tar.gz

{specsmith-0.11.7.dev462/src/specsmith.egg-info → specsmith-0.11.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.11.7.dev462
+Version: 0.11.8
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT
@@ -957,6 +957,43 @@ See the `codity-ai-review` governance skill (`specsmith skill install codity-ai-
 
 ---
 
+## Skills
+
+specsmith ships **70+ built-in skills** across 11 domains that AI agents (Warp, Claude Code, Codex, Cursor) can install and use.
+
+```bash
+# List all available skills
+specsmith skill list
+
+# Search by keyword
+specsmith skill search zephyr
+
+# Install a skill into .agents/skills/
+specsmith skill install specsmith
+specsmith skill install specsmith-save
+specsmith skill install specsmith-audit
+```
+
+Skills are installed as `.agents/skills/<slug>/SKILL.md` and are auto-discovered by any AI tool that scans `.agents/skills/`.
+
+### Self-referential governance skills
+
+Three skills document specsmith itself:
+
+| Slug | Purpose |
+|------|--------|
+| `specsmith` | Master CLI reference — session workflow, commands, audit codes |
+| `specsmith-save` | When and how to run `specsmith save` |
+| `specsmith-audit` | Running audits and interpreting results |
+
+### Remote reference (Warp Oz cloud agents)
+
+```bash
+oz agent run-cloud --skill "layer1labs/specsmith:specsmith-save" --prompt "save my work"
+```
+
+---
+
 ## The specsmith Bootstrap
 
 specsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/README.md

@@ -885,6 +885,43 @@ See the `codity-ai-review` governance skill (`specsmith skill install codity-ai-
 
 ---
 
+## Skills
+
+specsmith ships **70+ built-in skills** across 11 domains that AI agents (Warp, Claude Code, Codex, Cursor) can install and use.
+
+```bash
+# List all available skills
+specsmith skill list
+
+# Search by keyword
+specsmith skill search zephyr
+
+# Install a skill into .agents/skills/
+specsmith skill install specsmith
+specsmith skill install specsmith-save
+specsmith skill install specsmith-audit
+```
+
+Skills are installed as `.agents/skills/<slug>/SKILL.md` and are auto-discovered by any AI tool that scans `.agents/skills/`.
+
+### Self-referential governance skills
+
+Three skills document specsmith itself:
+
+| Slug | Purpose |
+|------|--------|
+| `specsmith` | Master CLI reference — session workflow, commands, audit codes |
+| `specsmith-save` | When and how to run `specsmith save` |
+| `specsmith-audit` | Running audits and interpreting results |
+
+### Remote reference (Warp Oz cloud agents)
+
+```bash
+oz agent run-cloud --skill "layer1labs/specsmith:specsmith-save" --prompt "save my work"
+```
+
+---
+
 ## The specsmith Bootstrap
 
 specsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.11.7.dev462"
+version = "0.11.8"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/src/specsmith/__init__.py

@@ -8,4 +8,4 @@ from importlib.metadata import version as _pkg_version
 try:
     __version__: str = _pkg_version("specsmith")
 except PackageNotFoundError:  # running from source without install
-    __version__ = "0.11.7"  # fallback: keep in sync with pyproject.toml
+    __version__ = "0.11.8"  # fallback: keep in sync with pyproject.toml

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/src/specsmith/auditor.py

@@ -23,6 +23,7 @@ class AuditResult:
     passed: bool
     message: str
     fixable: bool = False
+    suppressed: bool = False
 
 
 @dataclass
@@ -37,7 +38,7 @@ class AuditReport:
 
     @property
     def failed(self) -> int:
-        return sum(1 for r in self.results if not r.passed)
+        return sum(1 for r in self.results if not r.passed and not r.suppressed)
 
     @property
     def fixable(self) -> int:
@@ -47,6 +48,39 @@ class AuditReport:
     def healthy(self) -> bool:
         return self.failed == 0
 
+    @property
+    def suppressed_count(self) -> int:
+        return sum(1 for r in self.results if r.suppressed)
+
+
+# ---------------------------------------------------------------------------
+# Suppression aliases (scaffold.yml accepted_warnings → AuditResult.name)
+# ---------------------------------------------------------------------------
+
+_SUPPRESSION_ALIASES: dict[str, str] = {
+    "scaffold_type_mismatch": "type-mismatch",
+    "ledger_line_threshold": "ledger-size",
+    "open_todo_count": "ledger-open-todos",
+    "ledger_size": "ledger-size",
+}
+
+
+def _apply_accepted_warnings(report: AuditReport, accepted: list[str]) -> None:
+    """Mark audit results matching *accepted* warning names as suppressed.
+
+    Each entry in *accepted* is either a key in ``_SUPPRESSION_ALIASES`` or a
+    direct ``AuditResult.name`` (exact match or prefix match up to ``:``).
+    Matched results are set to ``suppressed=True`` and ``passed=True`` so they
+    no longer count as failures.
+    """
+    resolved: list[str] = [_SUPPRESSION_ALIASES.get(a, a) for a in accepted]
+    for result in report.results:
+        for name in resolved:
+            if result.name == name or result.name.startswith(name + ":"):
+                result.suppressed = True
+                result.passed = True
+                break
+
 
 # ---------------------------------------------------------------------------
 # Governance file existence checks
@@ -386,10 +420,7 @@ def check_ledger_health(root: Path) -> list[AuditResult]:
 
     # Size check — uses configurable threshold (#145)
     threshold = _get_ledger_threshold(root)
-    # Check audit_suppressions for opt-out
-    raw = _read_scaffold_raw(root)
-    suppressed = "ledger_size" in (raw.get("audit_suppressions") or [])
-    if not suppressed and line_count > threshold:
+    if line_count > threshold:
         results.append(
             AuditResult(
                 name="ledger-size",
@@ -1171,6 +1202,15 @@ def run_audit(root: Path) -> AuditReport:
     report.results.extend(check_industrial_artifacts(root))
     report.results.extend(check_derived_artifacts(root))
     report.results.extend(check_cross_repo_dependencies(root))
+
+    # Apply accepted_warnings / audit_suppressions from scaffold.yml (REQ-357)
+    raw = _read_scaffold_raw(root)
+    _accepted: list[str] = list(raw.get("accepted_warnings") or [])
+    # backward-compat: audit_suppressions list (pre-#188 ledger_size suppression)
+    _old_suppressed: list[str] = list(raw.get("audit_suppressions") or [])
+    _accepted = _accepted + _old_suppressed
+    if _accepted:
+        _apply_accepted_warnings(report, _accepted)
     return report
 
 
@@ -1182,7 +1222,7 @@ def run_auto_fix(root: Path, report: AuditReport) -> list[str]:
     fixed: list[str] = []
 
     for result in report.results:
-        if result.passed:
+        if result.passed or result.suppressed:
             continue
 
         # Fix missing required files with minimal stubs

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/src/specsmith/cli.py

@@ -441,8 +441,14 @@ def audit(fix: bool, project_dir: str) -> None:
     report = run_audit(root)
 
     for r in report.results:
-        icon = "[green]✓[/green]" if r.passed else "[red]✗[/red]"
-        console.print(f"  {icon} {r.message}")
+        if r.suppressed:
+            icon = "[dim]~[/dim]"
+        elif r.passed:
+            icon = "[green]✓[/green]"
+        else:
+            icon = "[red]✗[/red]"
+        msg = r.message + " [dim](accepted)[/dim]" if r.suppressed else r.message
+        console.print(f"  {icon} {msg}")
 
     console.print()
     if report.healthy:
@@ -8524,9 +8530,19 @@ def skill_list(project_dir: str, as_json: bool) -> None:
     from specsmith import skills as _skills
 
     root = Path(project_dir).resolve()
-    installed = [p.name for p in _skills.installed_skills(root)]
+    installed_paths = _skills.installed_skills(root)
+    # Build identifier list: slug (subdir) or filename (flat legacy)
+    installed: list[str] = []
+    installed_slugs: set[str] = set()
+    for p in installed_paths:
+        if p.name == "SKILL.md":  # subdir format: <slug>/SKILL.md
+            installed.append(p.parent.name)
+            installed_slugs.add(p.parent.name)
+        else:  # legacy flat format: <slug>.md
+            installed.append(p.name)
+            installed_slugs.add(p.stem)
     catalog = [
-        {"slug": entry.slug, "name": entry.name, "installed": f"{entry.slug}.md" in installed}
+        {"slug": entry.slug, "name": entry.name, "installed": entry.slug in installed_slugs}
         for entry in _skills.CATALOG
     ]
     if as_json:

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/src/specsmith/config.py

@@ -115,7 +115,7 @@ class ProjectConfig(BaseModel):
         ),
     )
     language: str = Field(default="python", description="Primary language/runtime")
-    spec_version: str = Field(default="0.11.7", description="Spec version to scaffold from")
+    spec_version: str = Field(default="0.11.8", description="Spec version to scaffold from")
     description: str = Field(default="", description="Short project description")
 
     # Options

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/src/specsmith/phase.py

@@ -77,8 +77,8 @@ def _req_count(min_count: int) -> Callable[[Path], bool]:
             if p.exists():
                 try:
                     text = p.read_text(encoding="utf-8", errors="ignore")
-                    # Support both ### REQ-NNN (old) and ## N. Title / - **ID:** REQ-NNN (new)
-                    count = len(re.findall(r"^###\s+REQ-", text, re.MULTILINE))
+                    # Support H2/H3 headings (## REQ-NNN, ### REQ-NNN, ## REQ-BE-001) (REQ-359)
+                    count = len(re.findall(r"^#{2,3}\s+REQ-", text, re.MULTILINE))
                     if count == 0:
                         count = len(re.findall(r"- \*\*ID:\*\* REQ-", text))
                     if count == 0:

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/src/specsmith/skills/__init__.py

@@ -11,16 +11,17 @@ existing code continues to work without changes.
 
 Domain modules
 ~~~~~~~~~~~~~~
-  governance   — project governance, verification, review, release workflows
-  embedded     — RTOS/BSP: Zephyr, Yocto, FreeRTOS, NuttX, Buildroot, Azure RTOS …
-  hardware     — EDA: KiCad, Altium, Vivado, Quartus, GTKWave, OpenOCD, JTAG
-  mobile       — iOS (Xcode/Swift/TestFlight), Android (Gradle/ADB), Flutter, RN
-  cloud        — AWS CLI, Azure CLI, GCP, GitHub CLI (gh)
-  devops       — Docker, Kubernetes, Terraform, CI/CD pipelines
-  ssh          — SSH key management, remote-dev, WSL2
-  cross_platform — CMake/vcpkg/conan, package managers, cross-OS CI
-  productivity — Email, presentations, Gamma.ai, MS Office, LibreOffice
-  corporate    — Budgets, project mgmt, HR, fundraising, marketing, sales, legal
+  governance        — project governance, verification, review, release workflows
+  specsmith_skills  — specsmith self-referential skills (save, audit, reference)
+  embedded          — RTOS/BSP: Zephyr, Yocto, FreeRTOS, NuttX, Buildroot, Azure RTOS …
+  hardware          — EDA: KiCad, Altium, Vivado, Quartus, GTKWave, OpenOCD, JTAG
+  mobile            — iOS (Xcode/Swift/TestFlight), Android (Gradle/ADB), Flutter, RN
+  cloud             — AWS CLI, Azure CLI, GCP, GitHub CLI (gh)
+  devops            — Docker, Kubernetes, Terraform, CI/CD pipelines
+  ssh               — SSH key management, remote-dev, WSL2
+  cross_platform    — CMake/vcpkg/conan, package managers, cross-OS CI
+  productivity      — Email, presentations, Gamma.ai, MS Office, LibreOffice
+  corporate         — Budgets, project mgmt, HR, fundraising, marketing, sales, legal
 
 Usage
 ~~~~~
@@ -121,6 +122,7 @@ def _build_catalog() -> list[SkillEntry]:
         hardware,
         mobile,
         productivity,
+        specsmith_skills,
         ssh,
     )
 
@@ -136,6 +138,7 @@ def _build_catalog() -> list[SkillEntry]:
         + productivity.SKILLS
         + corporate.SKILLS
         + docs.SKILLS
+        + specsmith_skills.SKILLS
     )
 
 
@@ -207,15 +210,21 @@ def by_project_type(project_type: str) -> list[SkillEntry]:
 
 
 def installed_skills(project_dir: Path) -> list[Path]:
-    """Return SKILL.md files installed under ``.agents/skills/``."""
+    """Return installed skill files under ``.agents/skills/`` (both flat and subdir formats)."""
     base = project_dir / ".agents" / "skills"
     if not base.is_dir():
         return []
-    return sorted(p for p in base.iterdir() if p.is_file() and p.suffix == ".md")
+    paths: list[Path] = []
+    for item in sorted(base.iterdir()):
+        if item.is_file() and item.suffix == ".md":  # legacy flat format
+            paths.append(item)
+        elif item.is_dir() and (item / "SKILL.md").exists():  # subdir format
+            paths.append(item / "SKILL.md")
+    return sorted(paths)
 
 
 def install(slug: str, project_dir: Path, *, force: bool = False) -> Path:
-    """Copy skill *slug* into ``<project_dir>/.agents/skills/<slug>.md``.
+    """Copy skill *slug* into ``<project_dir>/.agents/skills/<slug>/SKILL.md``.
 
     Raises
     ------
@@ -229,7 +238,10 @@ def install(slug: str, project_dir: Path, *, force: bool = False) -> Path:
         raise KeyError(f"Unknown skill: {slug!r}")
     base = project_dir / ".agents" / "skills"
     base.mkdir(parents=True, exist_ok=True)
-    target = base / f"{slug}.md"
+    # Subdirectory format: <slug>/SKILL.md (REQ-360)
+    skill_dir = base / slug
+    skill_dir.mkdir(exist_ok=True)
+    target = skill_dir / "SKILL.md"
     if target.exists() and not force:
         raise FileExistsError(f"Already installed: {target}. Pass force=True to overwrite.")
     target.write_text(entry.body, encoding="utf-8")

{specsmith-0.11.7.dev462 → specsmith-0.11.8}/src/specsmith/skills/governance.py

@@ -293,6 +293,172 @@ print("Rust backend:", RUST_BACKEND)
 """
         ),
     ),
+    SkillEntry(
+        slug="specsmith",
+        name="Specsmith — master governance CLI reference",
+        description=(
+            "Master reference for the specsmith AEE governance tool — key concepts, "
+            "common commands, session workflow, phase advancement, and audit codes. "
+            "Use whenever working in a specsmith-governed project."
+        ),
+        domain=SkillDomain.GOVERNANCE,
+        tags=["specsmith", "governance", "aee", "cli", "session", "audit", "phase", "ledger"],
+        prerequisites=["specsmith"],
+        body="""\
+# Specsmith — Master Governance CLI Reference
+
+specsmith is the Applied Epistemic Engineering (AEE) toolkit for AI-assisted
+development.  It governs projects through a 7-phase lifecycle and enforces
+22 hard rules (H1–H22) via preflight gates, audits, and cryptographic trace
+vaults.
+
+## Key Concepts
+- **AEE Phase** — inception → architecture → requirements → test_spec →
+  implementation → verification → release.  `specsmith phase` shows the
+  current phase and readiness percentage.
+- **Preflight Gate** — every proposed change must pass
+  `specsmith preflight "<intent>" --json` before execution.
+- **Work Item** — a scoped unit of work (`WI-<hash>`) assigned by preflight.
+- **Governance Anchor** — `specsmith checkpoint` emits a timestamped snapshot
+  of phase, health, and active work items.
+- **ESDB** — EpiStemic State Database (ChronoMemory WAL) stores beliefs,
+  decisions, and trace seals.
+
+## Common Commands
+```bash
+specsmith audit              # governance health (28 checks)
+specsmith sync               # YAML → JSON → Markdown sync
+specsmith validate --strict  # schema validation
+specsmith preflight "..."    # preflight gate
+specsmith checkpoint         # emit GOVERNANCE ANCHOR
+specsmith save               # ESDB backup + commit + push
+specsmith phase              # show current phase + readiness
+specsmith phase next         # advance phase (checks prerequisites)
+specsmith kill-session       # terminate all agent processes
+specsmith ledger add "msg"   # append to LEDGER.md
+```
+
+## Session Workflow
+1. `specsmith audit && specsmith sync && specsmith checkpoint`
+2. `specsmith preflight "<describe change>" --json`
+3. Execute work (only if decision == accepted)
+4. Every 8-10 turns: `specsmith checkpoint` (output verbatim)
+5. `specsmith save && specsmith kill-session`
+
+## Audit Codes
+- 28 checks across structure, REQ↔TEST coverage, governance size,
+  tool config, phase readiness, and supplementary rules.
+- `specsmith audit --fix` auto-repairs missing files and CI configs.
+
+## Phase Advancement
+- `specsmith phase next` checks prerequisites before advancing.
+- `specsmith phase set <phase>` jumps (with `--force` to skip checks).
+- Phase stored as `aee_phase` in `scaffold.yml`.
+""",
+    ),
+    SkillEntry(
+        slug="specsmith-audit",
+        name="Specsmith Audit — drift detection and governance health",
+        description=(
+            "Run specsmith audit to check for governance drift between requirements, "
+            "tests, and architecture. Required before advancing an AEE phase."
+        ),
+        domain=SkillDomain.GOVERNANCE,
+        tags=["specsmith", "audit", "drift", "health", "governance", "aee", "requirements"],
+        prerequisites=["specsmith"],
+        body="""\
+# Specsmith Audit — Drift Detection and Governance Health
+
+## When to Run
+- At the start of every session (part of bootstrap)
+- Before advancing an AEE phase (`specsmith phase next`)
+- After significant code or requirements changes
+- When drift is suspected (stale coverage, missing tests)
+
+## Command
+```bash
+specsmith audit                    # full 28-check governance audit
+specsmith audit --fix              # auto-repair missing files
+specsmith audit --project-dir .    # explicit project root
+```
+
+## What It Checks (28 checks)
+1. Governance file structure (.specsmith/, docs/, AGENTS.md)
+2. REQ↔TEST bidirectional coverage (no orphan tests, no untested REQs)
+3. Governance file size thresholds
+4. CI tool configuration matches project type
+5. Phase readiness prerequisites
+6. Supplementary rules referenced in AGENTS.md
+7. Duplicate governance files (root vs docs/ canonical)
+8. YAML↔JSON↔Markdown sync state
+
+## Interpreting Results
+- **28/28 checks passed** — governance is healthy
+- **Failures** — surface to user before starting work
+- **Warnings** — non-blocking but should be addressed
+
+## Suppressing Warnings
+In `scaffold.yml`:
+```yaml
+accepted_warnings:
+  - <alias>     # renders as ~ <check> (accepted), excluded from failure count
+```
+
+## Integration with Phase Advancement
+`specsmith phase next` runs audit internally. All checks must pass
+(or be accepted) before the phase advances.
+""",
+    ),
+    SkillEntry(
+        slug="specsmith-save",
+        name="Specsmith Save — governance-aware save workflow",
+        description=(
+            "Run specsmith save to commit and push all current changes with governance "
+            "state backup. Use at the end of any work session or after completing a feature/fix."
+        ),
+        domain=SkillDomain.GOVERNANCE,
+        tags=["specsmith", "save", "commit", "push", "esdb", "backup", "governance"],
+        prerequisites=["specsmith"],
+        body="""\
+# Specsmith Save — Governance-Aware Save Workflow
+
+## When to Use
+- At the end of every work session
+- After completing a feature or fix
+- Before switching branches or contexts
+- Never end a session with uncommitted governance changes
+
+## Command
+```bash
+specsmith save                     # ESDB backup + commit + push
+specsmith save --project-dir .     # explicit project root
+```
+
+## What It Does (in order)
+1. Creates a timestamped ESDB backup (.specsmith/backups/)
+2. Runs `git add -A` to stage all changes
+3. Commits with a governance-stamped message
+4. Pushes to the current remote branch
+
+## Prerequisites
+- All governance changes must be consistent (run `specsmith audit` first
+  if unsure)
+- A git remote must be configured
+- Working tree should have changes to commit
+
+## Session End Protocol
+```bash
+specsmith save --project-dir .    # ESDB backup + commit + push
+specsmith kill-session            # stop governance-serve and tracked processes
+```
+
+## ESDB Backup Details
+- Backups are written to `.specsmith/backups/`
+- Filename format: `backup-YYYY-MM-DDTHH-MM-SS.json`
+- Contains requirements.json and testcases.json snapshots
+- Use `specsmith esdb rollback --steps N` to restore from backup
+""",
+    ),
     SkillEntry(
         slug="specsmith-session-governance",
         name="Specsmith Session Governance — drift prevention, heartbeat, preflight gate",