Skip to content

Commit 2532eb1

Browse files
tbitcsoz-agent
tbitcs
and
oz-agent
committed
release: merge develop into main for v0.2.0
Co-Authored-By: Oz <oz-agent@warp.dev>
2 parents 76605f9 + 22f0b5b commit 2532eb1

75 files changed

Lines changed: 5245 additions & 304 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/dev-release.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Dev Release
2+
3+
on:
4+
push:
5+
branches: [develop]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
dev-build:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v6
16+
with:
17+
fetch-depth: 0
18+
19+
- uses: actions/setup-python@v6
20+
with:
21+
python-version: "3.12"
22+
cache: pip
23+
24+
- name: Install build tools
25+
run: pip install build
26+
27+
- name: Set dev version
28+
run: |
29+
# Read base version and bump patch for dev
30+
BASE_VERSION=$(grep 'version = ' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
31+
MAJOR=$(echo $BASE_VERSION | cut -d. -f1)
32+
MINOR=$(echo $BASE_VERSION | cut -d. -f2)
33+
PATCH=$(echo $BASE_VERSION | cut -d. -f3)
34+
NEXT_PATCH=$((PATCH + 1))
35+
COMMIT_COUNT=$(git rev-list --count HEAD ^$(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~100) 2>/dev/null || echo 0)
36+
DEV_VERSION="${MAJOR}.${MINOR}.${NEXT_PATCH}.dev${COMMIT_COUNT}"
37+
echo "DEV_VERSION=${DEV_VERSION}" >> $GITHUB_ENV
38+
39+
# Patch pyproject.toml with dev version
40+
sed -i "s/version = \"${BASE_VERSION}\"/version = \"${DEV_VERSION}\"/" pyproject.toml
41+
echo "Building version: ${DEV_VERSION}"
42+
43+
- run: python -m build
44+
45+
- name: Upload build artifacts
46+
uses: actions/upload-artifact@v7
47+
with:
48+
name: dev-dist
49+
path: dist/
50+
51+
pypi-dev-publish:
52+
needs: dev-build
53+
runs-on: ubuntu-latest
54+
environment: pypi
55+
permissions:
56+
id-token: write
57+
continue-on-error: true
58+
steps:
59+
- uses: actions/download-artifact@v8
60+
with:
61+
name: dev-dist
62+
path: dist/
63+
- name: Publish dev release to PyPI
64+
uses: pypa/gh-action-pypi-publish@release/v1
65+
66+
docs-build:
67+
needs: dev-build
68+
runs-on: ubuntu-latest
69+
continue-on-error: true
70+
steps:
71+
- name: Trigger ReadTheDocs build for develop
72+
run: |
73+
curl -s -X POST \
74+
-H "Authorization: Token ${{ secrets.RTD_TOKEN }}" \
75+
"https://readthedocs.org/api/v3/projects/specsmith/versions/develop/builds/"

‎.github/workflows/release.yml‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,22 @@ permissions:
88
contents: write
99

1010
jobs:
11+
test:
12+
runs-on: ubuntu-latest
13+
if: github.ref_type == 'tag'
14+
steps:
15+
- uses: actions/checkout@v6
16+
- uses: actions/setup-python@v6
17+
with:
18+
python-version: "3.12"
19+
cache: pip
20+
- run: pip install -e ".[dev]"
21+
- run: ruff check src/
22+
- run: mypy src/specsmith --ignore-missing-imports
23+
- run: pytest tests/ -x -q
24+
1125
build:
26+
needs: test
1227
runs-on: ubuntu-latest
1328
steps:
1429
- uses: actions/checkout@v6
@@ -47,7 +62,8 @@ jobs:
4762
environment: pypi
4863
permissions:
4964
id-token: write
50-
# Skip gracefully if pypi environment is not configured yet
65+
# Only publish from main branch tags — never from develop or feature branches
66+
if: github.event.base_ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')
5167
continue-on-error: true
5268
steps:
5369
- uses: actions/download-artifact@v8

‎.warp/rules/documentation-updates.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,16 @@ Before every release:
5454
- Verify install commands say `pip install specsmith` (no `--pre` for stable)
5555
- Follow the full checklist in `docs/site/releasing.md`
5656

57+
## Branch Protection
58+
59+
- **NEVER tag a stable release on develop.** Tags must only be created on main.
60+
- **NEVER push tags from develop.** The stable release workflow publishes to PyPI — only main branch releases are allowed.
61+
- All feature work happens on develop. Stable releases merge develop → main first, then tag on main.
62+
- **Dev releases are automatic.** Every push to develop triggers `.devN` pre-release to PyPI.
63+
- Dev releases use `X.Y.(Z+1).devN` version suffix — always the NEXT patch version, not the current.
64+
- Example: if stable is `0.1.3`, dev builds are `0.1.4.dev1`, `0.1.4.dev2`, etc.
65+
- Install dev builds: `pip install --pre specsmith`
66+
5767
## Rule
5868

5969
If any documentation update is needed, make the updates in the SAME commit as the code changes — do not defer documentation to a separate commit.

‎.warp/rules/kr260-board-identity.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# KR260 Board Identity — COM Port Safety Rule
2+
3+
## Rule
4+
5+
**NEVER assume which COM port corresponds to kria-a or kria-b based on port number or
6+
position alone.** COM port assignments can change across reboots, USB hub resets, cable
7+
swaps, or OS re-enumeration events.
8+
9+
## Required Practice
10+
11+
Before issuing any board-specific command, configuration, or measurement over a serial
12+
console (COM port), **always verify the hostname first**:
13+
14+
```
15+
login: atomicrail
16+
password: ...
17+
atomicrail@kria-a:~$ ← confirm this matches your intent
18+
```
19+
20+
Or, if already logged in:
21+
22+
```bash
23+
hostname
24+
```
25+
26+
## Background
27+
28+
On 2026-04-02, after flashing and rebooting both KR260 boards, the COM port assignments
29+
were found to be **swapped relative to the previous session**. What was kria-a's port
30+
is now kria-b's port and vice versa. This was only caught because the board banner and
31+
hostname were checked in the boot log.
32+
33+
## Scope
34+
35+
Applies to all dual-board KR260 (kria-a / kria-b) lab work in the AtomicRail / cpsc-engine-rtl
36+
project whenever serial consoles, minicom/PuTTY/Warp sessions, or any tool that references
37+
a COM port by name or number is used.
38+
39+
## Consequence of Violation
40+
41+
Running a benchmark, flashing a bitstream, or modifying network configuration on the wrong
42+
board produces invalid results and may require board recovery.

‎.warp/rules/no-hardcoded-versions.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# No Hardcoded Versions Rule
2+
3+
## Policy
4+
5+
Version strings MUST NOT be hardcoded in documentation, tests, or application code outside of `pyproject.toml`.
6+
7+
## Single Source of Truth
8+
9+
- **`pyproject.toml`** `version` field is the sole source of truth for the package version.
10+
- **`__init__.py`** reads the version at runtime via `importlib.metadata.version()`.
11+
- **Documentation** uses `{{ version }}` placeholders resolved by a MkDocs hook at build time.
12+
- **Tests** compare against `importlib.metadata.version()`, never hardcoded strings.
13+
14+
## What to Check
15+
16+
Before every commit, verify:
17+
18+
- No literal version strings (e.g., `0.1.3`, `0.2.0`) appear in:
19+
- `docs/site/*.md` — use `{{ version }}` instead
20+
- Test assertions — use `from specsmith import __version__` or `importlib.metadata`
21+
- README.md badge text — use shields.io dynamic badges
22+
- Troubleshooting docs — say "latest version" not "v0.1.x+"
23+
- `pyproject.toml` is the ONLY file that contains the actual version number
24+
- `__init__.py` fallback value is only for uninstalled source runs
25+
26+
## For Managed Projects
27+
28+
Projects scaffolded by specsmith follow the same pattern:
29+
- `init.py.j2` generates `importlib.metadata.version()` code
30+
- `pyproject.toml.j2` sets the initial version; all other code reads it dynamically
31+
- CI dev-release workflows calculate dev versions from git tags, not source files
32+
33+
## Release Process
34+
35+
When bumping versions, `specsmith release` updates `pyproject.toml` (the source of truth). The releaser also updates `config.py` spec_version default so new scaffolds use the current version. No other files need version string changes.

‎CHANGELOG.md‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.2.0] - 2026-04-02
11+
12+
### Added
13+
- **Community templates** (#42): `CONTRIBUTING.md`, `LICENSE` (MIT/Apache-2.0), `SECURITY.md`, `CODE_OF_CONDUCT.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `.github/ISSUE_TEMPLATE/` (bug report + feature request). Config fields: `license` (default MIT), `community_files` list.
14+
- **AI credit tracking** (#50): `specsmith credits` subcommand group — record, summary, report, analyze, budget. Tracks tokens/cost per session, model, provider, and task. JSON storage at `.specsmith/credits.json`.
15+
- **Credit spend analysis** (#51): `specsmith credits analyze` detects model inefficiency, token waste, governance bloat, cost trends. Generates optimization recommendations with estimated savings.
16+
- **Credit budget/watermarks**: `specsmith credits budget --cap 50 --watermarks 5,10,25,50`. Monthly caps, alert thresholds, watermark notifications.
17+
- **Auto-init credit tracking**: `init`, `import`, and `upgrade` all create `.specsmith/credit-budget.json` with unlimited default budget. `.specsmith/` gitignored.
18+
- **`specsmith architect`** (#49): interactive architecture generation — scans project, interviews user about components/data flow/deployment, generates rich `docs/ARCHITECTURE.md`.
19+
- **`specsmith self-update`**: auto-detects channel (stable/dev), supports `--channel` override and `--version` pinning.
20+
- **Multi-language detection**: importer detects and reports all significant languages (primary + secondary).
21+
- **Dynamic versioning**: `__version__` reads from `importlib.metadata`. Docs use `{{ version }}` hook. Tests are version-agnostic.
22+
- **Dev-release workflow for managed projects** (#35): gitflow + GitHub + Python generates `.github/workflows/dev-release.yml`.
23+
- **Type-specific templates**: .gitattributes (#39) for 15 language types, .gitignore (#40) expanded for all 30 types, .editorconfig (#43) with per-language indent settings.
24+
- **Yocto/bitbake/devicetree/markdown**: `.bbclass`, `.inc`, `.dts`, `.dtsi` in language detection; `kas.yml` build system; enhanced CI metadata.
25+
- **No-hardcoded-versions rule** (H10): governance template and WARP rule.
26+
- **Agent credit instructions**: Warp and Claude adapters include credit recording commands.
27+
- **Session-end credit summary**: `session-end` shows total spend and budget alerts.
28+
- **VCS commands**: `specsmith commit`, `push`, `sync`, `branch`, `pr`, `session-end` for governed git workflows.
29+
- **Structured ledger CLI**: `specsmith ledger add/list/stats` for append-only change tracking.
30+
- **Requirements CLI**: `specsmith req list/add/trace/coverage` for requirements management.
31+
- **Test gap analysis**: `specsmith test gaps/orphans/summary` for REQ↔TEST coverage.
32+
- **Plugin system scaffold**: `specsmith plugin list`, entry-point-based extensibility.
33+
34+
### Fixed
35+
- **Import with large AGENTS.md** (#46): broader keyword extraction, diff marker stripping, paragraph dedup, existing doc detection.
36+
- **UnboundLocalError on import** with existing docs: scoping fix for REQUIREMENTS/TEST_SPEC/architecture skip logic.
37+
- **Audit false positive**: architecture docs found in subdirectories (e.g., `docs/architecture/DESIGN.md`).
38+
- **`audit --fix`** now generates missing recommended files (ARCHITECTURE.md from scan, REQUIREMENTS.md, TEST_SPEC.md stubs).
39+
- **Topic-aware section classification** (#47): body content keywords route sections to correct governance files.
40+
- **Type-specific audit thresholds** (#48): FPGA/embedded get higher limits (rules=1000, verification=600).
41+
42+
### Changed
43+
- **Uppercase governance filenames**: all scaffolded markdown files use uppercase stems (RULES.md, WORKFLOW.md, ROLES.md, CONTEXT-BUDGET.md, VERIFICATION.md, DRIFT-METRICS.md, ARCHITECTURE.md). Upgrader auto-migrates legacy lowercase filenames on both case-sensitive and case-insensitive filesystems.
44+
- Auditor now recommends `CONTRIBUTING.md` and `LICENSE`.
45+
- RTD default version set to `stable`, default branch set to `develop`.
46+
- Docs version references use dynamic `{{ version }}` instead of hardcoded strings.
47+
- `init.py.j2` template for managed projects uses `importlib.metadata` pattern.
48+
- Governance file size thresholds raised globally (rules=800, verification=400).
49+
- Yocto toolset: added `testimage`, `yocto-check-layer` compliance.
50+
- Release workflow now runs full test suite before building.
51+
1052
## [0.1.3] - 2026-04-01
1153

1254
### Fixed
@@ -129,7 +171,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
129171
- **G9**: Session start file list now marks services.md as conditional ("if it exists").
130172
- **G10**: Open TODOs format specified as `- [ ]` / `- [x]` checkbox syntax.
131173

132-
[Unreleased]: https://github.com/BitConcepts/specsmith/compare/v0.1.3...HEAD
174+
[Unreleased]: https://github.com/BitConcepts/specsmith/compare/v0.2.0...HEAD
175+
[0.2.0]: https://github.com/BitConcepts/specsmith/compare/v0.1.3...v0.2.0
133176
[0.1.3]: https://github.com/BitConcepts/specsmith/compare/v0.1.2...v0.1.3
134177
[0.1.2]: https://github.com/BitConcepts/specsmith/compare/v0.1.1...v0.1.2
135178
[0.1.1]: https://github.com/BitConcepts/specsmith/compare/v0.1.0...v0.1.1

‎README.md‎

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
# specsmith
22

33
[![CI](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml)
4-
[![Docs](https://readthedocs.org/projects/specsmith/badge/?version=latest)](https://specsmith.readthedocs.io/en/latest/)
5-
[![PyPI](https://img.shields.io/pypi/v/specsmith?style=flat&color=blue)](https://pypi.org/project/specsmith/)
4+
[![Docs](https://readthedocs.org/projects/specsmith/badge/?version=stable)](https://specsmith.readthedocs.io/en/stable/)
5+
[![PyPI Stable](https://img.shields.io/pypi/v/specsmith?label=stable&style=flat&color=blue)](https://pypi.org/project/specsmith/)
6+
[![PyPI Dev](https://img.shields.io/pypi/v/specsmith?include_prereleases&label=dev&style=flat&color=orange)](https://pypi.org/project/specsmith/#history)
67
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
78
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
89

@@ -35,14 +36,36 @@ pip install specsmith
3536
## Quick Start
3637

3738
```bash
38-
specsmith init # New project (interactive)
39-
specsmith init --config scaffold.yml # New project (from config)
40-
specsmith import --project-dir ./my-project # Adopt existing project
41-
specsmith audit --project-dir ./my-project # Health check
42-
specsmith export --project-dir ./my-project # Compliance report
43-
specsmith doctor --project-dir ./my-project # Tool check
39+
# Install
40+
pip install specsmith
41+
42+
# New project (interactive)
43+
specsmith init
44+
45+
# Adopt an existing project
46+
specsmith import --project-dir ./my-project
47+
48+
# Check governance health
49+
specsmith audit --project-dir ./my-project
50+
51+
# Generate architecture docs interactively
52+
specsmith architect --project-dir ./my-project
53+
54+
# Start an AI agent session (universal pattern)
55+
# From any governed repo root:
56+
/agent AGENTS.md
4457
```
4558

59+
### Starting an AI Agent Session
60+
61+
The universal pattern for any specsmith-governed project:
62+
63+
```
64+
/agent AGENTS.md
65+
```
66+
67+
This works in Warp, Claude Code, Cursor, and any agent that reads markdown context files. The agent loads AGENTS.md (the governance hub), reads LEDGER.md for session state, and picks up from the last recorded action.
68+
4669
## 30 Project Types
4770

4871
**Software:** Python, Rust, Go, C/C++, .NET, JS/TS, mobile, monorepo, microservices, DevOps/IaC, data/ML, browser extensions.
@@ -55,20 +78,23 @@ specsmith doctor --project-dir ./my-project # Tool check
5578

5679
Each type gets: tool-aware CI (correct lint/test/security/build tools), domain-specific directory structure, governance rules in AGENTS.md, and pre-populated requirements and test stubs.
5780

58-
## 11 CLI Commands
81+
## 40+ CLI Commands
5982

6083
| Command | Purpose |
6184
|---------|---------|
6285
| `init` | Scaffold a new governed project |
6386
| `import` | Adopt an existing project (merge mode) |
6487
| `audit` | Drift detection and health checks (`--fix` to auto-repair) |
88+
| `architect` | Interactive architecture generation |
6589
| `validate` | Governance file consistency checks |
6690
| `compress` | Archive old ledger entries |
6791
| `upgrade` | Update governance to new spec version |
6892
| `status` | CI/PR/alert status from VCS platform |
6993
| `diff` | Compare governance against templates |
7094
| `export` | Compliance report with REQ↔TEST coverage |
7195
| `doctor` | Check if verification tools are installed |
96+
| `self-update` | Update specsmith (channel-aware) |
97+
| `credits` | AI credit tracking, analysis, and budgets |
7298

7399
## 7 Agent Integrations
74100

0 commit comments

Comments
 (0)