@workflow-cannon/workspace-kit 0.14.0 → 0.16.0

package/README.md

@@ -1,136 +1,85 @@
 AI agents: `./.ai/` is the authoritative source of truth; read all files there before any analysis, planning, or code changes, and follow `./.ai/` over `README.md`, `./docs/`, and conflicting existing code patterns.
 
-# Workflow Cannon
-
-Workflow Cannon is the canonical home of `@workflow-cannon/workspace-kit` and the operational docs that drive its evolution.
-
-It is built for developers using VS Code who want safe, reproducible, package-first workflow automation with clear release evidence.
-
-## Table of Contents
-
-- [What This Repository Is](#what-this-repository-is)
-- [Big-Picture Vision](#big-picture-vision)
-- [Current Status](#current-status)
-- [Goals](#goals)
-- [Package](#package)
-- [Repository Map](#repository-map)
-- [Documentation Index](#documentation-index)
-- [License](#license)
-
-## What This Repository Is
+<div align="center">
+  <img src="title_image.png" alt="Workflow Cannon" width="720" />
+</div>
 
-Workflow Cannon is the source of truth for:
-
-- The `@workflow-cannon/workspace-kit` package
-- Maintainer planning and execution artifacts
-- Consumer validation and release-readiness evidence
-
-Guiding characteristics:
+# Workflow Cannon
 
-- Package-first delivery and verification
-- Deterministic, auditable workflows
-- Safe-by-default operations (validation, traceability, rollback-friendly changes)
+**[`@workflow-cannon/workspace-kit`](https://www.npmjs.com/package/@workflow-cannon/workspace-kit)** — CLI, task engine, and workflow contracts for repos that want deterministic, policy-governed automation with clear evidence.
 
-## Big-Picture Vision
+## Quick start (clone this repo)
 
-Workflow Cannon is evolving from a package and docs repository into a developer workflow platform that can:
+**Needs:** Node.js **22+** (see CI), **pnpm 10** (see `packageManager` in `package.json`).
 
-- model planning, tasks, policy, and execution as first-class, versioned contracts
-- run repeatable workflows with deterministic outcomes and evidence capture
-- continuously improve itself based on observed friction and outcome data
+```bash
+git clone https://github.com/NJLaPrell/workflow-cannon.git
+cd workflow-cannon
+pnpm install
+pnpm run build
+```
 
-The long-term direction in this repository is to close the loop between:
+Verify the kit sees your workspace:
 
-1. **What happened** (transcripts, diffs, run artifacts, diagnostics)
-2. **What should change** (recommendations to templates, rules, process, and config)
-3. **What gets adopted** (human-reviewed approvals, policy checks, safe rollout)
+```bash
+node dist/cli.js doctor
+node dist/cli.js --help
+```
 
-### Enhancement Engine (automatic learning and correction)
+Try **read-only** task-engine queries:
 
-The Improvement/Enhancement Engine is intended to detect weak spots in workflows and rules, then generate high-signal fixes with supporting evidence. Instead of hard-coding static process forever, the system should learn from real usage patterns and propose better defaults.
+```bash
+node dist/cli.js run list-tasks '{}'
+node dist/cli.js run get-next-actions '{}'
+```
 
-In practice, this means:
+**Developing:** after edits, `pnpm run build` then `pnpm test` (or `pnpm run phase5-gates` before larger changes). If `workspace-kit` is not on your `PATH`, use `node dist/cli.js …` from the repo root (same as above).
 
-- detect recurring failure patterns, manual rework, and template drift
-- emit recommendation items with confidence, deduping, and provenance
-- route recommendations through an approval queue (`accept`, `decline`, `accept edited`)
-- apply approved changes through guarded automation (dry-run, diff, rollback-ready)
-- measure post-change outcomes so future recommendations improve over time
+## Quick start (use the package in another project)
 
-This keeps automation adaptive without sacrificing safety, governance, or developer trust.
+```bash
+npm install @workflow-cannon/workspace-kit
+npx workspace-kit --help
+```
 
-## Current Status
+Or with pnpm: `pnpm add @workflow-cannon/workspace-kit` then `pnpm exec workspace-kit --help`.
 
-**Release and phase truth:** see `docs/maintainers/ROADMAP.md` and `docs/maintainers/data/workspace-kit-status.yaml`. **Task queue:** `.workspace-kit/tasks/state.json` (ids and `status` are authoritative for execution).
+## What this repo contains
 
-- **Phases 0–7** are complete through **`v0.9.0`** (see roadmap for slice ids).
-- **Phase 8** ships maintainer/onboarding hardening (`v0.10.0`): policy denial clarity, runbooks, and doc alignment for CLI vs `run` approval.
-- **Phase 9–10** ship agent/onboarding parity (`v0.11.0`): interactive policy opt-in, strict response-template mode, Agent CLI map (`docs/maintainers/AGENT-CLI-MAP.md`), and CLI-first Cursor guidance.
-- **Phase 11** ships architectural review follow-up hardening (`v0.12.0`): policy/session denial edge tests, persistence concurrency semantics, release doc-sweep checklist, and runtime path audit note.
-- **Phase 12** ships Cursor-native thin-client extension delivery (`v0.13.0`): dashboard/tasks/config UI flows, extension test suite, and operator/security docs.
-- **Phase 13** is the active queue: Task Engine lifecycle tightening (`T311+`).
+| Area | What |
+| --- | --- |
+| **CLI** | `workspace-kit` — `doctor`, `config`, `run <module-command>` (see `workspace-kit run` with no args for the list). |
+| **Task engine** | Canonical queue in `.workspace-kit/tasks/state.json`; lifecycle via `run-transition`. Wishlist ideation uses ids `W###` (see [`docs/maintainers/runbooks/wishlist-workflow.md`](docs/maintainers/runbooks/wishlist-workflow.md)). |
+| **Docs** | Maintainer process, roadmap, and changelog under `docs/maintainers/`. |
+| **Cursor extension** (optional) | Thin UI in `extensions/cursor-workflow-cannon/` — build with `pnpm run ui:prepare`. |
 
-Historical note: this file’s milestone list is not the live queue—always check task state for **`ready`** work.
+There is **no** built-in IDE slash command like `/qt` from this package; editor integrations are **your** config (e.g. `.cursor/commands/`), while **`workspace-kit`** is the supported CLI.
 
-## Goals
+## Policy and approvals (read this before mutating state)
 
-- Keep package implementation and release operations centralized here.
-- Preserve independent consumer validation and update cadence.
-- Grow modular capabilities for planning, tasking, configuration, policy, and improvement.
-- Build a human-governed enhancement loop that learns from usage and recommends better workflows/rules.
-- Maintain deterministic and auditable behavior as system complexity increases.
+Sensitive `workspace-kit run` commands require JSON **`policyApproval`** in the third CLI argument. Chat approval is not enough. Env-based approval applies to `init` / `upgrade` / `config`, not the `run` path.
 
-## Package
+- **Human guide:** [`docs/maintainers/POLICY-APPROVAL.md`](docs/maintainers/POLICY-APPROVAL.md)
+- **Copy-paste table:** [`docs/maintainers/AGENT-CLI-MAP.md`](docs/maintainers/AGENT-CLI-MAP.md)
 
-Install:
+## Project status and roadmap
 
-```bash
-npm install @workflow-cannon/workspace-kit
-```
+Release cadence, phase history, and strategic decisions: [`docs/maintainers/ROADMAP.md`](docs/maintainers/ROADMAP.md). **Live execution queue:** `.workspace-kit/tasks/state.json` (`status` and `id` are authoritative — not this README’s milestone bullets).
 
-### How to run the CLI (this repo and consumers)
+Snapshot: [`docs/maintainers/data/workspace-kit-status.yaml`](docs/maintainers/data/workspace-kit-status.yaml).
 
-There is **no** IDE slash command like `/qt` defined by this package unless your own editor config adds one. Supported entrypoints:
+## Where to go next
 
-| Context | Command |
+| Goal | Start here |
 | --- | --- |
-| **Installed package** | `npx @workflow-cannon/workspace-kit --help` or `pnpm exec workspace-kit --help` when the package is a dependency |
-| **Developing this repo** | `pnpm run build` then `node dist/cli.js --help` or `pnpm exec workspace-kit --help` if linked |
-| **Transcript helpers** | `pnpm run transcript:sync` / `pnpm run transcript:ingest` (see maintainer runbooks) |
-
-Mutating commands require policy approval: **`docs/maintainers/POLICY-APPROVAL.md`** (JSON **`policyApproval`** for `workspace-kit run`, env for `config`/`init`/`upgrade`).
-
-## Repository Map
-
-- `README.md` - project entry point
-- `.ai/PRINCIPLES.md` - project goals and decision principles (canonical AI)
-- `docs/maintainers/ROADMAP.md` - roadmap and decision log
-- `.workspace-kit/tasks/state.json` - execution tracking
-- `docs/maintainers/ARCHITECTURE.md` - architecture direction
-- `docs/maintainers/DECISIONS.md` - focused design/decision notes
-- `docs/maintainers/RELEASING.md` - release checklist and validation expectations
-- `.ai/module-build.md` - canonical AI module build guidance
-- `docs/maintainers/` - maintainer process and boundary docs
-- `docs/maintainers/module-build-guide.md` - human-readable module build guidance
-- `docs/adr/` - ADR templates and records
-
-## Documentation Index
-
-- Project goals and decision principles: `.ai/PRINCIPLES.md`
-- Strategy and long-range direction: `docs/maintainers/ROADMAP.md`
-- Active execution tasks: `.workspace-kit/tasks/state.json`
-- Glossary and agent-guidance terms: `docs/maintainers/TERMS.md`
-- Architecture direction: `docs/maintainers/ARCHITECTURE.md`
-- Project decisions: `docs/maintainers/DECISIONS.md`
-- Governance policy surface: `docs/maintainers/GOVERNANCE.md`
-- Release process and gates: `docs/maintainers/RELEASING.md`
-- Policy / approval surfaces: `docs/maintainers/POLICY-APPROVAL.md`
-- Canonical changelog: `docs/maintainers/CHANGELOG.md` (`CHANGELOG.md` at repo root is pointer-only)
-- Canonical AI module build guidance: `.ai/module-build.md`
-- Human module build guide: `docs/maintainers/module-build-guide.md`
-- Security, support, and governance: `docs/maintainers/SECURITY.md`, `docs/maintainers/SUPPORT.md`, `docs/maintainers/GOVERNANCE.md`
-- AI behavior rules and command wrappers: `.cursor/rules/`, `.cursor/commands/`
+| Goals, trade-offs, gates | [`.ai/PRINCIPLES.md`](.ai/PRINCIPLES.md) |
+| Roadmap & versions | [`docs/maintainers/ROADMAP.md`](docs/maintainers/ROADMAP.md) |
+| Changelog | [`docs/maintainers/CHANGELOG.md`](docs/maintainers/CHANGELOG.md) |
+| Release process | [`docs/maintainers/RELEASING.md`](docs/maintainers/RELEASING.md) |
+| Glossary | [`docs/maintainers/TERMS.md`](docs/maintainers/TERMS.md) |
+| Architecture | [`docs/maintainers/ARCHITECTURE.md`](docs/maintainers/ARCHITECTURE.md) |
+| Agent/CLI execution | [`docs/maintainers/AGENTS.md`](docs/maintainers/AGENTS.md) |
 
 ## License
 
-Licensed under MIT. See `LICENSE`.
+MIT. See [`LICENSE`](LICENSE).

package/dist/modules/approvals/review-runtime.js

@@ -1,15 +1,7 @@
 import { appendLineageEvent } from "../../core/lineage-store.js";
-import { TaskStore } from "../task-engine/store.js";
+import { openPlanningStores } from "../task-engine/planning-open.js";
 import { TransitionService } from "../task-engine/service.js";
 import { appendDecisionRecord, computeDecisionFingerprint, readDecisionFingerprints } from "./decisions-store.js";
-function taskStoreRelativePath(ctx) {
-    const tasks = ctx.effectiveConfig?.tasks;
-    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
-        return undefined;
-    }
-    const p = tasks.storeRelativePath;
-    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
-}
 function getEvidenceKey(task) {
     const m = task.metadata;
     const k = m && typeof m.evidenceKey === "string" ? m.evidenceKey : "";
@@ -24,8 +16,8 @@ export async function runReviewItem(ctx, args, actor) {
     if (decision === "accept_edited" && !(typeof args.editedSummary === "string" && args.editedSummary.trim())) {
         return { ok: false, code: "invalid-args", message: "accept_edited requires non-empty editedSummary" };
     }
-    const store = new TaskStore(ctx.workspacePath, taskStoreRelativePath(ctx));
-    await store.load();
+    const planning = await openPlanningStores(ctx);
+    const store = planning.taskStore;
     const task = store.getTask(taskId);
     if (!task) {
         return { ok: false, code: "task-not-found", message: `Task '${taskId}' not found` };

package/dist/modules/improvement/generate-recommendations-runtime.js

@@ -1,17 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { TaskStore } from "../task-engine/store.js";
+import { openPlanningStores } from "../task-engine/planning-open.js";
 import { appendLineageEvent } from "../../core/lineage-store.js";
 import { loadImprovementState, saveImprovementState } from "./improvement-state.js";
 import { ingestAgentTranscripts, ingestConfigMutations, ingestGitDiffBetweenTags, ingestPolicyDenials, ingestTaskTransitionFriction, taskIdForEvidenceKey } from "./ingest.js";
 import { priorityForTier } from "./confidence.js";
-function taskStoreRelativePath(ctx) {
-    const tasks = ctx.effectiveConfig?.tasks;
-    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
-        return undefined;
-    }
-    const p = tasks.storeRelativePath;
-    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
-}
 function hasEvidenceKey(tasks, key) {
     return tasks.some((t) => {
         const m = t.metadata;
@@ -48,8 +40,8 @@ export function getMaxRecommendationCandidatesPerRun(ctx) {
 }
 export async function runGenerateRecommendations(ctx, args) {
     const runId = randomUUID();
-    const store = new TaskStore(ctx.workspacePath, taskStoreRelativePath(ctx));
-    await store.load();
+    const planning = await openPlanningStores(ctx);
+    const store = planning.taskStore;
     const state = await loadImprovementState(ctx.workspacePath);
     const transcriptsRoot = resolveTranscriptArchivePath(ctx, args);
     const fromTag = typeof args.fromTag === "string" ? args.fromTag.trim() : undefined;

package/dist/modules/index.d.ts

@@ -7,3 +7,5 @@ export { workspaceConfigModule } from "./workspace-config/index.js";
 export { planningModule } from "./planning/index.js";
 export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, getNextActions } from "./task-engine/index.js";
 export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult, TaskEngineErrorCode, TaskAdapter, TaskAdapterCapability, NextActionSuggestion, BlockingAnalysisEntry } from "./task-engine/index.js";
+export type { WishlistItem, WishlistStatus, WishlistStoreDocument } from "./task-engine/index.js";
+export { WishlistStore, validateWishlistIntakePayload, validateWishlistUpdatePayload, buildWishlistItemFromIntake, WISHLIST_ID_RE } from "./task-engine/index.js";

package/dist/modules/index.js

@@ -5,3 +5,4 @@ export { computeHeuristicConfidence, HEURISTIC_1_ADMISSION_THRESHOLD, shouldAdmi
 export { workspaceConfigModule } from "./workspace-config/index.js";
 export { planningModule } from "./planning/index.js";
 export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, getNextActions } from "./task-engine/index.js";
+export { WishlistStore, validateWishlistIntakePayload, validateWishlistUpdatePayload, buildWishlistItemFromIntake, WISHLIST_ID_RE } from "./task-engine/index.js";

package/dist/modules/task-engine/index.d.ts

@@ -5,4 +5,9 @@ export { TransitionService } from "./service.js";
 export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
 export { getNextActions } from "./suggestions.js";
 export { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
+export { WishlistStore } from "./wishlist-store.js";
+export type { WishlistItem, WishlistStatus, WishlistStoreDocument } from "./wishlist-types.js";
+export { validateWishlistIntakePayload, validateWishlistUpdatePayload, buildWishlistItemFromIntake, WISHLIST_ID_RE } from "./wishlist-validation.js";
+export { openPlanningStores } from "./planning-open.js";
+export { getTaskPersistenceBackend, planningSqliteDatabaseRelativePath, planningTaskStoreRelativePath, planningWishlistStoreRelativePath } from "./planning-config.js";
 export declare const taskEngineModule: WorkflowModule;