v1.0.0 — production-ready architecture

Theme: Production-ready architecture.

The Hermes external audit (2026-05-18) verified v0.3.0 was a "good
place for an early public/open-source release" and proposed thirteen
items to harden the architecture before the project grew further.
v1.0.0 closes all of them. Effective with this release, Praxis adopts
the SemVer + deprecation policy spelled out in STABILITY.md:
CLI subcommands + flags, JSON outputs, on-disk engagement file formats,
the evidence-bundle manifest schema, environment-variable surface, and
top-level Python re-exports are now public surfaces under those
guarantees.

Correctness (Tier A)

• D-057 — Fix TUI wake/profile plumbing. action_manual_wake
  now uses load_profile(self._profile_name) instead of a hard-coded
  "default"; Orchestrator.__init__ accepts agent: Agent | None,
  removing two # type: ignore[arg-type] smells. Hermes #2.
• D-058 — WorkQueueRepo.list() filters assignee in SQL
  (indexed column) instead of after LIMIT. Fixes silent
  under-reporting when the first N rows happened to be of another
  assignee. New migration 002_workitems_assignee.sql adds the
  column + backfills via json_extract(payload_json, '$.assignee').
  Hermes #6.

Architecture foundations (Tier B)

• D-059 — New praxis.engagement.snapshot module. Three
  LLM-prompt sites (ask, check, artifact generate) now route
  through one read model (build_engagement_snapshot +
  render_snapshot_for_llm(purpose=...)). Byte-equivalent prompt
  output verified by tests against the legacy builders. Net -190
  lines of duplicated engagement-context construction. Hermes #3.
• D-060 — Atomic writes for sufficiency reports + generated
  artifacts via new praxis.storage.files.atomic_write_text. The
  audit/evidence trail is no longer at risk of partial-write
  corruption. Hermes #4.
• D-061 — Replace silent except Exception: pass with structured
  logger.warning(...) calls in the sufficiency-gate context
  builder + Priorities-screen section renderers. TUI sections render
  a dim "⚠ Could not load" marker on degradation so the operator
  sees the failure mode. Hermes #5.

Test + release quality (Tier C)

• D-062 — Real Textual pilot tests via app.run_test(): numeric-
  key screen switching, full 1→9 sweep mount, queue / priorities /
  artifact-viewer rendering, w-keybind manual wake. Shared demo-
  engagement seeder (tests/integration/_tui_seed.py) used by both
  the pilot tests and the screenshot generator so they can't drift.
  Hermes #1.
• D-063 — CI matrix extended to Python 3.13. New
  package-verification job: uv build + clean-install smoke
  (praxis version / praxis --help / praxis tui --smoke) +
  minimal-install smoke (no extras) that proves the lazy-import
  boundary holds. Hermes #8.

Maintainability (Tier D)

• D-064 — Split cli/engagement_cmd.py (1059 LOC) into a
  per-entity package (cli/engagement/glossary.py, stakeholders.py,
  …). 80–175 LOC per submodule. Byte-identical command surface; pure
  refactor verified by D-052's 12 integration tests passing
  unchanged. Hermes #7.

Surface (Tier E)

• D-065 — PII guard adds block + redact modes alongside the
  existing warn / off. PRAXIS_PII_GUARD=block refuses to send
  PII-tagged input (exits 2); =redact replaces SSNs with [SSN]
  and Luhn-valid cards with [CC] before the LLM call. Hermes #10.
• D-066 — praxis doctor rewritten as a first-run health check.
  Ten read-only checks (python_version, praxis_version, active_profile,
  model_alias, api_key_env, engagement, sqlite_state, audit_writable,
  bundled_skills, optional_extras). Output as a rich table by
  default; --json for scripting; --strict exits non-zero on
  warnings. The legacy real-LLM probe behaviour moves to
  praxis doctor probe for back-compat. Hermes #11.
• D-067 — TUI R keybind on Artifact Viewer regenerates the
  selected artifact. Worker-thread LLM call (@work(thread=True))
  keeps the UI responsive; new artifact lands as a fresh timestamped
  file (originals preserved). app.py plumbs profile_name +
  model_alias into the screen. Hermes #12.
• D-068 — New praxis export evidence command. Bundles the
  entire .praxis/ tree + a content-hashed MANIFEST.json as
  zip / tar.gz / dir. Deterministic hashes (sorted walk) for
  audit-trust. Hermes called this "the strongest v1.0
  differentiator." Hermes #13.

Quality

• 657 tests passing (was 624 at v0.4.0, +33), coverage 85.10%.
• CI green on Python 3.11, 3.12, 3.13 + the new
  package-verification job.
• All four gates green per commit: pytest, ruff check,
  ruff format, mypy --strict src/praxis (125 source files).
• 13 conventional commits since v0.4.0 (D-057..D-068 + release bump).

Real-world verification

A retest of the v0.3.0 scenarios against this release is documented at
~/praxis-realworld-eval/retest-v1.0.0.md (eval workspace; not in
the repo).

Known limitations / deferred

• TUI Artifact Viewer g (new) + c (sufficiency-check row)
  keybinds — Hermes's spec lists 4 keybinds; v1.0 ships r + R.
  Queued for v1.1.
• Profile-level pii_guard_mode field + per-command
  --pii-guard flag — env-var only today (Hermes #10 minimum spec).
  Queued.
• praxis import evidence <bundle> to restore from an evidence
  bundle — natural follow-up to D-068. Queued.
• GPG signing of MANIFEST.json — defer until a security-audit-
  driven request appears.
• PyPI publish — the uv tool install git+...@v1.0.0 form
  remains the install path. PyPI listing is queued for v1.0.1.
• run_cmd.py:status + TUI engagement_screen / priorities_screen
  migrations to the EngagementSnapshot read model (D-059b
  follow-up). The architectural foundation is in place; those
  callers will plug in incrementally.

v0.4.0 — adoption-surface batch

Theme: Adoption surface — scriptable chat, friendlier errors, completed CRUD.

Three focused features that close the v0.4.0 Tier 2 plan (D-050 / D-051 /
D-052). All three target adoption: making the CLI usable from scripts /
CI, making transport failures self-actionable, and completing the gaps
in the engagement-entity verbs that previous releases left behind.

Added

• D-050 — praxis chat --message/-m "..." runs one turn through
  the full ChatRuntime (tools, session, slash commands) and exits 0.
  The REPL banner is suppressed so stdout stays clean for callers piping
  into jq or similar. PII guard (D-043) still fires on the single
  turn. Difference vs. praxis ask: chat -m keeps the runtime, so the
  agent can call engagement / queue tools; ask is stateless.

• D-052 — Completed CRUD verbs on praxis engagement assumption
  and praxis engagement constraint:

  • assumption get|update|remove
  • constraint get|update|remove

  Updates are partial (only supplied flags are written) and preserve
  untouched fields including the validated flag on assumptions. Both
  get variants support --json for scripting. Closes NEW-001.

• D-052 — praxis engagement question open now accepts
  --answerers <stakeholder-ids> and --blocks <artifact-ids> (both
  comma-separated). The repo accepted these fields since 0.2.x; only
  the CLI binding was missing. Closes NEW-004.

Changed

• D-051 — Transport errors are now provider-specific and actionable.
  New praxis.transport.errors.translate_provider_exception() duck-types
  on type(exc).__module__ + class name (both OpenAI and Anthropic
  SDKs share the Stainless-generated exception hierarchy) and maps each
  kind to a tailored message:

  • auth → names the env var to set
  • permission → names the model the key lacks access to
  • rate_limit → suggests retry / tier upgrade
  • not_found → names the missing model
  • bad_request → carries the SDK's detail
  • server_error → tells the user to retry later
  • connection → blames the network with the SDK's detail
  • timeout → identifies a timed-out request

  Each TransportError carries details["kind"] so future retry logic
  can branch programmatically without string-matching. Unknown
  exceptions fall through to today's generic message — behaviour is
  strictly additive, no existing assertion breaks. Closes
  NEW-003.

Breaking (CLI)

• D-050 — praxis chat --model no longer accepts the -m short
  alias. -m is now bound to --message, matching git commit -m and
  praxis queue commit -m convention. The full --model gpt-4.1
  long form still works. --model -m is intact on artifact, check,
  and elicit (those have no --message conflict).

Documentation

• D-050 — docs/how-to/first-engagement.md gains a "Scripting and
  CI" section with a chat -m vs ask comparison table.

Quality

• 571 tests passing (+32 since v0.3.1), coverage 84.42%.
• All four gates green per commit: pytest, ruff check,
  ruff format, mypy --strict src/praxis.
• 5 conventional commits since v0.3.1 (D-050 ×2 / D-051 / D-052 + bump).

Known limitations / deferred to v1.0.0

• D-055 — Multi-engagement awareness (praxis engagements list/ show/switch, registry, TUI header) deferred. Larger feature; queued
  for a dedicated cycle.
• D-053 / D-054 / D-056 — Superseded by v1.0.0 plan items
  (D-067 TUI regenerate, D-062 pilot tests, D-066 doctor expansion).
  See ~/praxis-realworld-eval/v1.0.0-plan.md in the eval workspace.

v0.3.1 — automation patch + adoption walkthrough

Theme: Automation patch + adoption walkthrough.

A small follow-up release closing the one finding surfaced during the
v0.3.0 retest (RW-019) plus the two adoption-friction items called out
by the Hermes external audit. No runtime-behavior changes beyond the
structlog routing fix; the rest is install path, documentation, and
verification.

Fixed

• D-047 — Configure structlog at package import: route console
  output to stderr (PrintLoggerFactory(file=sys.stderr)), filter at
  WARNING level by default, opt-in DEBUG via PRAXIS_DEBUG=1. The
  default factory previously wrote to stdout, which corrupted
  praxis ... --json | jq pipelines whenever an audit event fired.
  Audit JSONL on-disk writes are unaffected — those use direct file
  opens, not structlog. Closes RW-019.

Added

• D-048 — README now leads with a one-command install:
  uv tool install --python 3.12 "praxis-ba[all] @ git+...@v0.3.1".
  Drops praxis onto your PATH in an isolated environment. The
  git clone + uv sync form is retained as "Development install."
  A real PyPI publish is queued for a future release.
• D-049 — New docs/how-to/first-engagement.md — a full
  setup-to-output walkthrough (~540 lines) verified by cold-run on a
  fresh sandbox. Every output block is real captured stdout, not
  hand-written. Documents the actual .praxis/ layout
  (config.yaml + engagement/ subdir), the 5-column sufficiency
  table including the Blocker column, and the full timestamp in the
  status snapshot's Last sufficiency value.

Changed

• D-049 — README's "Five-minute tour" (~140 lines of step-by-step
  commands) replaced with a 22-line "Quick start" that links to the
  new how-to. The logo, analytical-loop diagram, and TUI gallery are
  retained at their original positions.
• D-049 — CONTRIBUTING.md adds a "must remain runnable" line
  pointing at the new how-to; CI exercises the non-LLM steps on every
  push (tests/integration/test_tour_offline.py, 7 tests).

Quality

• 539 tests passing (+10 since v0.3.0), coverage 84.39%.
• All four gates green per commit: pytest, ruff check,
  ruff format, mypy --strict src/praxis.
• 7 conventional commits since v0.3.0 (D-047 / D-049 ×3 / D-048 +
  one image-restoration commit + version bump).

Known limitations / deferred work

• Real pip install praxis-ba from PyPI is still queued (D-048
  Option A); the uv tool install form documented here is the
  supported one-command install path until then.
• The how-to's LLM-using steps (ask, check, elicit, artifact generate)
  are exercised by the documented cold-run procedure, not by CI.
• All Hermes-review items that aren't part of v0.3.1 (architectural
  hardening — TUI wake plumbing, EngagementSnapshot read model, atomic
  writes, real Textual pilot tests, etc.) are queued for v1.0.0 (see
  the v1.0.0 plan in the eval workspace).

v0.3.0 — Agent-led, end-to-end + live TUI

Praxis v0.3.0 — Agent-led, end-to-end + live TUI

Pipeline coherence (Batch 3 / RW closures):
D-036 check prints next-step elicit hint (RW-003)
D-037 artifact generate binds latest sufficiency report (RW-009)
D-038 sufficiency gate reads full decision bodies + constraints (RW-004)
D-039 wake items populate related_artifact_ids / related_question_ids (RW-013)

Polish (Batch 4):
D-040 full status snapshot + real engagement name (RW-005)
D-041 artifact list accepts --profile for consistency (RW-008)
D-042 queue commit --message alias for --note (RW-014)
D-043 PII guard on ask/chat input (RW-018)

TUI workspace:
D-044 live auto-refresh on Backlog + Work Queue (Textual set_interval)
D-045 new Priorities screen (screen 8 — top critical, oldest unanswered,
top active work items, insufficient artifacts)
D-046 new Artifact Viewer screen (screen 9 — DataTable + rendered Markdown)

Quality: 529 tests passing (+58 from v0.2.1), coverage 84.36%, ruff +
mypy clean. 11 conventional commits + this release commit.

All 18 RW-XXX findings from the v0.2.0 real-world scenario test are
now closed across v0.2.1 (9) and v0.3.0 (the remainder).

See CHANGELOG.md for details.

v0.2.1 — Trustable Surface + Proactive Cycle

Praxis v0.2.1 — Trustable Surface + Proactive Cycle

Closes 9 RW-XXX findings from the v0.2.0 real-world scenario test:

Batch 1 — Trustable Surface:
D-028 ask engagement-aware + flag-uncertainty guard (RW-002/006/007)
D-029 active default profile resolved in 6 BA commands (RW-001)
D-030 --json outputs bypass Rich wrapping; jq-safe everywhere (RW-017)
D-031 queue default shows all assignees; +--assignee/--human-only (RW-010)

Batch 2 — Proactive Cycle:
D-032 WorkQueueRepo.enqueue_deduped + wake dedup (RW-011)
D-033 wake reads state diff since last wake (RW-015)
D-034 wake enqueues actionable elicit task (RW-016)
D-035 real audit_event_count in WakeReport via counted() (RW-012)

Quality: 471 tests passing (+32 from v0.2.0), coverage 84.07%,
ruff + mypy clean. 9 conventional commits (8 fixes + 1 release).

See CHANGELOG.md for details.

v0.2.0

Release title:

 Praxis-Engine v0.2.0                                                                                                                                                                                                                         
                                                                                                                                                                                                                                              
 Release description:                                                                                                                                                                                                                         
                                                                                                                                                                                                                                              
 Praxis-Engine v0.2.0 focuses on making the TUI useful as a real operating surface, improving artifact generation, and aligning CLI/runtime behavior after the v0.1.1 stabilization release.                                                  
                                                                                                                                                                                                                                              
 Highlights                                                                                                                                                                                                                                   
                                                                                                                                                                                                                                              
 - TUI chat now uses the real backend agent runtime instead of the previous placeholder “Agent processing...” behavior.                                                                                                                       
 - CLI chat runtime was refactored into shared backend code so CLI and TUI chat paths stay aligned.                                                                                                                                           
 - praxis tui --screen now honors the requested initial screen.                                                                                                                                                                               
 - Added new TUI screens for:                                                                                                                                                                                                                 
   - backlog artifacts                                                                                                                                                                                                                        
   - configuration visibility                                                                                                                                                                                                                 
   - project setup guidance                                                                                                                                                                                                                   
 - Added artifact generation support, including:                                                                                                                                                                                              
   - artifact models                                                                                                                                                                                                                          
   - service layer                                                                                                                                                                                                                            
   - praxis artifact CLI command support                                                                                                                                                                                                      
 - Improved engagement/config discovery so Praxis only treats a directory as an engagement when a real engagement config exists.                                                                                                              
 - Improved CLI JSON output behavior for artifact, session, and tool commands.                                                                                                                                                                
 - Updated package metadata to v0.2.0.                                                                                                                                                                                                        
 - Refreshed uv.lock for the full extras dependency set.                                                                                                                                                                                      
                                                                                                                                                                                                                                              
 Validation                                                                                                                                                                                                                                   
                                                                                                                                                                                                                                              
 This release was verified locally with the full quality gate suite:                                                                                                                                                                          
                                                                                                                                                                                                                                              
 bash                                                                                                                                                                                                                                         
 uv run pytest -q                                                                                                                                                                                                                             
 uv run ruff check .                                                                                                                                                                                                                          
 uv run ruff format --check .                                                                                                                                                                                                                 
 uv run mypy src/praxis                                                                                                                                                                                                                       
                                                                                                                                                                                                                                              
 Results:                                                                                                                                                                                                                                     
                                                                                                                                                                                                                                              
 text                                                                                                                                                                                                                                         
 433 passed in 19.27s                                                                                                                                                                                                                         
 Required test coverage of 80% reached. Total coverage: 83.68%                                                                                                                                                                                ...

v0.1.1 — Defect Fixes

v0.1.1 — Defect Fixes

Addresses 20 defects (1 blocker, 8 major, 8 minor, 3 nits) found during the v0.1.0 post-release evaluation.

Highlights

• Documentation & first-run setup — Added prerequisites, offline/online command matrix, fixed clone URL, prefixed source-install commands with uv run (D-001, D-002, D-003)
• Version bump — pyproject.toml now reads 0.1.0 (D-004)
• Profile creation UX — profile create accepts --provider, --model, --api-key-env, --set-default; first profile auto-defaults (D-009, D-016)
• Error handling — Clean error messages for malformed YAML, transport/auth failures, invalid skill frontmatter, and non-file storage paths; PRAXIS_DEBUG=1 for full tracebacks (D-011, D-012, D-018, D-020)
• Audit correctness — Engagement CLI commands now write per-engagement audit events (D-006)
• Engagement CLI completeness — Added assumption and constraint subcommands; glossary search covers definitions/notes/sources; decisions reject self-supersede; Rich markup no longer eats [id] strings (D-005, D-007, D-013, D-014)
• Profile resolution — run and wake resolve profile via config instead of hard-coding "default" (D-008)
• Config show — Reports active: false when no engagement found (D-010)
• Skill filtering — _-prefixed categories hidden in production (D-015)
• TUI smoke test — praxis tui --smoke for headless CI validation (D-017)
• Tool invoke — praxis tool invoke NAME --args-json '{}' for direct CLI tool execution (D-019)

Quality

• 416 tests passing
• ruff check / format clean
• mypy strict clean