specsmither-lifecycle 0.1.0__tar.gz

specsmither_lifecycle-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# --- Local-only planning docs (milestone breakdowns; not published) ---
+planner/
+
+# --- Throwaway CLI/TUI prototype (milestone 02 mock; not published) ---
+playground/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Local SQLite databases / config
+*.db
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+.specsmither/
+
+# Dev-only uv overrides (e.g. an editable ../crucible source) — kept local so
+# CI + published builds resolve crucible-forge from PyPI.
+uv.toml
+
+# Node (only used by tools/gen_*_golden.mjs to regenerate golden fixtures)
+node_modules/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/

specsmither_lifecycle-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `specsmither-lifecycle` are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/); this project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## 0.1.0
+
+First release — the pure planning-lifecycle core, extracted from the `specsmither`
+product into its own publishable distribution with **no persistence and no UI/server
+dependency** (no SQLAlchemy, no Textual, no MCP). A host embeds the planning state
+machine in-process and provides its own persistence through the `WritePlan` seam.
+
+### Added
+
+- **Pure verb surface** — `start_planning_session`, `action_planning_session`,
+  `complete_planning_session`, `inspect_planning_session`, and the handover verbs
+  (`approve_handover` / `reject_handover` / `reject_handover_with_feedback`). Each is
+  a pure `(payload, ports) -> {response, WritePlan}` function: it reads state through
+  injected ports and returns the mutation as a `WritePlan` — it performs no I/O.
+- **`LifecyclePorts`** — the injection contract: the `PlanningSessionStore` /
+  `SpecStore` / `ConfigStore` read ports, the `Validator` (crucible), the pure
+  operations projector, and the optional `persist_write_plan` / `clock` /
+  `id_generator`. The host implements the stores over its own database.
+- **`WritePlan` data contract** (`lifecycle.write_plan_types`) — an ordered list of
+  serializable item kinds (`specMutation`, `sessionUpdate`, `actionAppend`,
+  score/transition datapoints, …). Any executor — the product's SQLite one or an
+  external Postgres one — consumes it as plain data.
+- **`PlanningSessionRecord`** — a pure, DB-free frozen record for the session state
+  the verbs read/return (replaces the ORM row on the verb boundary).
+- **In-memory operations projector** — computes post-mutation state for the
+  validator/gate without touching a database.
+- **Phase-gate evaluator + guidance composer + prechecks** — the deterministic gate
+  and the agent-facing guidance, driven entirely by `crucible.validate`.
+
+### Dependencies
+
+`crucible-forge`, `pydantic`, `python-ulid`, `pyyaml` only. This distribution shares
+the `specsmither` PEP 420 namespace with the `specsmither` product distribution; both
+build and publish independently from the same repository.

specsmither_lifecycle-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: specsmither-lifecycle
+Version: 0.1.0
+Summary: The PURE planning-lifecycle core of SpecSmither — the crucible-gated verb surface (start/action/complete/inspect + handovers), the in-memory operations projector, the WritePlan data contract, and the domain records. No SQLAlchemy, no Textual, no MCP.
+Project-URL: Homepage, https://github.com/blacksmithers/specsmither
+Project-URL: Repository, https://github.com/blacksmithers/specsmither
+Project-URL: Issues, https://github.com/blacksmithers/specsmither/issues
+Author-email: Gabriel Augusto Gonçalves <gab.augustog@gmail.com>
+License: Apache-2.0
+Keywords: crucible,lifecycle,planning,spec,specforge,specsmither
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: crucible-forge>=0.2.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-ulid>=2.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# specsmither-lifecycle
+
+The **pure** planning-lifecycle core of [SpecSmither](https://github.com/blacksmithers/specsmither).
+
+This distribution contributes the `specsmither.lifecycle`, `specsmither.domain`, and
+`specsmither.ids` modules to the shared `specsmither` PEP 420 namespace. It is the
+crucible-gated verb surface — `start` / `action` / `complete` / `inspect` plus the
+handover verbs — together with the in-memory operations projector, the `WritePlan`
+data contract, and the domain records/enums.
+
+It is deliberately **dependency-light**: `crucible-forge`, `pydantic`, `python-ulid`,
+and `pyyaml` only. It pulls in **no** SQLAlchemy, Textual, or MCP — those live in the
+`specsmither` product distribution, which depends on this package and wires it to a
+concrete SQLite store, TUI, and MCP server.
+
+The verb surface satisfies a pure `(payload, ports) -> {response, WritePlan}` contract:
+a host embeds it by providing the `LifecyclePorts` seam (stores, validator, operations
+projector, clock, id generator) and consuming the returned `WritePlan`.

specsmither_lifecycle-0.1.0/README.md

@@ -0,0 +1,18 @@
+# specsmither-lifecycle
+
+The **pure** planning-lifecycle core of [SpecSmither](https://github.com/blacksmithers/specsmither).
+
+This distribution contributes the `specsmither.lifecycle`, `specsmither.domain`, and
+`specsmither.ids` modules to the shared `specsmither` PEP 420 namespace. It is the
+crucible-gated verb surface — `start` / `action` / `complete` / `inspect` plus the
+handover verbs — together with the in-memory operations projector, the `WritePlan`
+data contract, and the domain records/enums.
+
+It is deliberately **dependency-light**: `crucible-forge`, `pydantic`, `python-ulid`,
+and `pyyaml` only. It pulls in **no** SQLAlchemy, Textual, or MCP — those live in the
+`specsmither` product distribution, which depends on this package and wires it to a
+concrete SQLite store, TUI, and MCP server.
+
+The verb surface satisfies a pure `(payload, ports) -> {response, WritePlan}` contract:
+a host embeds it by providing the `LifecyclePorts` seam (stores, validator, operations
+projector, clock, id generator) and consuming the returned `WritePlan`.

specsmither_lifecycle-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "specsmither-lifecycle"
+version = "0.1.0"
+description = "The PURE planning-lifecycle core of SpecSmither — the crucible-gated verb surface (start/action/complete/inspect + handovers), the in-memory operations projector, the WritePlan data contract, and the domain records. No SQLAlchemy, no Textual, no MCP."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Gabriel Augusto Gonçalves", email = "gab.augustog@gmail.com" }]
+keywords = ["spec", "specforge", "specsmither", "planning", "lifecycle", "crucible"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+# The PURE core deps ONLY — the whole point of the split. NO sqlalchemy/textual/mcp.
+dependencies = [
+    "crucible-forge>=0.2.0",
+    "pydantic>=2.6",
+    "python-ulid>=2.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/blacksmithers/specsmither"
+Repository = "https://github.com/blacksmithers/specsmither"
+Issues = "https://github.com/blacksmithers/specsmither/issues"
+
+# PEP 420 namespace package: this dist contributes ``specsmither.lifecycle`` /
+# ``specsmither.domain`` / ``specsmither.ids`` to the shared ``specsmither`` namespace
+# (there is intentionally NO src/specsmither/__init__.py). The product dist
+# ``specsmither`` contributes the rest of the namespace.
+[tool.hatch.build.targets.wheel]
+packages = ["src/specsmither"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/specsmither", "README.md", "CHANGELOG.md"]

specsmither_lifecycle-0.1.0/src/specsmither/domain/__init__.py

@@ -0,0 +1,6 @@
+"""Domain layer: enums, status transitions, and runtime DB-row records.
+
+Pure (no SQLAlchemy, no I/O). Defines the type vocabulary the whole engine
+shares. ``records.py`` rebuilds crucible's ``Specification`` shape from DB rows
+(``SpecFull``) so the planning gate can score a persisted spec.
+"""

specsmither_lifecycle-0.1.0/src/specsmither/domain/enums.py

@@ -0,0 +1,266 @@
+"""Runtime / lifecycle / status enum vocabulary for SpecSmither.
+
+These are the enums that crucible does NOT provide. The OpenSpec *authoring*
+vocabulary (TicketType, Complexity, EpicCategory, TestType, …) is the single
+source of truth in ``crucible.models.enums`` and is reused from there — it is
+deliberately NOT redefined in this module.
+
+Ground truth (ported verbatim so values round-trip with the TS/JSON wire):
+- ``session-types/src/runtime/enums.ts`` (lifecycle / planning / cross-val vocab)
+- ``api-types/src/runtime/status.ts`` (the 4-value ticket status surface)
+- ``api-types/src/runtime/ticket-record.ts`` (ticket file-change ``kind``)
+
+All members are :class:`enum.StrEnum`, so a member compares equal to and is
+usable anywhere its verbatim string value is expected.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+__all__ = [
+    "ActorType",
+    "ActualAction",
+    "DatapointTrigger",
+    "EpicStatus",
+    "ExpectedAction",
+    "FieldState",
+    "FileChangeKind",
+    "FileChangeStatus",
+    "FindingCategory",
+    "GateResult",
+    "GuidanceVariant",
+    "JustificationApproved",
+    "Outcome",
+    "PlanningPhase",
+    "PlanningSessionStatus",
+    "SpecStatus",
+    "TicketStatus",
+    "TransitionTrigger",
+    "WorkSessionStatus",
+]
+
+
+class TicketStatus(StrEnum):
+    """Canonical 4-value ticket status (api-types ``TICKET_STATUSES``).
+
+    "Blocked" is not a status — it is signalled via ``block_reason`` on a
+    ``pending`` ticket.
+    """
+
+    PENDING = "pending"
+    READY = "ready"
+    ACTIVE = "active"
+    DONE = "done"
+
+
+class SpecStatus(StrEnum):
+    """Spec lifecycle (session-types ``SPEC_STATUSES``) — all 8 values verbatim.
+
+    SpecSmither has NO review lifecycle, so ``ready_for_review`` / ``in_review``
+    / ``reviewed`` are UNREACHABLE here. They are kept because the M0 CRUD freeze
+    guards (#18) reference them: ``reviewed`` is treated as read-only and
+    ``in_review`` blocks create. Do not drop them.
+    """
+
+    DRAFT = "draft"
+    PLANNING = "planning"
+    READY = "ready"
+    IN_PROGRESS = "in_progress"
+    # Unreachable in SpecSmither (no review lifecycle) — retained for the
+    # CRUD-freeze guards (#18): `reviewed` = read-only, `in_review` = blocks create.
+    READY_FOR_REVIEW = "ready_for_review"
+    IN_REVIEW = "in_review"
+    REVIEWED = "reviewed"
+    DONE = "done"
+
+
+class PlanningSessionStatus(StrEnum):
+    """Planning-session status (session-types ``PLANNING_SESSION_STATUSES``)."""
+
+    ACTIVE = "active"
+    AWAITING_HUMAN_REVIEW = "awaiting_human_review"
+    CLOSED = "closed"
+
+
+class WorkSessionStatus(StrEnum):
+    """Work-session status (session-types ``WORK_SESSION_STATUSES``)."""
+
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    CLOSED = "closed"
+
+
+class PlanningPhase(StrEnum):
+    """Planning phase machine (session-types ``PLANNING_PHASES``)."""
+
+    PLANNING_SPEC = "planning_spec"
+    EPIC_DECOMPOSITION = "epic_decomposition"
+    EPIC_EXPANSION = "epic_expansion"
+    TICKET_DECOMPOSITION = "ticket_decomposition"
+    TICKET_EXPANSION = "ticket_expansion"
+    CROSS_VALIDATION = "cross_validation"
+    PLANNED = "planned"
+
+
+class TransitionTrigger(StrEnum):
+    """Phase-transition trigger (session-types ``TRANSITION_TRIGGERS``)."""
+
+    AUTO_INITIAL = "auto_initial"
+    AI_AGENT = "ai_agent"
+    HUMAN_APPROVE = "human_approve"
+    HUMAN_COMPLETE = "human_complete"
+    HUMAN_REJECT_WITH_FEEDBACK = "human_reject_with_feedback"
+    HUMAN_REJECT_NO_FEEDBACK = "human_reject_no_feedback"
+
+
+class Outcome(StrEnum):
+    """Audited action outcome (session-types ``OUTCOMES``)."""
+
+    SUCCESS = "success"
+    DENIED = "denied"
+
+
+class DatapointTrigger(StrEnum):
+    """Score-datapoint trigger (session-types ``DATAPOINT_TRIGGERS``)."""
+
+    CREATED = "created"
+    METADATA_UPDATED = "metadata_updated"
+    EPIC_FIELD_UPDATED = "epic_field_updated"
+    TICKET_FIELD_UPDATED = "ticket_field_updated"
+    BLUEPRINT_FIELD_UPDATED = "blueprint_field_updated"
+    DEPENDENCY_ADDED = "dependency_added"
+    DEPENDENCY_REMOVED = "dependency_removed"
+    BLUEPRINT_LINKED = "blueprint_linked"
+    BLUEPRINT_UNLINKED = "blueprint_unlinked"
+    CROSS_VAL_RECOMPUTE = "cross_val_recompute"
+
+
+class GuidanceVariant(StrEnum):
+    """Guidance-message variant (session-types ``GUIDANCE_VARIANTS``).
+
+    Includes the six M6.6 additions consumed exclusively by
+    ``get_planning_status``.
+    """
+
+    DENIED = "denied"
+    GATE_FAILED = "gate_failed"
+    GATE_PASSED = "gate_passed"
+    HUMAN_HANDOVER = "human_handover"
+    HUMAN_FEEDBACK = "human_feedback"
+    PHASE_ADVANCE = "phase_advance"
+    PHASE_ROLLBACK = "phase_rollback"
+    PHASE_COMPLETE = "phase_complete"
+    # M6.6 additions.
+    PHASE_STATUS_REPORT = "phase_status_report"
+    AWAITING_HUMAN_REVIEW_HANDOVER = "awaiting_human_review_handover"
+    HUMAN_FEEDBACK_RECEIVED = "human_feedback_received"
+    HUMAN_REJECTED_NO_FEEDBACK = "human_rejected_no_feedback"
+    PHASE_ADVANCED_AFTER_APPROVE = "phase_advanced_after_approve"
+    SESSION_CLOSED = "session_closed"
+
+
+class FindingCategory(StrEnum):
+    """Cross-validation finding category (session-types ``FINDING_CATEGORIES``)."""
+
+    RUBRIC = "rubric"
+    COUNT = "count"
+    CROSS_CUT = "cross-cut"
+    CASCADE = "cascade"
+    CROSS_VALIDATION = "cross-validation"
+    SCHEMA = "schema"
+
+
+class GateResult(StrEnum):
+    """Gate result (session-types ``GATE_RESULTS``)."""
+
+    PASS = "pass"
+    FAIL = "fail"
+
+
+class FieldState(StrEnum):
+    """Field-presence state (session-types ``FIELD_STATES``)."""
+
+    EMPTY = "empty"
+    PARTIAL = "partial"
+    FILLED = "filled"
+    NA = "na"
+
+
+class ExpectedAction(StrEnum):
+    """Planned file action (session-types ``EXPECTED_ACTIONS``)."""
+
+    CREATE = "create"
+    MODIFY = "modify"
+    DELETE = "delete"
+    REFERENCE = "reference"
+
+
+class ActualAction(StrEnum):
+    """Observed file action (session-types ``ACTUAL_ACTIONS``)."""
+
+    CREATED = "created"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    REFERENCED = "referenced"
+    ABSENT = "absent"
+
+
+class FileChangeStatus(StrEnum):
+    """Expected-vs-actual reconciliation (session-types ``FILE_CHANGE_STATUSES``)."""
+
+    MATCHED = "matched"
+    MISSING = "missing"
+    MISMATCHED = "mismatched"
+    EXTRA = "extra"
+
+
+class JustificationApproved(StrEnum):
+    """Justification approval state (session-types ``JUSTIFICATION_APPROVED_VALUES``)."""
+
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+class FileChangeKind(StrEnum):
+    """Ticket PLAN-side file-change kind (api-types ``TicketFileChangeKind``).
+
+    Drives ``ticket_file_changes.kind`` (schema §3). Distinct from the work-side
+    :class:`ExpectedAction` / :class:`ActualAction` vocabulary — these are the
+    ``toBeX`` camelCase literals from ``api-types/runtime/ticket-record.ts``.
+    """
+
+    TO_BE_CREATED = "toBeCreated"
+    TO_BE_MODIFIED = "toBeModified"
+    TO_BE_DELETED = "toBeDeleted"
+    TO_BE_REFERENCED = "toBeReferenced"
+
+
+class EpicStatus(StrEnum):
+    """Epic lifecycle status.
+
+    A DISTINCT enum exists in the TS (``types/src/schema/epic.ts`` →
+    ``'todo' | 'in_progress' | 'completed'``), and the planning verbs that
+    SpecSmither ports create epics with ``status: 'todo'`` and explicitly comment
+    that this is "a constrained EpicStatus enum (todo|in_progress|completed)"
+    (``lifecycle/.../action-planning-session.ts``). So epics do NOT share the
+    ticket vocabulary — these three values are ported verbatim.
+    """
+
+    TODO = "todo"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+
+
+class ActorType(StrEnum):
+    """Audit actor identity (§6 actor model).
+
+    Confirmed against the TS: ``actor: 'agent' | 'human'`` throughout the
+    planning verbs / ``action-builder.ts``. There is no named ``ACTOR_TYPES``
+    array — the union is inlined — so the two members are defined here. MCP tool
+    calls resolve to ``agent``; explicit CLI handover/approve commands to ``human``.
+    """
+
+    AGENT = "agent"
+    HUMAN = "human"