zenkit 0.5.0

package/dist/schemas/schemas/benchmark.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/benchmark.schema.json",
+  "title": "ZenKit Benchmark Result",
+  "description": "Structured output from a ZenKit benchmark run with acceptance criteria verification.",
+  "type": "object",
+  "required": ["benchmark_id", "version", "mode", "task_name", "started_at", "completed_at", "status", "validation_summary", "acceptance_criteria_results"],
+  "properties": {
+    "benchmark_id": { "type": "string" },
+    "version": { "type": "string" },
+    "mode": {
+      "type": "string",
+      "enum": ["zenkit", "baseline"],
+      "description": "Whether this run used ZenKit workflow structure or an unstructured baseline."
+    },
+    "task_name": { "type": "string" },
+    "feature_spec": { "type": "string" },
+    "started_at": { "type": "string", "format": "date-time" },
+    "completed_at": { "type": "string", "format": "date-time" },
+    "duration_ms": { "type": "integer", "minimum": 0 },
+    "status": {
+      "type": "string",
+      "enum": ["pass", "fail", "partial"]
+    },
+    "expected_files": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "files_found": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "files_missing": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "acceptance_criteria_results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "description", "status", "evidence", "verification_type"],
+        "properties": {
+          "id": { "type": "string" },
+          "description": { "type": "string" },
+          "status": { "type": "string", "enum": ["pass", "fail"] },
+          "evidence": { "type": "string", "description": "What was actually checked and found." },
+          "verification_type": { "type": "string" }
+        }
+      }
+    },
+    "stages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "status", "checks_run", "checks_passed"],
+        "properties": {
+          "name": { "type": "string" },
+          "status": { "type": "string", "enum": ["pass", "fail", "skipped"] },
+          "duration_ms": { "type": "integer" },
+          "checks_run": { "type": "integer", "minimum": 0 },
+          "checks_passed": { "type": "integer", "minimum": 0 },
+          "details": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "validation_summary": {
+      "type": "object",
+      "required": ["total_criteria", "criteria_passed", "criteria_failed"],
+      "properties": {
+        "total_criteria": { "type": "integer" },
+        "criteria_passed": { "type": "integer" },
+        "criteria_failed": { "type": "integer" },
+        "schemas_valid": { "type": "boolean" },
+        "examples_valid": { "type": "boolean" }
+      }
+    },
+    "telemetry": {
+      "type": "object",
+      "required": ["estimated"],
+      "properties": {
+        "estimated": {
+          "type": "object",
+          "required": ["tokens", "cost_usd", "basis"],
+          "properties": {
+            "tokens": { "type": "integer" },
+            "cost_usd": { "type": "number" },
+            "basis": { "type": "string", "description": "How the estimate was calculated." }
+          }
+        },
+        "actual": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["tokens", "cost_usd"],
+              "properties": {
+                "tokens": { "type": "integer" },
+                "cost_usd": { "type": "number" }
+              }
+            }
+          ],
+          "description": "Null when no real telemetry is available. Never fabricated."
+        }
+      }
+    },
+    "uncertainty": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "What this benchmark does NOT prove."
+    },
+    "limitations": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Inherited from the feature spec — scope boundaries of the verification."
+    }
+  },
+  "additionalProperties": false
+}

package/dist/schemas/schemas/checkpoint.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/checkpoint.schema.json",
+  "title": "ZenKit Checkpoint",
+  "description": "A snapshot of workflow state at a specific point in execution.",
+  "type": "object",
+  "required": ["checkpoint_id", "task_id", "status", "timestamp"],
+  "properties": {
+    "checkpoint_id": {
+      "type": "string",
+      "pattern": "^chk-[a-z0-9-]+$"
+    },
+    "task_id": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["snapshot", "gate", "rollback_point"]
+    },
+    "stage": {
+      "type": "string",
+      "enum": ["plan", "build", "audit", "ship"]
+    },
+    "state": {
+      "type": "object",
+      "properties": {
+        "files_changed": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tests_passing": { "type": "boolean" },
+        "lint_passing": { "type": "boolean" },
+        "git_ref": { "type": "string" },
+        "notes": { "type": "string" }
+      }
+    },
+    "gate_conditions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "condition": { "type": "string" },
+          "met": { "type": "boolean" }
+        },
+        "required": ["condition", "met"]
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "agent": { "type": "string" },
+        "command": { "type": "string" },
+        "iteration": { "type": "integer" },
+        "tokens_used": { "type": "integer" },
+        "cost_estimate_usd": { "type": "number" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/dist/schemas/schemas/feature-spec.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/feature-spec.schema.json",
+  "title": "ZenKit Feature Spec",
+  "description": "Machine-readable feature specification for ZenKit benchmarks.",
+  "type": "object",
+  "required": ["feature_id", "name", "description", "mode", "acceptance_criteria", "constraints", "expected_files", "limitations"],
+  "properties": {
+    "feature_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["zenkit", "baseline"]
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "description", "verification"],
+        "properties": {
+          "id": { "type": "string" },
+          "description": { "type": "string" },
+          "verification": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["file_exists", "file_contains", "schema_count", "examples_valid", "schemas_consistent", "test_passes", "json_path_equals"]
+              },
+              "path": { "type": "string" },
+              "pattern": { "type": "string" },
+              "command": { "type": "string", "description": "Shell command to run for test_passes verification." },
+              "json_path": { "type": "string", "description": "Dot-separated path into JSON for json_path_equals." },
+              "equals": { "description": "Expected value for json_path_equals." },
+              "expected": { "type": "integer" }
+            }
+          }
+        }
+      }
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "expected_files": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "assigned_commands": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "estimated_complexity": {
+      "type": "string",
+      "enum": ["low", "medium", "high"]
+    },
+    "limitations": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "What this spec does NOT verify. Required — specs must be honest about scope."
+    }
+  },
+  "additionalProperties": false
+}

package/dist/schemas/schemas/handoff.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/handoff.schema.json",
+  "title": "ZenKit Handoff Contract",
+  "description": "Structured handoff between agents or workflow stages in ZenKit.",
+  "type": "object",
+  "required": ["context", "assumptions", "decision", "deliverable", "next_agent"],
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "What is the current situation? What has happened so far?"
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Explicit assumptions made during this stage."
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Hard constraints that bound this work."
+    },
+    "decision": {
+      "type": "string",
+      "description": "What was decided and why."
+    },
+    "deliverable": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["code", "document", "schema", "plan", "review", "test", "artifact"]
+        },
+        "description": { "type": "string" },
+        "files_changed": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "validation_status": {
+          "type": "string",
+          "enum": ["passed", "failed", "partial", "untested"]
+        }
+      },
+      "required": ["type", "description"]
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "description": { "type": "string" },
+          "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
+          "mitigation": { "type": "string" }
+        },
+        "required": ["description", "severity"]
+      }
+    },
+    "open_questions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Unresolved questions that the next agent should address."
+    },
+    "next_agent": {
+      "type": "string",
+      "description": "The agent or role that should receive this handoff."
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "timestamp": { "type": "string", "format": "date-time" },
+        "source_agent": { "type": "string" },
+        "command": { "type": "string" },
+        "iteration": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/dist/schemas/schemas/task.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/task.schema.json",
+  "title": "ZenKit Task",
+  "description": "A discrete unit of work within a ZenKit workflow.",
+  "type": "object",
+  "required": ["id", "name", "status", "command"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "description": {
+      "type": "string"
+    },
+    "command": {
+      "type": "string",
+      "enum": ["plan", "build", "audit", "refactor", "spec", "handoff", "checkpoint", "ship"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "in_progress", "blocked", "completed", "failed", "skipped"]
+    },
+    "context": {
+      "type": "string"
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "files_affected": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "assigned_agent": {
+      "type": "string"
+    },
+    "parent_task": {
+      "type": "string"
+    },
+    "dependencies": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "created_at": { "type": "string", "format": "date-time" },
+        "updated_at": { "type": "string", "format": "date-time" },
+        "estimated_tokens": { "type": "integer", "minimum": 0 },
+        "actual_tokens": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/dist/schemas/task.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/task.schema.json",
+  "title": "ZenKit Task",
+  "description": "A discrete unit of work within a ZenKit workflow.",
+  "type": "object",
+  "required": ["id", "name", "status", "command"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "description": {
+      "type": "string"
+    },
+    "command": {
+      "type": "string",
+      "enum": ["plan", "build", "audit", "refactor", "spec", "handoff", "checkpoint", "ship"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "in_progress", "blocked", "completed", "failed", "skipped"]
+    },
+    "context": {
+      "type": "string"
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "files_affected": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "assigned_agent": {
+      "type": "string"
+    },
+    "parent_task": {
+      "type": "string"
+    },
+    "dependencies": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "created_at": { "type": "string", "format": "date-time" },
+        "updated_at": { "type": "string", "format": "date-time" },
+        "estimated_tokens": { "type": "integer", "minimum": 0 },
+        "actual_tokens": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/docs/agent-contract.md

@@ -0,0 +1,36 @@
+# Agent Contracts
+
+Agents in ZenKit are bounded workers, not autonomous assistants. Each has explicit responsibility, defined inputs, and required outputs.
+
+## Definition format
+
+Each agent specifies: name, responsibility (one sentence), input/output schemas, allowed skills, and constraints. See `agents/*.md` for all 9 definitions.
+
+## Bounded responsibility
+
+Each agent owns one stage. It does not redo earlier work or pre-empt later work. Schemas enforce this — an agent cannot produce output shaped for a different stage without violating its contract.
+
+## Default handoff chain
+
+```
+product-manager → system-architect → backend / frontend (parallel)
+  → qa → security → auditor → writer → ship
+```
+
+This is a default, not a requirement. Teams can remove, reorder, or add agents.
+
+## What agents must NOT do
+
+- Assume context not in the input.
+- Skip open questions — silence is a contract violation.
+- Modify upstream artifacts — flag problems and hand off.
+- Claim certainty without evidence.
+- Invoke skills outside their allowed list.
+
+## Adding custom agents
+
+1. Define in `agents/` with name, responsibility, boundaries, handoff targets.
+2. Place in the handoff chain at the appropriate position.
+3. Ensure schema compatibility with upstream output and downstream input.
+
+Custom agents follow the same contracts as built-in agents.

package/docs/architecture.md

@@ -0,0 +1,88 @@
+# ZenKit Architecture
+
+ZenKit is built from six primitive categories that compose into workflows. There is no runtime -- only schemas, commands, and conventions that tools and agents agree to follow.
+
+## The Six Primitives
+
+### Commands
+
+The verbs of the system. Each command (`spec`, `plan`, `build`, `audit`, `refactor`, `handoff`, `checkpoint`, `ship`) takes structured input and produces structured output. Commands are stateless -- they read input, produce output, and exit.
+
+### Schemas
+
+JSON schemas that define the shape of every input and output. Schemas are the source of truth. If an agent produces output that does not validate against its schema, the output is rejected. No exceptions.
+
+### Skills
+
+Reusable capabilities that agents can invoke during command execution. A skill is a scoped unit of work -- "generate SQL migration," "run lint," "estimate complexity." Skills are composable and can be shared across agents.
+
+### Hooks
+
+Lifecycle callbacks that fire before or after a command runs. Hooks handle side effects: logging, notifications, file cleanup, environment validation. They keep commands pure by moving side effects to the edges.
+
+### Checkpoints
+
+Snapshots of workflow state at a given point. A checkpoint captures the current context, completed steps, and pending work. Checkpoints enable resumption -- if a workflow fails at step 4, you restart from checkpoint 3, not from zero.
+
+### Rubrics
+
+Evaluation criteria that the audit system uses to grade deliverables. A rubric defines what "done" looks like for a given command or workflow stage. Rubrics are explicit, versioned, and diffable.
+
+## Workflow Composition
+
+Primitives compose into workflows through chaining. The output of one command becomes the input of the next. The standard lifecycle is:
+
+```
+plan --> build --> audit --> ship
+
+    +---> checkpoint (at any stage)
+    +---> refactor (loops back to build)
+    +---> handoff (transfers between agents)
+```
+
+### The Lifecycle
+
+```
+  +---------+     +---------+     +---------+     +---------+
+  |  PLAN   |---->|  BUILD  |---->|  AUDIT  |---->|  SHIP   |
+  +---------+     +---------+     +---------+     +---------+
+       |               |               |               |
+       v               v               v               v
+  checkpoint      checkpoint      checkpoint      checkpoint
+                       ^               |
+                       |    (fail)     |
+                       +---------------+
+                        refactor loop
+```
+
+**Plan**: Define what will be built, how, and why. Produces a structured plan with scope, dependencies, and risk assessment.
+
+**Build**: Execute the plan. Produce code, configurations, migrations, or whatever the spec requires. Output includes the deliverable plus metadata about decisions made during building.
+
+**Audit**: Validate the build output against the spec and rubrics. The audit checks schema compliance, runs tests if available, and flags gaps. Audit failures feed back into a refactor cycle.
+
+**Ship**: Package and release the validated output. Ship only runs after audit passes. It produces a manifest of what was shipped and where.
+
+## The Handoff Contract
+
+Agents do not share memory. They share documents. When one agent finishes its work, it produces a handoff artifact that contains everything the next agent needs: context, deliverables, assumptions, constraints, and open questions.
+
+The handoff contract ensures that agent A does not need to know how agent B works. It only needs to produce output that matches the handoff schema. This is what makes agents replaceable -- swap the implementation, keep the contract.
+
+```
+Agent A                    Agent B
+  |                          |
+  +--- handoff artifact ---->|
+  |    (schema-validated)    |
+  |                          +---> continues work
+```
+
+Handoff artifacts are versioned and stored alongside the code they describe. They are first-class project artifacts, not ephemeral messages.
+
+## The CLI
+
+The `zenkit` CLI provides the executable interface to the protocol: `validate` checks data against schemas, `benchmark` runs feature specs, `audit` produces structured audit reports, `init` scaffolds ZenKit into a project, and `status` shows project health. The CLI is a thin wrapper — it delegates to the same scripts and schemas that compose the protocol layer.
+
+## What Is Not Here
+
+There is no central orchestrator. There is no agent registry service. There is no shared memory bus. Coordination happens through files, schemas, and explicit contracts. This is intentional — ZenKit works with any AI provider, any CI system, and any language.

package/docs/benchmarking.md

@@ -0,0 +1,51 @@
+# Benchmarking
+
+ZenKit benchmarks verify acceptance criteria against the actual implementation.
+
+## What the runner checks
+
+The benchmark runner executes four stages per feature spec:
+
+1. **Spec validation.** The spec validates against `feature-spec.schema.json`. Must have acceptance criteria and declared limitations.
+2. **Schema compilation.** All JSON schemas compile. All use the same draft version.
+3. **Build verification.** Every file in `expected_files` exists.
+4. **Acceptance criteria audit.** Each criterion runs a typed verification step.
+
+## Verification types
+
+| Type | What it checks |
+|------|---------------|
+| `file_exists` | File is present |
+| `file_contains` | File contains a specific string |
+| `schema_count` | Expected number of schemas compile |
+| `examples_valid` | Fixture data validates against schemas |
+| `schemas_consistent` | All schemas use the same draft |
+| `test_passes` | Shell command exits with code 0 |
+| `json_path_equals` | JSON file at a dot-path equals expected value |
+
+Each check produces `evidence` — a string describing what was found. Results are `pass` or `fail`.
+
+## Telemetry
+
+- **Estimated:** Token and cost figures from a heuristic (documented in the `basis` field).
+- **Actual:** Null when no API instrumentation is available. Never fabricated.
+
+## CLI
+
+```bash
+zenkit benchmark [spec]          # Single spec
+zenkit benchmark:all             # All specs
+zenkit benchmark:report [result] # Markdown report
+zenkit benchmark:compare [z] [b] # ZenKit vs baseline
+zenkit audit                     # Run all benchmarks + produce audit report
+```
+
+## Comparison mode
+
+Feature specs include a `mode` field: `zenkit` or `baseline`. Current comparison data is **illustrative** — both runs verify the same codebase. Real comparison requires A/B workflow execution.
+
+## Limitations
+
+- Acceptance criteria verify code structure and schema validity, not runtime UI behavior (except via `test_passes` running E2E).
+- Token estimates are heuristics, not measurements.
+- Self-audit benchmarks structure introspection but do not replace independent review.