Skip to content

Commit e19c000

Browse files
tbitcsoz-agent
tbitcs
and
oz-agent
committed
feat: AEE epistemic layer, agentic client, auth, workspace, watch, patent, auto-update (#10 #16 #17 #37 #52)
Applied Epistemic Engineering (AEE): - epistemic standalone library (src/epistemic/) - zero deps, works in any Python 3.10+ project BeliefArtifact, StressTester, FailureModeGraph, CertaintyEngine, RecoveryOperator, TraceVault, AEESession - specsmith.epistemic compatibility shim (re-exports from epistemic) - src/specsmith/trace.py (STP-inspired cryptographic sealing) - ledger.py: CryptoAuditChain SHA-256 chaining for tamper-evident ledger - 8 new CLI commands: stress-test, epistemic-audit, belief-graph, trace, integrate, run, agent, watch - H13 hard rule (Epistemic Boundaries Required) in governance templates - 4 new governance templates: epistemic-axioms, belief-registry, failure-modes, uncertainty-map - 3 new project types: epistemic-pipeline, knowledge-engineering, aee-research - scaffolder.py: epistemic templates rendered for epistemic project types - 25 new tests (all pass), lint clean Agentic client (src/specsmith/agent/): - specsmith run - AEE-integrated REPL (Anthropic/OpenAI/Gemini/Ollama, all optional) - specsmith agent providers/tools/skills - 20 specsmith commands as native tools with epistemic contracts - HookRegistry (H13 enforcement, ledger hints, context budget warning) - SKILL.md loader with domain priority (epistemic > governance > testing > vcs) - Built-in profiles: planner, verifier, epistemic-auditor Issue resolutions: - Closes #37: specsmith auth set/list/remove/check (OS keyring > file; tokens never logged) - Closes #17: specsmith workspace init/audit/export (workspace.yml multi-project governance) - Closes #16: specsmith watch (polling daemon, LEDGER.md staleness alerts) - Closes #10: specsmith patent search/prior-art (USPTO ODP API, key-term extraction) - Closes #52: CreditBudget.enforcement_mode soft|hard, specsmith credits check, credits budget --enforcement Auto-update: - _AutoUpdateGroup checks scaffold.yml spec_version on every command - Prompts Y/n to migrate if outdated; skippable via SPECSMITH_NO_AUTO_UPDATE=1 RTD / PyPI badge fixes: - dev-release.yml: validates RTD_TOKEN, prints HTTP status, explains Option A/B for 'latest' - README badge: ?include_prereleases=true - releasing.md: complete root-cause diagnosis and step-by-step fix instructions Co-Authored-By: Oz <oz-agent@warp.dev>
1 parent aefa6c4 commit e19c000

62 files changed

Lines changed: 11064 additions & 57 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: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,48 @@ jobs:
8181
runs-on: ubuntu-latest
8282
continue-on-error: true
8383
steps:
84-
- name: Trigger ReadTheDocs build for develop
84+
- name: Trigger ReadTheDocs builds (develop + latest)
85+
env:
86+
RTD_TOKEN: ${{ secrets.RTD_TOKEN }}
8587
run: |
86-
curl -s -X POST \
87-
-H "Authorization: Token ${{ secrets.RTD_TOKEN }}" \
88-
"https://readthedocs.org/api/v3/projects/specsmith/versions/develop/builds/"
88+
if [ -z "$RTD_TOKEN" ]; then
89+
echo "WARNING: RTD_TOKEN secret is not set. Skipping RTD build trigger."
90+
echo "To fix: go to GitHub repo Settings → Secrets → Actions and add RTD_TOKEN."
91+
echo "Get the token from: https://readthedocs.org/accounts/tokens/"
92+
exit 0
93+
fi
94+
95+
# Trigger the 'develop' RTD version build (accessible at /en/develop/)
96+
echo "Triggering RTD build for 'develop' version..."
97+
STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
98+
-H "Authorization: Token $RTD_TOKEN" \
99+
"https://readthedocs.org/api/v3/projects/specsmith/versions/develop/builds/")
100+
echo "RTD develop build trigger: HTTP $STATUS"
101+
if [ "$STATUS" != "202" ]; then
102+
echo "WARNING: RTD develop build trigger returned HTTP $STATUS (expected 202)."
103+
echo "Common causes:"
104+
echo " - 401: RTD_TOKEN is invalid or expired"
105+
echo " - 404: 'develop' version not activated in RTD dashboard"
106+
echo " Fix: https://readthedocs.org/projects/specsmith/versions/ → activate 'develop'"
107+
fi
108+
109+
# NOTE about RTD 'latest' version:
110+
# RTD 'latest' maps to the repository's DEFAULT BRANCH, which is 'main' (not 'develop').
111+
# To make 'latest' show dev builds, you have TWO options:
112+
#
113+
# OPTION A (recommended): Change RTD default branch to 'develop'
114+
# - RTD dashboard → specsmith project → Admin → Advanced Settings
115+
# - Set 'Default branch' to 'develop'
116+
# - After this, every push to develop auto-rebuilds /en/latest/
117+
# - The separate curl below is then optional
118+
#
119+
# OPTION B: Keep 'main' as RTD default, trigger 'latest' manually from here
120+
# - Uncomment the block below
121+
# - This overwrites 'latest' docs with develop content on every develop push
122+
# - Downside: 'latest' will show dev docs even for stable users
123+
#
124+
# OPTION B (uncomment if needed):
125+
# echo "Triggering RTD build for 'latest' version..."
126+
# curl -s -X POST \
127+
# -H "Authorization: Token $RTD_TOKEN" \
128+
# "https://readthedocs.org/api/v3/projects/specsmith/versions/latest/builds/"

‎.specsmith/model-rate-limits.json‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
[
2+
{
3+
"provider": "openai",
4+
"model": "gpt-4o",
5+
"rpm_limit": 500,
6+
"tpm_limit": 30000000,
7+
"utilization_target": 0.7,
8+
"concurrency_cap": 1,
9+
"source": "default"
10+
},
11+
{
12+
"provider": "openai",
13+
"model": "gpt-4o-mini",
14+
"rpm_limit": 500,
15+
"tpm_limit": 200000000,
16+
"utilization_target": 0.7,
17+
"concurrency_cap": 1,
18+
"source": "default"
19+
},
20+
{
21+
"provider": "openai",
22+
"model": "gpt-4-turbo",
23+
"rpm_limit": 500,
24+
"tpm_limit": 800000,
25+
"utilization_target": 0.7,
26+
"concurrency_cap": 1,
27+
"source": "default"
28+
},
29+
{
30+
"provider": "openai",
31+
"model": "gpt-3.5-turbo",
32+
"rpm_limit": 3500,
33+
"tpm_limit": 90000,
34+
"utilization_target": 0.7,
35+
"concurrency_cap": 1,
36+
"source": "default"
37+
},
38+
{
39+
"provider": "openai",
40+
"model": "o1",
41+
"rpm_limit": 500,
42+
"tpm_limit": 30000000,
43+
"utilization_target": 0.7,
44+
"concurrency_cap": 1,
45+
"source": "default"
46+
},
47+
{
48+
"provider": "openai",
49+
"model": "o1-mini",
50+
"rpm_limit": 1000,
51+
"tpm_limit": 200000000,
52+
"utilization_target": 0.7,
53+
"concurrency_cap": 1,
54+
"source": "default"
55+
},
56+
{
57+
"provider": "openai",
58+
"model": "o3-mini",
59+
"rpm_limit": 1000,
60+
"tpm_limit": 200000000,
61+
"utilization_target": 0.7,
62+
"concurrency_cap": 1,
63+
"source": "default"
64+
},
65+
{
66+
"provider": "openai",
67+
"model": "gpt-5.4",
68+
"rpm_limit": 60,
69+
"tpm_limit": 500000,
70+
"utilization_target": 0.7,
71+
"concurrency_cap": 1,
72+
"source": "default"
73+
},
74+
{
75+
"provider": "openai",
76+
"model": "*",
77+
"rpm_limit": 500,
78+
"tpm_limit": 500000,
79+
"utilization_target": 0.7,
80+
"concurrency_cap": 1,
81+
"source": "default"
82+
},
83+
{
84+
"provider": "anthropic",
85+
"model": "claude-opus-4",
86+
"rpm_limit": 2000,
87+
"tpm_limit": 40000000,
88+
"utilization_target": 0.7,
89+
"concurrency_cap": 1,
90+
"source": "default"
91+
},
92+
{
93+
"provider": "anthropic",
94+
"model": "claude-sonnet-4",
95+
"rpm_limit": 2000,
96+
"tpm_limit": 40000000,
97+
"utilization_target": 0.7,
98+
"concurrency_cap": 1,
99+
"source": "default"
100+
},
101+
{
102+
"provider": "anthropic",
103+
"model": "claude-haiku-3-5",
104+
"rpm_limit": 2000,
105+
"tpm_limit": 200000000,
106+
"utilization_target": 0.7,
107+
"concurrency_cap": 1,
108+
"source": "default"
109+
},
110+
{
111+
"provider": "anthropic",
112+
"model": "claude-3-5-sonnet",
113+
"rpm_limit": 2000,
114+
"tpm_limit": 40000000,
115+
"utilization_target": 0.7,
116+
"concurrency_cap": 1,
117+
"source": "default"
118+
},
119+
{
120+
"provider": "anthropic",
121+
"model": "claude-3-5-haiku",
122+
"rpm_limit": 2000,
123+
"tpm_limit": 200000000,
124+
"utilization_target": 0.7,
125+
"concurrency_cap": 1,
126+
"source": "default"
127+
},
128+
{
129+
"provider": "anthropic",
130+
"model": "claude-3-opus",
131+
"rpm_limit": 2000,
132+
"tpm_limit": 40000000,
133+
"utilization_target": 0.7,
134+
"concurrency_cap": 1,
135+
"source": "default"
136+
},
137+
{
138+
"provider": "anthropic",
139+
"model": "*",
140+
"rpm_limit": 2000,
141+
"tpm_limit": 40000000,
142+
"utilization_target": 0.7,
143+
"concurrency_cap": 1,
144+
"source": "default"
145+
},
146+
{
147+
"provider": "google",
148+
"model": "gemini-1.5-pro",
149+
"rpm_limit": 360,
150+
"tpm_limit": 4000000,
151+
"utilization_target": 0.7,
152+
"concurrency_cap": 1,
153+
"source": "default"
154+
},
155+
{
156+
"provider": "google",
157+
"model": "gemini-1.5-flash",
158+
"rpm_limit": 1000,
159+
"tpm_limit": 4000000,
160+
"utilization_target": 0.7,
161+
"concurrency_cap": 1,
162+
"source": "default"
163+
},
164+
{
165+
"provider": "google",
166+
"model": "gemini-2.0-flash",
167+
"rpm_limit": 1000,
168+
"tpm_limit": 4000000,
169+
"utilization_target": 0.7,
170+
"concurrency_cap": 1,
171+
"source": "default"
172+
},
173+
{
174+
"provider": "google",
175+
"model": "gemini-2.5-pro",
176+
"rpm_limit": 360,
177+
"tpm_limit": 4000000,
178+
"utilization_target": 0.7,
179+
"concurrency_cap": 1,
180+
"source": "default"
181+
},
182+
{
183+
"provider": "google",
184+
"model": "*",
185+
"rpm_limit": 360,
186+
"tpm_limit": 4000000,
187+
"utilization_target": 0.7,
188+
"concurrency_cap": 1,
189+
"source": "default"
190+
}
191+
]

‎AGENTS.md‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,16 @@
22

33
## Identity
44
- **Project**: specsmith
5-
- **Type**: CLI tool (Python) — Spec Section 17.3
6-
- **Spec version**: 0.1.0-alpha.1
5+
- **Type**: CLI tool (Python) + AEE library — Spec Section 17.3
6+
- **Spec version**: 0.3.0-alpha.1
77
- **Language**: Python 3.10+
88
- **Platforms**: Windows, Linux, macOS
99

1010
## Purpose
11-
Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
11+
Applied Epistemic Engineering toolkit for AI-assisted development. Treats belief systems
12+
like code: codable, testable, deployable. Co-installs the `epistemic` standalone library.
13+
Includes an AEE-integrated agentic client (`specsmith run`) supporting Claude, GPT, Gemini,
14+
and local Ollama models.
1215

1316
## Quick Commands
1417
- `pip install -e ".[dev]"` — dev install
@@ -19,16 +22,26 @@ Forge governed project scaffolds from the Agentic AI Development Workflow Specif
1922
- `specsmith init` — scaffold a new project
2023
- `specsmith audit` — health checks
2124
- `specsmith validate` — governance consistency
25+
- `specsmith stress-test` — AEE adversarial challenges
26+
- `specsmith epistemic-audit` — full AEE pipeline
27+
- `specsmith belief-graph` — belief artifact dependency graph
28+
- `specsmith trace seal/verify/log` — cryptographic trace vault
29+
- `specsmith run` — agentic REPL (requires provider)
30+
- `specsmith agent providers` — check provider status
2231

2332
## File Registry
24-
- `src/specsmith/` — package source
25-
- `src/specsmith/templates/` — Jinja2 scaffold templates
33+
- `src/specsmith/` — specsmith CLI package
34+
- `src/epistemic/` — standalone AEE library (canonical location)
35+
- `src/specsmith/epistemic/` — compatibility shim (re-exports from epistemic)
36+
- `src/specsmith/agent/` — agentic client (providers, tools, runner, hooks, skills)
37+
- `src/specsmith/templates/` — Jinja2 scaffold templates (incl. 4 new epistemic templates)
2638
- `src/specsmith/integrations/` — agent platform adapters
2739
- `tests/` — test suite
28-
- `docs/REQUIREMENTS.md` — formal requirements (37 REQs)
29-
- `docs/TEST_SPEC.md` — test specifications (30 TESTs)
40+
- `docs/REQUIREMENTS.md` — formal requirements
41+
- `docs/TEST_SPEC.md` — test specifications
3042
- `docs/governance/` — modular governance docs
31-
- `docs/AGENT-WORKFLOW-SPEC.md` — the specification itself
43+
- `docs/AGENT-WORKFLOW-SPEC.md` — the specification itself (v0.3.0)
44+
- `C:\Users\trist\Development\BitConcepts\everything-claude-code` — ECC reference (local clone)
3245

3346
## Governance
3447
This project follows its own specification. See:

‎CHANGELOG.md‎

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

88
## [Unreleased]
99

10+
## [0.3.0a1] - 2026-04-05
11+
12+
### Added — Applied Epistemic Engineering
13+
14+
- **`epistemic` standalone library** (`src/epistemic/`): zero-dep Python library co-installed with specsmith. `from epistemic import AEESession` works in any Python 3.10+ project. Seven modules: `belief.py`, `stress_tester.py`, `failure_graph.py`, `recovery.py`, `certainty.py`, `session.py`, `trace.py`.
15+
- **`AEESession`**: high-level facade bundling the full AEE pipeline (add_belief, accept, add_evidence, run, save, load, seal, verify_trace). Primary entry point for non-specsmith projects including glossa-lab, cpac, and compliance pipelines.
16+
- **`BeliefArtifact`**: fundamental AEE primitive. Requirements, decisions, and hypotheses are all BeliefArtifacts with propositions, epistemic boundaries, confidence levels, and failure modes.
17+
- **`StressTester`**: 8-category adversarial challenge engine (vagueness, falsifiability, observability, irreducibility, compound claim, no propositions, P1 confidence, logic knots).
18+
- **`FailureModeGraph`**: directed graph of stress-test→breakpoint relations with `equilibrium_check()` and `logic_knot_detect()`. Mermaid diagram rendering.
19+
- **`CertaintyEngine`**: CERTUS-inspired confidence scoring. C = base × coverage × freshness. Weakest-link propagation through inferential links.
20+
- **`RecoveryOperator`**: generates bounded `RecoveryProposal` objects for all failure modes. Never auto-applies. Ranked by severity.
21+
- **`TraceVault`** (`src/epistemic/trace.py`): STP-inspired cryptographic decision sealing. SHA-256 chain, append-only `.specsmith/trace.jsonl`.
22+
- **`CryptoAuditChain`** in `ledger.py`: SHA-256 chained hashes for all ledger entries. Tamper-evident history.
23+
- **`specsmith.epistemic`**: backward-compatible shim that re-exports everything from `epistemic`.
24+
25+
### Added — New CLI Commands
26+
27+
- **`specsmith stress-test`**: AEE adversarial stress-tests on `docs/REQUIREMENTS.md`. Text and Mermaid output.
28+
- **`specsmith epistemic-audit`**: full AEE pipeline — stress-test + failure graph + certainty scoring + recovery proposals. `--threshold` and `--mermaid` options.
29+
- **`specsmith belief-graph`**: render belief artifact dependency graph by component. Text and Mermaid.
30+
- **`specsmith trace seal/verify/log`**: cryptographic trace vault management.
31+
- **`specsmith integrate <tool>`**: epistemic impact analysis before tool adapter scaffolding.
32+
- **`specsmith run`**: AEE-integrated agentic REPL. Auto-detects provider. `--task`, `--provider`, `--model`, `--tier` options.
33+
- **`specsmith agent providers/tools/skills`**: configure and inspect the agentic client.
34+
35+
### Added — Agentic Client
36+
37+
- **`src/specsmith/agent/`**: minimal, cross-platform Python agentic client.
38+
- `core.py`: `Message`, `Tool`, `CompletionResponse`, `ModelTier`, `BaseProvider` protocol
39+
- `providers/`: Anthropic, OpenAI (incl. Ollama via compat endpoint), Gemini, Ollama (stdlib-only)
40+
- `tools.py`: 20 specsmith commands as native agent tools with epistemic contracts
41+
- `hooks.py`: `HookRegistry` with Pre/PostTool, SessionStart, SessionEnd hooks. Built-in H13 enforcement.
42+
- `skills.py`: SKILL.md loader with domain prioritization (epistemic > governance > verification > testing > vcs)
43+
- `runner.py`: REPL loop with tool execution, model routing, session state, streaming support
44+
- Built-in profiles: `planner.md`, `verifier.md`, `epistemic-auditor.md`
45+
- All LLM providers are optional extras: `pip install specsmith[anthropic]`, `specsmith[openai]`, `specsmith[gemini]`
46+
- Ollama support via stdlib `urllib` only (zero deps)
47+
- Model routing: `--tier fast/balanced/powerful` maps to appropriate models per provider
48+
49+
### Added — Project Types and Config
50+
51+
- **3 new project types**: `epistemic-pipeline` (ARE 8-phase), `knowledge-engineering`, `aee-research`
52+
- **`ProjectConfig.enable_epistemic`**: opt-in AEE governance layer
53+
- **`ProjectConfig.epistemic_threshold`**: configurable certainty threshold (default 0.7)
54+
- **`ProjectConfig.enable_trace_vault`**: opt-in cryptographic trace vault
55+
56+
### Added — Governance Templates
57+
58+
- **`epistemic-axioms.md.j2`**: 5 AEE axioms applied to the project
59+
- **`belief-registry.md.j2`**: catalog of BeliefArtifacts (decisions, assumptions, dependencies)
60+
- **`failure-modes.md.j2`**: Failure-Mode Graph document
61+
- **`uncertainty-map.md.j2`**: known unknowns and accepted uncertainties
62+
- **H13** added to `rules.md.j2`: Epistemic Boundaries Required — proposals must state assumptions
63+
- 3 new stop conditions in `rules.md.j2`: Logic Knot, P1 confidence, trace chain integrity
64+
65+
### Added — Documentation
66+
67+
- **`docs/site/aee-primer.md`**: 10-part comprehensive guide from zero AEE knowledge to full productivity. Covers theory, formal machinery, 4-step method, belief artifacts, logic knots, certainty engine, trace vault, practical workflow, domain examples, and references.
68+
- **`docs/site/epistemic-library.md`**: full API reference for the standalone `epistemic` library with integration examples for glossa-lab, compliance, and FastAPI.
69+
- RTD nav updated with "Applied Epistemic Engineering" section and "Agentic Client" section.
70+
- ECC reference cloned locally: `C:\Users\trist\Development\BitConcepts\everything-claude-code`
71+
72+
### Changed
73+
74+
- **Version**: 0.2.3 → 0.3.0a1
75+
- **Package description**: AEE-first framing
76+
- **pyproject.toml**: `epistemic` package in `package-data`, optional LLM extras (`[anthropic]`, `[openai]`, `[gemini]`, `[agent]`, `[all]`)
77+
- **AGENTS.md**: updated identity, spec version 0.3.0-alpha.1, new commands, ECC reference
78+
- **README.md**: leads with AEE identity, explains the paradigm shift, shows epistemic library usage
79+
- **mkdocs.yml**: AEE and Agentic Client nav sections, navigation.tabs feature
80+
1081
## [0.2.3] - 2026-04-03
1182

1283
### Fixed

0 commit comments

Comments
 (0)