spec-kitty-cli 2.1.1__tar.gz → 2.1.3__tar.gz

{spec_kitty_cli-2.1.1 → spec_kitty_cli-2.1.3}/CHANGELOG.md

@@ -11,6 +11,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _No unreleased changes._
 
+## [2.1.3] - 2026-03-27
+
+### 🐛 Fixed
+
+**Preserve explicit WP args in workflow prompts**: Slash-command arguments passed to `/spec-kitty.implement` and `/spec-kitty.review` are now forwarded into the resolver-first flow instead of being silently dropped. Agents receiving explicit WP selectors (e.g., `WP03`, `--base WP01`) will correctly pass them to `spec-kitty agent context resolve` via `--wp-id` and `--base` flags.
+
+- `implement.md` and `review.md` mission templates now include an `{ARGS}` placeholder with conditional forwarding instructions
+- Public slash-command docs updated: `/spec-kitty.implement` documents `[--base WP_ID]` support; `/spec-kitty.review` is now WP-only (removed stale "or prompt path" syntax)
+- Regression tests added across Markdown and TOML agent formats to ensure argument placeholders survive rendering
+
+## [2.1.2] - 2026-03-23
+
+### 🔧 Improved
+
+**Skills audit and expansion**: All 6 distributed skills audited, command-verified, and expanded with full architecture documentation. Skills now document internal systems (glossary pipeline, constitution extraction, runtime DAG, git workflow boundary) so agents can operate effectively.
+
+- setup-doctor: Fixed wrong CLI commands (`verify` → `verify-setup`, `status` → `agent tasks status`), added `--remove-orphaned` safety warning
+- runtime-review: Added discovery step, `--feature` flags, empty-lane guidance
+- glossary-context: Added 5-layer middleware pipeline, extraction methods, checkpoint/resume, step config
+- constitution-doctrine: Added extraction rules, governance.yaml schema, interview profiles, answers.yaml schema
+- runtime-next: Added decision algorithm, WP iteration logic, 6 guard primitives, agent loop pattern
+- orchestrator-api: Added JSON output examples, error code catalog, idempotency behavior, preflight details
+
+### ✨ Added
+
+**2 new skills**: `spec-kitty-mission-system` (explains missions, 4 types, template resolution, guards) and `spec-kitty-git-workflow` (documents Python vs agent git operation boundary).
+
+**Reusable skill update utility**: `src/specify_cli/upgrade/skill_update.py` for finding and patching skill files across all 13 agent skill roots.
+
+**10 upgrade migrations** for consumer projects: 6 skill fixes, 1 release skill removal, 2 new skill installations, 1 glossary skill expansion.
+
+**Documentation parity sprint (Feature 056)**: DocFX build now includes all 4 Divio categories (was only building 1x/ and 2x/). 5 new user guides distilled from skills, 4 existing docs expanded, 22 fact-check corrections across 20 files.
+
+### 🐛 Fixed
+
+**DocFX build gap**: 56 docs files (tutorials, how-to, reference, explanation) were in the repo but excluded from the docs.spec-kitty.ai build. Now included via updated `docfx.json`.
+
+**8-lane state machine documentation**: All docs updated from outdated 4-lane model (planned/doing/for_review/done) to correct 8-lane model (planned/claimed/in_progress/for_review/approved/done/blocked/canceled) with 24 allowed transitions.
+
+**CLI reference completeness**: Added 12 missing commands to cli-commands.md, 7 missing subcommands to agent-subcommands.md. Fixed `spec-kitty sync` (documented as flat command, actually a group with 6 subcommands).
+
+### 🧹 Maintenance
+
+- Removed `release` skill from distribution (spec-kitty development only, not for consumers)
+- Removed obsolete `docs/how-to/upgrade-to-0-11-0.md`
+- Fixed all cross-reference links in new docs (0 new DocFX build warnings)
+
 ## [2.1.1] - 2026-03-21
 
 ### 🐛 Fixed

{spec_kitty_cli-2.1.1 → spec_kitty_cli-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 2.1.1
+Version: 2.1.3
 Summary: Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation.
 Project-URL: Repository, https://github.com/Priivacy-ai/spec-kitty
 Project-URL: Issues, https://github.com/Priivacy-ai/spec-kitty/issues

spec_kitty_cli-2.1.3/kitty-specs/056-documentation-parity-sprint/tasks/README.md

@@ -0,0 +1,75 @@
+# Tasks Directory
+
+This directory contains work package (WP) prompt files with lane status in frontmatter.
+
+## Directory Structure (v0.9.0+)
+
+```
+tasks/
+├── WP01-setup-infrastructure.md
+├── WP02-user-authentication.md
+├── WP03-api-endpoints.md
+└── README.md
+```
+
+All WP files are stored flat in `tasks/`. The lane (planned, doing, for_review, approved, done) is stored in the YAML frontmatter `lane:` field.
+
+## Work Package File Format
+
+Each WP file **MUST** use YAML frontmatter:
+
+```yaml
+---
+work_package_id: "WP01"
+title: "Work Package Title"
+lane: "planned"
+dependencies: []
+planning_base_branch: "2.x"
+merge_target_branch: "2.x"
+branch_strategy: "Planning artifacts were generated on 2.x; completed changes must merge back into 2.x."
+subtasks:
+  - "T001"
+  - "T002"
+phase: "Phase 1 - Setup"
+assignee: ""
+agent: ""
+shell_pid: ""
+review_status: ""
+reviewed_by: ""
+review_feedback: ""
+history:
+  - timestamp: "2025-01-01T00:00:00Z"
+    lane: "planned"
+    agent: "system"
+    action: "Prompt generated via /spec-kitty.tasks"
+---
+
+# Work Package Prompt: WP01 – Work Package Title
+
+[Content follows...]
+```
+
+## Valid Lane Values
+
+- `planned` - Ready for implementation
+- `doing` - Currently being worked on
+- `for_review` - Awaiting review
+- `approved` - Review passed; awaiting merge-complete recording
+- `done` - Completed
+
+## Moving Between Lanes
+
+Use the CLI (updates frontmatter only, no file movement):
+```bash
+spec-kitty agent tasks move-task <WPID> --to <lane>
+```
+
+Example:
+```bash
+spec-kitty agent tasks move-task WP01 --to doing
+```
+
+## File Naming
+
+- Format: `WP01-kebab-case-slug.md`
+- Examples: `WP01-setup-infrastructure.md`, `WP02-user-auth.md`

{spec_kitty_cli-2.1.1 → spec_kitty_cli-2.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "2.1.1"
+version = "2.1.3"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }

spec_kitty_cli-2.1.3/src/doctrine/skills/spec-kitty-constitution-doctrine/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: spec-kitty-constitution-doctrine
+description: >-
+  Run constitution interview, generation, context, and sync workflows for
+  project governance in Spec Kitty 2.x.
+  Triggers: "interview for constitution", "generate constitution",
+  "sync constitution", "use doctrine", "set up governance",
+  "constitution status", "extract governance config".
+  Does NOT handle: generic spec writing not tied to governance, direct runtime
+  loop advancement, setup/repair diagnostics, or editorial glossary maintenance.
+---
+
+# spec-kitty-constitution-doctrine
+
+Manage the constitution lifecycle: interview, generate, context-load, sync,
+and status. The constitution is the single authoritative governance document
+for a Spec Kitty project. All structured config (governance.yaml,
+directives.yaml, references.yaml) is derived from it.
+
+---
+
+## How the Constitution System Works
+
+The constitution is a **governance-as-code** framework. A human-written markdown
+document captures project policy, and the runtime extracts structured YAML from
+it to constrain what agents see and do during workflow actions.
+
+### The 3-Layer Model
+
+1. **Constitution** (`constitution.md`) — Human-editable markdown. The single
+   authoritative source. Created via interview or written by hand.
+
+2. **Extracted config** — Machine-readable YAML derived deterministically by
+   sync. Never edit these directly — they are overwritten on every sync.
+   - `governance.yaml` — Testing, quality, performance, branching, doctrine selections
+   - `directives.yaml` — Numbered project rules with severity and scope
+   - `metadata.yaml` — Hash, timestamp, extraction mode
+
+3. **Doctrine references** (`library/*.md`) — Detailed guidance documents for
+   selected paradigms, directives, and tools. Copied from `src/doctrine/` during
+   generation.
+
+### Data Flow
+
+```
+Interview Answers (answers.yaml)
+        ↓
+  [generate command]  ← doctrine templates, mission config
+        ↓
+Constitution (constitution.md)  ← authoritative source
+        ↓
+  [auto-sync triggered]
+        ↓
+    ├→ governance.yaml      ← extracted structured config
+    ├→ directives.yaml      ← extracted numbered rules
+    ├→ metadata.yaml        ← hash, timestamp, extraction mode
+    └→ library/*.md         ← copied doctrine reference docs
+        ↓
+  [context command]  at each workflow action
+        ↓
+    Text injected into agent prompt
+```
+
+### How Sync Extraction Works
+
+The sync command parses `constitution.md` by classifying section headings
+against a keyword map:
+
+| Heading keyword | Target schema |
+|---|---|
+| `testing`, `test`, `coverage` | `governance.testing` |
+| `quality`, `lint` | `governance.quality` |
+| `commit` | `governance.commits` |
+| `performance` | `governance.performance` |
+| `branch` | `governance.branch_strategy` |
+| `paradigm`, `tool`, `template` | `governance.doctrine` |
+| `directive`, `constraint`, `rule` | `directives.directives` |
+
+For each matched section, the parser extracts structured data from:
+1. **Markdown tables** — rows parsed as key-value dicts
+2. **YAML code blocks** — parsed directly
+3. **Numbered lists** — extracted as directive items
+4. **Keyword patterns** — regex matching for quantitative values:
+   - `90%+ coverage` → `testing.min_coverage: 90`
+   - `TDD required` → `testing.tdd_required: true`
+   - `< 2 seconds` → `performance.cli_timeout_seconds: 2.0`
+   - `mypy --strict` → `testing.type_checking: "mypy --strict"`
+   - `1 approval` → `quality.pr_approvals: 1`
+   - `conventional commits` → `commits.convention: "conventional"`
+   - `pre-commit hooks` → `quality.pre_commit_hooks: true`
+
+Doctrine selections (paradigms, directives, tools, template_set) are merged
+from YAML blocks and tables that contain keys like `selected_paradigms`,
+`available_tools`, or `template_set`.
+
+### governance.yaml Schema
+
+```yaml
+testing:
+  min_coverage: 90              # Minimum test coverage %
+  tdd_required: false           # TDD mandatory
+  framework: pytest             # Test framework
+  type_checking: "mypy --strict" # Type checker
+quality:
+  linting: ruff                 # Linter
+  pr_approvals: 1               # Required approvals before merge
+  pre_commit_hooks: false       # Pre-commit hooks required
+commits:
+  convention: conventional      # Commit convention (or null)
+performance:
+  cli_timeout_seconds: 2.0      # Max CLI command duration
+  dashboard_max_wps: 100        # Max work packages dashboard displays
+branch_strategy:
+  main_branch: main             # Primary branch
+  dev_branch: null              # Development branch (optional)
+  rules: []                     # Branch naming/protection rules
+doctrine:
+  selected_paradigms: []        # Active paradigm IDs
+  selected_directives: []       # Active directive IDs
+  available_tools: []           # Active tool IDs
+  template_set: null            # Mission template set
+enforcement: {}                 # Enforcement policy by domain
+```
+
+### directives.yaml Schema
+
+```yaml
+directives:
+  - id: DIR-001                 # Auto-generated or custom ID
+    title: "Short title"        # First 50 chars
+    description: "Full text"    # Full description
+    severity: warn              # error (blocks), warn (displayed), info (logged)
+    applies_to: [implement, review]  # Actions where directive fires
+```
+
+### Hash-Based Staleness Detection
+
+Sync uses SHA-256 to detect changes. The hash of `constitution.md` content
+(whitespace-normalized) is stored in `metadata.yaml`. On sync:
+- If hashes match and `--force` not set → skip (idempotent)
+- If hashes differ → re-extract
+- If no `metadata.yaml` exists → always stale
+
+### How Context Gets Injected Into Workflow Actions
+
+When you run `/spec-kitty.specify`, `/spec-kitty.plan`, `/spec-kitty.implement`,
+or `/spec-kitty.review`, the runtime automatically calls
+`spec-kitty constitution context --action <action>`. The returned text is
+injected into the agent prompt.
+
+**Three context modes:**
+
+| Mode | When | Content |
+|---|---|---|
+| `bootstrap` | First load for an action | Full policy summary (up to 8 bullets) + reference doc list (up to 10) |
+| `compact` | Subsequent loads | Resolved paradigms, directives, tools, template_set only |
+| `missing` | No constitution exists | Instructions to create one |
+
+First-load state is tracked in `.kittify/constitution/context-state.json`.
+Each action (specify, plan, implement, review) has an independent first-load
+timestamp.
+
+### Available Doctrine Assets
+
+**Paradigms** (from `src/doctrine/paradigms/`):
+- `test-first` — Prefer acceptance-first and red-green-refactor loops
+
+**Directives** (from `src/doctrine/directives/`):
+- `TEST_FIRST` — Require test-first behavior across acceptance and implementation.
+  References tactics: acceptance-test-first, tdd-red-green-refactor, zombies-tdd.
+
+**Template sets** (from `src/doctrine/missions/`):
+- `software-dev-default` — Core development workflow
+- `plan-default` — Goal-oriented planning
+- `documentation-default` — Documentation creation (Divio)
+- `research-default` — Research and evidence gathering
+
+**Styleguides** (from `src/doctrine/styleguides/`):
+- `python-implementation` — Python coding principles
+- `kitty-glossary-writing` — Glossary authoring style
+
+**Default tool registry:** spec-kitty, git, python, pytest, ruff, mypy, poetry
+
+### Interview Profiles
+
+**Minimal** (8 questions — fast bootstrap):
+
+| Question | Governance use |
+|---|---|
+| `project_intent` | Policy summary, preamble |
+| `languages_frameworks` | Styleguide selection (e.g., Python) |
+| `testing_requirements` | `testing.framework`, `testing.min_coverage` |
+| `quality_gates` | Quality Gates section |
+| `review_policy` | `quality.pr_approvals`, Branch Strategy |
+| `performance_targets` | `performance.cli_timeout_seconds` |
+| `deployment_constraints` | `branch_strategy.rules` |
+
+**Comprehensive** (11 questions — adds 4 more):
+
+| Question | Governance use |
+|---|---|
+| `documentation_policy` | Added to Project Directives |
+| `risk_boundaries` | Added to Project Directives |
+| `amendment_process` | Amendment Process section |
+| `exception_policy` | Exception Policy section |
+
+### answers.yaml Schema
+
+```yaml
+schema_version: "1.0.0"
+mission: "software-dev"
+profile: "minimal"
+answers:
+  project_intent: "..."
+  languages_frameworks: "..."
+  testing_requirements: "..."
+  quality_gates: "..."
+  review_policy: "..."
+  performance_targets: "..."
+  deployment_constraints: "..."
+  # comprehensive only:
+  documentation_policy: "..."
+  risk_boundaries: "..."
+  amendment_process: "..."
+  exception_policy: "..."
+selected_paradigms:
+  - "test-first"
+selected_directives:
+  - "TEST_FIRST"
+available_tools:
+  - "spec-kitty"
+  - "git"
+  - "python"
+  - "pytest"
+  - "ruff"
+  - "mypy"
+  - "poetry"
+```
+
+---
+
+## Step 1: Check Current State
+
+```bash
+spec-kitty constitution status --json
+```
+
+Reports `synced` or `stale`, current and stored hashes, library doc count,
+and per-file sizes. If `stale`, run sync before relying on governance config.
+
+---
+
+## Step 2: Run the Constitution Interview
+
+**Fast path (deterministic defaults):**
+
+```bash
+spec-kitty constitution interview --mission software-dev --profile minimal --defaults --json
+```
+
+**Full interactive interview:**
+
+```bash
+spec-kitty constitution interview --mission software-dev --profile comprehensive
+```
+
+Key flags: `--profile minimal|comprehensive`, `--defaults`, `--json`,
+`--selected-paradigms`, `--selected-directives`, `--available-tools`.
+See `references/constitution-command-map.md` for all flags.
+
+**Output:** `.kittify/constitution/interview/answers.yaml`
+
+---
+
+## Step 3: Generate the Constitution
+
+```bash
+spec-kitty constitution generate --from-interview --json
+```
+
+Key flags: `--mission`, `--template-set`, `--force`, `--from-interview`, `--json`.
+
+Generation triggers an automatic sync, so governance.yaml and directives.yaml
+are written immediately.
+
+**Output:** `.kittify/constitution/constitution.md` plus extracted YAML files
+and `library/*.md` reference documents.
+
+---
+
+## Step 4: Load Context for Workflow Actions
+
+Load governance context before each workflow action:
+
+```bash
+spec-kitty constitution context --action specify --json
+spec-kitty constitution context --action plan --json
+spec-kitty constitution context --action implement --json
+spec-kitty constitution context --action review --json
+```
+
+The runtime calls context automatically during slash commands. Manual
+invocation is useful for debugging what governance policy an action receives.
+
+---
+
+## Step 5: Sync After Manual Edits
+
+```bash
+spec-kitty constitution sync --json
+spec-kitty constitution sync --force --json   # re-extract even if unchanged
+```
+
+Sync is idempotent — skips extraction when the constitution hash is unchanged
+unless `--force` is passed.
+
+---
+
+## When Doctrine Constrains Runtime
+
+Doctrine constrains runtime behavior when the constitution has been generated
+and the agent is executing a workflow action (specify, plan, implement, review).
+The specific constraints come from the project's own constitution — load them
+with `spec-kitty constitution context --action <action> --json` rather than
+assuming fixed policy values.
+
+Doctrine does NOT constrain when:
+
+- The user works outside a mission.
+- No constitution has been generated.
+- The action is not a workflow action (specify, plan, implement, review).
+
+---
+
+## Governance Anti-Patterns
+
+1. **Editing derived files** — `governance.yaml`, `directives.yaml`, and
+   `library/*.md` are overwritten by sync/generate. Edit `constitution.md`.
+2. **Skipping the interview** — produces generic defaults; the constitution
+   is most valuable with project-specific decisions.
+3. **Stale constitution** — an outdated constitution silently injects wrong
+   policy. Run `status` to check, `sync` to fix.
+4. **Legacy path assumptions** — canonical path is
+   `.kittify/constitution/constitution.md`, not `.kittify/memory/`.
+
+See `references/doctrine-artifact-structure.md` for the full anti-pattern table.
+
+---
+
+## References
+
+- `references/constitution-command-map.md` -- Full CLI command reference with all flags and output fields
+- `references/doctrine-artifact-structure.md` -- File layout, authority classes, and data flow