specsmith 0.3.6.dev179__py3-none-any.whl → 0.3.6.dev182__py3-none-any.whl

specsmith/templates/agents.md.j2

@@ -1,230 +1,249 @@
-# {{ project.name }} — Agent Governance
-
-**Project:** {{ project.name }}
-**Type:** {{ project.type_label }} — Section {{ project.section_ref }}
-**Platforms:** {{ project.platform_names | join(', ') }}
-**Spec version:** {{ project.spec_version }}
-
----
-
-> **SESSION START — AUTO-LOAD REQUIRED**
-> You have just read this file. **Do not ask for confirmation.**
-> Immediately read the following files before doing anything else:
-> 1. `docs/governance/RULES.md`
-> 2. `docs/governance/WORKFLOW.md`
-> 3. `docs/governance/ROLES.md`
-> 4. `docs/governance/CONTEXT-BUDGET.md`
->
-> Then read `LEDGER.md` to restore session state. Proceed directly to the start protocol below.
-
----
-
-## Governance File Registry
-
-This project uses the modular governance layout. Read this file in full on every session. Load governance docs per the timing column.
-
-| File | Content | Load timing |
-| ---- | ------- | ----------- |
-| `docs/governance/RULES.md` | Hard rules H1–H9, stop conditions | **AUTO-LOAD** (no prompt) |
-| `docs/governance/WORKFLOW.md` | Session lifecycle, proposal format, ledger format | **AUTO-LOAD** (no prompt) |
-| `docs/governance/ROLES.md` | Agent role boundaries, behavioral rules | **AUTO-LOAD** (no prompt) |
-| `docs/governance/CONTEXT-BUDGET.md` | Context management, credit optimization | **AUTO-LOAD** (no prompt) |
-| `docs/governance/VERIFICATION.md` | Verification standards, acceptance criteria | When performing verification |
-| `docs/governance/DRIFT-METRICS.md` | Drift detection, feedback loops, health signals | On `audit` or session start |
-
-Other project documents:
-
-| File | Content |
-| ---- | ------- |
-| `README.md` | Project overview, structure, goals, status |
-| `LEDGER.md` | Append-only work record (sole authority for session state) |
-| `docs/ARCHITECTURE.md` | Components, boundaries, interfaces, platform expectations |
-| `docs/WORKFLOW.md` | Work loop, milestones, PR expectations |
-| `docs/REQUIREMENTS.md` | Formal, numbered, testable requirements |
-| `docs/TEST_SPEC.md` | Test cases linked to requirements |
-
----
-
-## Authority Hierarchy
-
-1. **AGENTS.md + docs/governance/*** — highest (governance docs inherit this file's authority)
-2. **README.md** — project intent and scope
-3. **docs/REQUIREMENTS.md** — what the system must do
-4. **docs/ARCHITECTURE.md** — how the system is structured
-5. **docs/TEST_SPEC.md** — how the system is verified
-6. **LEDGER.md** — sole authority for session state
-7. **docs/WORKFLOW.md** — how work proceeds
-
----
-
-## Project-Specific Rules
-{% if project.type == 'cli-python' %}
-- CLI must have `--help` for all commands
-- Exit codes must be documented and tested
-- No services.md unless daemon/background modes are added
-- Cross-platform rules apply to all file path and process behavior
-{% elif project.type == 'fpga-rtl' %}
-- Shell wrappers are mandatory for all Vivado/Quartus/EDA tool invocations
-- Constraint files (.xdc, .sdc) are governance artifacts — changes require proposals
-- Tool invocations MUST use batch/non-interactive modes only
-- Timing closure is a formal milestone
-{% elif project.type == 'yocto-bsp' %}
-- KAS YAML files are governance artifacts — changes require proposals
-- Machine/distro configs must be documented in architecture.md
-- Build durations must be stated in proposals
-{% elif project.type == 'pcb-hardware' %}
-- BOM files are governance artifacts — changes require proposals
-- Schematic review is a formal gate before layout
-- ECAD-MCAD sync points must be documented in workflow.md
-{% elif project.type in ('cli-rust', 'library-rust') %}
-- `cargo clippy` must pass with no warnings before merge
-- All public APIs must have doc comments
-- `cargo audit` must pass in CI
-{% elif project.type in ('cli-go',) %}
-- `golangci-lint run` must pass before merge
-- All exported functions must have doc comments
-- `govulncheck` must pass in CI
-{% elif project.type in ('cli-c', 'library-c') %}
-- MISRA-C compliance rules apply where annotated
-- `clang-tidy` and `cppcheck` must pass before merge
-- Memory safety must be verified for all allocations
-{% elif project.type == 'web-frontend' %}
-- `eslint` and `prettier` must pass before merge
-- All components must have corresponding test files
-- Accessibility (a11y) checks are recommended
-{% elif project.type == 'dotnet-app' %}
-- `dotnet format --verify-no-changes` must pass before merge
-- All public APIs must have XML doc comments
-{% elif project.type == 'devops-iac' %}
-- `tflint` / `ansible-lint` must pass before merge
-- Security scanning (`tfsec` / `checkov`) is mandatory
-- State files must never be committed
-{% elif project.type == 'data-ml' %}
-- Notebooks must be stripped of output before commit (`nbstripout`)
-- Model metrics must be recorded in the ledger
-- Data pipeline tests are mandatory
-{% elif project.type == 'microservices' %}
-- Each service must have independent CI and test suites
-- API contracts (OpenAPI / protobuf) are governance artifacts
-- `docker compose build` must succeed before merge
-{% elif project.type == 'spec-document' %}
-- All specification text must use precise, testable language
-- Cross-references must be validated before merge
-- Change proposals must reference exact section numbers
-- Prose linting (`vale`) must pass before merge
-{% elif project.type == 'user-manual' %}
-- All screenshots must be kept current with software releases
-- Link checking (`markdown-link-check`) must pass before merge
-- Spell checking (`cspell`) is mandatory
-- Versioned alongside the product it documents
-{% elif project.type == 'research-paper' %}
-- Citation integrity must be maintained — all `\cite{}` must resolve
-- Data and figures must be reproducible from source
-- LaTeX compilation must produce clean output (no warnings)
-{% elif project.type == 'business-plan' %}
-- Financial projections must cite assumptions and sources
-- Market data must include retrieval dates
-- All changes require stakeholder review
-{% elif project.type == 'patent-application' %}
-- Claims are governance artifacts — ALL changes require proposals
-- Independent claims must be self-contained and not reference other claims
-- Prior art references must be documented with publication dates
-- Figures must be numbered and referenced in the specification
-- Claim dependency chains must be validated (`claim-ref-check`)
-{% elif project.type == 'legal-compliance' %}
-- All document changes must be tracked with version history
-- Regulatory references must include jurisdiction and effective date
-- Approval workflows are mandatory before publication
-- Privileged/confidential documents must be marked clearly
-{% elif project.type == 'requirements-mgmt' %}
-- Every requirement must have a unique ID (REQ-xxx-NNN)
-- Traceability from requirements → tests must be maintained
-- Baseline snapshots must be taken at milestone boundaries
-{% elif project.type == 'api-specification' %}
-- API specs (OpenAPI / protobuf) are governance artifacts
-- Breaking changes require explicit proposals and version bumps
-- Linting (`spectral` / `buf lint`) must pass before merge
-- Generated code must not be manually edited
-{% elif project.type == 'monorepo' %}
-- Each package/service must have independent test suites
-- Shared code changes require impact analysis across consumers
-- Build tool (`nx` / `turbo`) must succeed before merge
-{% elif project.type == 'browser-extension' %}
-- Manifest permissions must be minimal and documented
-- Content security policy must be explicitly defined
-- `web-ext lint` must pass before merge
-{% else %}
-- Cross-platform rules apply to all file path and process behavior
-{% endif %}
-
----
-
-## Epistemic Governance (AEE)
-
-This project follows Applied Epistemic Engineering (AEE) principles. Every proposal MUST:
-- State its `Assumptions:` field (H13 — Epistemic Boundaries Required)
-- State its `Stress-test:` field — one adversarial challenge to the proposal's assumptions
-
-Run `specsmith epistemic-audit` to check epistemic health:
-- Equilibrium = all belief artifacts stress-tested with no critical failures
-- Certainty ≥ 0.7 (default threshold)
-- No Logic Knots (conflicting accepted requirements)
-
-`specsmith trace seal decision "<description>"` — seal any significant decision
-`specsmith stress-test` — adversarial challenges against REQUIREMENTS.md
-`specsmith belief-graph` — visualize BeliefArtifact dependency graph
-
-Stop condition (H13): P1 requirement with confidence below MEDIUM = work stops.
-
----
-
-## Session Lifecycle
-
-### Start Protocol
-1. Load `docs/governance/RULES.md`, `WORKFLOW.md`, `ROLES.md`, `CONTEXT-BUDGET.md` — **already done if you followed the auto-load instruction above**
-2. Read `LEDGER.md` — restore session state
-3. `specsmith sync` — pull latest changes
-4. `specsmith update --check` — verify specsmith is current
-5. Check branch: verify you're on the correct branch for the task
-6. Propose next task
-
-### During Work
-- After each task: `save` → `specsmith commit` (if verification passes)
-- Propose commit after successful verification + ledger save
-- Batch pushes: push after milestones, not every commit
-- Refuse to work on main directly (use feature branches)
-
-### End Protocol
-1. `specsmith session-end` — run checklist
-2. Commit any uncommitted work
-3. Push all unpushed commits
-4. If feature complete: propose PR
-
-## Quick Command Reference
-
-| Command        | Meaning                                        |
-| -------------- | ---------------------------------------------- |
-| `start`        | New session (sync + update check + branch check) |
-| `resume`       | Resume from ledger                             |
-| `save`         | Write ledger entry                             |
-| `commit`       | `specsmith commit` (audit + commit)            |
-| `push`         | `specsmith push` (with safety checks)          |
-| `sync`         | `specsmith sync` (pull + conflict warning)     |
-| `audit`        | `specsmith audit`                              |
-| `branch`       | `specsmith branch create`                      |
-| `pr`           | `specsmith pr` (create PR with governance)     |
-| `update`       | `specsmith update` (check + install + migrate) |
-| `session-end`  | `specsmith session-end` (end checklist)        |
-
-**specsmith install / update:**
-
-```bash
-# Recommended — global isolated install
-pipx install specsmith
-pipx inject specsmith anthropic openai  # add LLM providers
-pipx upgrade specsmith                  # update
-
-# Or with pip
-pip install specsmith
-specsmith self-update
-```
+# {{ project.name }} — Agent Governance
+
+**Project:** {{ project.name }}
+**Type:** {{ project.type_label }} — Section {{ project.section_ref }}
+**Platforms:** {{ project.platform_names | join(', ') }}
+**Spec version:** {{ project.spec_version }}
+
+---
+
+> **SESSION START — AUTO-LOAD REQUIRED**
+> You have just read this file. **Do not ask for confirmation.**
+> Immediately read the following files before doing anything else:
+> 1. `docs/governance/RULES.md`
+> 2. `docs/governance/SESSION-PROTOCOL.md`
+> 3. `docs/governance/ROLES.md`
+> 4. `docs/governance/CONTEXT-BUDGET.md`
+>
+> Then read `LEDGER.md` to restore session state. Proceed directly to the start protocol below.
+
+---
+
+## Governance File Registry
+
+This project uses the modular governance layout. Read this file in full on every session. Load governance docs per the timing column.
+
+| File | Content | Load timing |
+| ---- | ------- | ----------- |
+| `docs/governance/RULES.md` | Hard rules H1–H9, stop conditions | **AUTO-LOAD** (no prompt) |
+| `docs/governance/SESSION-PROTOCOL.md` | Session lifecycle, proposal format, ledger format | **AUTO-LOAD** (no prompt) |
+| `docs/governance/ROLES.md` | Agent role boundaries, behavioral rules | **AUTO-LOAD** (no prompt) |
+| `docs/governance/CONTEXT-BUDGET.md` | Context management, credit optimization | **AUTO-LOAD** (no prompt) |
+| `docs/governance/VERIFICATION.md` | Verification standards, acceptance criteria | When performing verification |
+| `docs/governance/DRIFT-METRICS.md` | Drift detection, feedback loops, health signals | On `audit` or session start |
+
+Other project documents:
+
+| File | Content |
+| ---- | ------- |
+| `README.md` | Project overview, structure, goals, status |
+| `LEDGER.md` | Append-only work record (sole authority for session state) |
+| `docs/ARCHITECTURE.md` | Components, boundaries, interfaces, platform expectations |
+| `docs/WORKFLOW.md` | Work loop, milestones, PR expectations |
+| `docs/REQUIREMENTS.md` | Formal, numbered, testable requirements |
+| `docs/TEST_SPEC.md` | Test cases linked to requirements |
+
+---
+
+## Current Phase
+
+This project is in the **{{ aee_phase_emoji }} {{ aee_phase_label }}** phase (`{{ aee_phase }}`).
+Focus work on artifacts appropriate for this phase. Run `specsmith phase show` to check readiness.
+
+---
+
+## Authority Hierarchy
+
+1. **AGENTS.md + docs/governance/*** — highest (governance docs inherit this file's authority)
+2. **README.md** — project intent and scope
+3. **docs/REQUIREMENTS.md** — what the system must do
+4. **docs/ARCHITECTURE.md** — how the system is structured
+5. **docs/TEST_SPEC.md** — how the system is verified
+6. **LEDGER.md** — sole authority for session state
+7. **docs/WORKFLOW.md** — how work proceeds
+
+---
+
+## Project-Specific Rules
+{% if project.type == 'cli-python' %}
+- CLI must have `--help` for all commands
+- Exit codes must be documented and tested
+- No services.md unless daemon/background modes are added
+- Cross-platform rules apply to all file path and process behavior
+{% elif project.type == 'fpga-rtl' %}
+- Shell wrappers are mandatory for all Vivado/Quartus/EDA tool invocations
+- Constraint files (.xdc, .sdc) are governance artifacts — changes require proposals
+- Tool invocations MUST use batch/non-interactive modes only
+- Timing closure is a formal milestone
+{% elif project.type == 'yocto-bsp' %}
+- KAS YAML files are governance artifacts — changes require proposals
+- Machine/distro configs must be documented in architecture.md
+- Build durations must be stated in proposals
+{% elif project.type == 'pcb-hardware' %}
+- BOM files are governance artifacts — changes require proposals
+- Schematic review is a formal gate before layout
+- ECAD-MCAD sync points must be documented in workflow.md
+{% elif project.type in ('cli-rust', 'library-rust') %}
+- `cargo clippy` must pass with no warnings before merge
+- All public APIs must have doc comments
+- `cargo audit` must pass in CI
+{% elif project.type in ('cli-go',) %}
+- `golangci-lint run` must pass before merge
+- All exported functions must have doc comments
+- `govulncheck` must pass in CI
+{% elif project.type in ('cli-c', 'library-c') %}
+- MISRA-C compliance rules apply where annotated
+- `clang-tidy` and `cppcheck` must pass before merge
+- Memory safety must be verified for all allocations
+{% elif project.type == 'web-frontend' %}
+- `eslint` and `prettier` must pass before merge
+- All components must have corresponding test files
+- Accessibility (a11y) checks are recommended
+{% elif project.type == 'dotnet-app' %}
+- `dotnet format --verify-no-changes` must pass before merge
+- All public APIs must have XML doc comments
+{% elif project.type == 'devops-iac' %}
+- `tflint` / `ansible-lint` must pass before merge
+- Security scanning (`tfsec` / `checkov`) is mandatory
+- State files must never be committed
+{% elif project.type == 'data-ml' %}
+- Notebooks must be stripped of output before commit (`nbstripout`)
+- Model metrics must be recorded in the ledger
+- Data pipeline tests are mandatory
+{% elif project.type == 'microservices' %}
+- Each service must have independent CI and test suites
+- API contracts (OpenAPI / protobuf) are governance artifacts
+- `docker compose build` must succeed before merge
+{% elif project.type == 'spec-document' %}
+- All specification text must use precise, testable language
+- Cross-references must be validated before merge
+- Change proposals must reference exact section numbers
+- Prose linting (`vale`) must pass before merge
+{% elif project.type == 'user-manual' %}
+- All screenshots must be kept current with software releases
+- Link checking (`markdown-link-check`) must pass before merge
+- Spell checking (`cspell`) is mandatory
+- Versioned alongside the product it documents
+{% elif project.type == 'research-paper' %}
+- Citation integrity must be maintained — all `\cite{}` must resolve
+- Data and figures must be reproducible from source
+- LaTeX compilation must produce clean output (no warnings)
+{% elif project.type == 'business-plan' %}
+- Financial projections must cite assumptions and sources
+- Market data must include retrieval dates
+- All changes require stakeholder review
+{% elif project.type == 'patent-application' %}
+- Claims are governance artifacts — ALL changes require proposals
+- Independent claims must be self-contained and not reference other claims
+- Prior art references must be documented with publication dates
+- Figures must be numbered and referenced in the specification
+- Claim dependency chains must be validated (`claim-ref-check`)
+{% elif project.type == 'legal-compliance' %}
+- All document changes must be tracked with version history
+- Regulatory references must include jurisdiction and effective date
+- Approval workflows are mandatory before publication
+- Privileged/confidential documents must be marked clearly
+{% elif project.type == 'requirements-mgmt' %}
+- Every requirement must have a unique ID (REQ-xxx-NNN)
+- Traceability from requirements → tests must be maintained
+- Baseline snapshots must be taken at milestone boundaries
+{% elif project.type == 'api-specification' %}
+- API specs (OpenAPI / protobuf) are governance artifacts
+- Breaking changes require explicit proposals and version bumps
+- Linting (`spectral` / `buf lint`) must pass before merge
+- Generated code must not be manually edited
+{% elif project.type == 'monorepo' %}
+- Each package/service must have independent test suites
+- Shared code changes require impact analysis across consumers
+- Build tool (`nx` / `turbo`) must succeed before merge
+{% elif project.type == 'browser-extension' %}
+- Manifest permissions must be minimal and documented
+- Content security policy must be explicitly defined
+- `web-ext lint` must pass before merge
+{% else %}
+- Cross-platform rules apply to all file path and process behavior
+{% endif %}
+
+---
+
+## Documentation Rule (H14)
+
+Before committing ANY change, verify documentation is current:
+1. Check if the change affects user-facing behavior, CLI commands, governance files, or configuration
+2. If yes: update the relevant documentation (README.md, docs/, CHANGELOG.md) in the SAME commit
+3. Never commit code changes without checking for documentation gaps
+4. When adding a feature: document it. When changing behavior: update the docs. When removing: note it.
+
+This is a hard rule. Undocumented features are governance violations.
+
+---
+
+## Epistemic Governance (AEE)
+
+This project follows Applied Epistemic Engineering (AEE) principles. Every proposal MUST:
+- State its `Assumptions:` field (H13 — Epistemic Boundaries Required)
+- State its `Stress-test:` field — one adversarial challenge to the proposal's assumptions
+
+Run `specsmith epistemic-audit` to check epistemic health:
+- Equilibrium = all belief artifacts stress-tested with no critical failures
+- Certainty ≥ 0.7 (default threshold)
+- No Logic Knots (conflicting accepted requirements)
+
+`specsmith trace seal decision "<description>"` — seal any significant decision
+`specsmith stress-test` — adversarial challenges against REQUIREMENTS.md
+`specsmith belief-graph` — visualize BeliefArtifact dependency graph
+
+Stop condition (H13): P1 requirement with confidence below MEDIUM = work stops.
+
+---
+
+## Session Lifecycle
+
+### Start Protocol
+1. Load `docs/governance/RULES.md`, `SESSION-PROTOCOL.md`, `LIFECYCLE.md`, `ROLES.md`, `CONTEXT-BUDGET.md` — **already done if you followed the auto-load instruction above**
+2. Read `LEDGER.md` — restore session state
+3. `specsmith sync` — pull latest changes
+4. `specsmith update --check` — verify specsmith is current
+5. Check branch: verify you're on the correct branch for the task
+6. Propose next task
+
+### During Work
+- After each task: `save` → `specsmith commit` (if verification passes)
+- Propose commit after successful verification + ledger save
+- Batch pushes: push after milestones, not every commit
+- Refuse to work on main directly (use feature branches)
+
+### End Protocol
+1. `specsmith session-end` — run checklist
+2. Commit any uncommitted work
+3. Push all unpushed commits
+4. If feature complete: propose PR
+
+## Quick Command Reference
+
+| Command        | Meaning                                        |
+| -------------- | ---------------------------------------------- |
+| `start`        | New session (sync + update check + branch check) |
+| `resume`       | Resume from ledger                             |
+| `save`         | Write ledger entry                             |
+| `commit`       | `specsmith commit` (audit + commit)            |
+| `push`         | `specsmith push` (with safety checks)          |
+| `sync`         | `specsmith sync` (pull + conflict warning)     |
+| `audit`        | `specsmith audit`                              |
+| `branch`       | `specsmith branch create`                      |
+| `pr`           | `specsmith pr` (create PR with governance)     |
+| `update`       | `specsmith update` (check + install + migrate) |
+| `session-end`  | `specsmith session-end` (end checklist)        |
+
+**specsmith install / update:**
+
+```bash
+# Recommended — global isolated install
+pipx install specsmith
+pipx inject specsmith anthropic openai  # add LLM providers
+pipx upgrade specsmith                  # update
+
+# Or with pip
+pip install specsmith
+specsmith self-update
+```

specsmith/templates/governance/context-budget.md.j2

@@ -11,7 +11,8 @@ On session start, load only:
 - Last ~300 lines of `LEDGER.md`
 
 Load on demand:
-- `docs/governance/WORKFLOW.md` — when preparing proposals or ledger entries
+- `docs/governance/SESSION-PROTOCOL.md` — when preparing proposals or ledger entries
+- `docs/governance/LIFECYCLE.md` — when checking phase readiness or advancing
 - `docs/governance/ROLES.md` — when role boundaries are relevant
 - `docs/governance/VERIFICATION.md` — when testing or accepting work
 - `docs/governance/DRIFT-METRICS.md` — when running `audit`

specsmith/templates/governance/lifecycle.md.j2

@@ -0,0 +1,44 @@
+# Project Lifecycle — AEE Development Phases
+
+This project follows the 7-phase Applied Epistemic Engineering (AEE) development lifecycle. Each phase has readiness checks that must pass before advancing.
+
+**Current phase:** {{ aee_phase_emoji }} **{{ aee_phase_label }}** (`{{ aee_phase }}`)
+
+## Phases
+
+1. 🌱 **Inception** — Governance scaffold, AGENTS.md, project type established
+2. 🏗 **Architecture** — ARCHITECTURE.md written, components defined, key decisions sealed
+3. 📋 **Requirements** — REQUIREMENTS.md populated, stress-tested, equilibrium reached
+4. ✅ **Test Specification** — TEST_SPEC.md covers all P1 requirements, coverage ≥ 80%
+5. ⚙ **Implementation** — Code development loop; audit passes; ledger updated each session
+6. 🔬 **Verification** — Epistemic audit passes threshold; trace vault sealed; export clean
+7. 🚀 **Release** — CHANGELOG updated; release tag created; compliance report filed
+
+## Phase Flow
+
+```
+inception → architecture → requirements → test_spec → implementation → verification → release
+                                                                                        ↓
+                                                                                  (next cycle)
+```
+
+## Advancing Phases
+
+Check readiness: `specsmith phase show`
+Advance to next: `specsmith phase next`
+Force-set phase: `specsmith phase set <phase> --force`
+
+All checks for the current phase must pass before `phase next` will advance.
+Use `--force` to override (e.g. during rapid prototyping).
+
+## Phase Artifacts
+
+Each phase produces specific artifacts:
+
+- **Inception**: `scaffold.yml`, `AGENTS.md`, `LEDGER.md`
+- **Architecture**: `docs/ARCHITECTURE.md`, trace vault seal
+- **Requirements**: `docs/REQUIREMENTS.md`, `docs/TEST_SPEC.md`
+- **Test Specification**: TEST_SPEC.md with ≥ 80% REQ coverage
+- **Implementation**: Code, updated LEDGER.md, passing audit
+- **Verification**: Epistemic audit, trace vault seals, export report
+- **Release**: `CHANGELOG.md`, release tag, compliance report

specsmith/templates/governance/{workflow.md.j2 → session-protocol.md.j2}

@@ -1,4 +1,4 @@
-# Session Lifecycle, Proposal Format, and Ledger Format
+# Session Protocol — Lifecycle, Proposal Format, and Ledger Format
 
 ## Session Types
 

specsmith/templates/readme.md.j2

@@ -7,7 +7,7 @@
 
 ## Status
 
-**Phase:** Scaffold complete — no runtime code yet.
+**Phase:** {{ aee_phase_emoji }} {{ aee_phase_label }} (`{{ aee_phase }}`)
 
 ## Target Platforms