@workflow-cannon/workspace-kit 0.14.0 → 0.16.0

package/dist/modules/task-engine/wishlist-validation.js

@@ -0,0 +1,96 @@
+/** Wishlist identifiers use a dedicated namespace: `W` + digits (e.g. `W1`, `W42`). */
+export const WISHLIST_ID_RE = /^W\d+$/;
+const REQUIRED_STRING_FIELDS = [
+    "title",
+    "problemStatement",
+    "expectedOutcome",
+    "impact",
+    "constraints",
+    "successSignals",
+    "requestor",
+    "evidenceRef"
+];
+function nonEmptyString(v, label) {
+    if (typeof v !== "string" || v.trim().length === 0) {
+        return null;
+    }
+    return v.trim();
+}
+/**
+ * Validates intake fields for creating or replacing content on an open wishlist item.
+ * Wishlist items never carry a Task Engine `phase`; reject if present.
+ */
+export function validateWishlistIntakePayload(args) {
+    const errors = [];
+    if ("phase" in args && args.phase !== undefined) {
+        errors.push("Wishlist items must not include 'phase'; only canonical tasks are phased.");
+    }
+    const id = typeof args.id === "string" ? args.id.trim() : "";
+    if (!id) {
+        errors.push("Wishlist 'id' is required.");
+    }
+    else if (!WISHLIST_ID_RE.test(id)) {
+        errors.push(`Wishlist 'id' must match ${WISHLIST_ID_RE.source} (e.g. W1).`);
+    }
+    for (const key of REQUIRED_STRING_FIELDS) {
+        const s = nonEmptyString(args[key], key);
+        if (s === null) {
+            errors.push(`Wishlist '${key}' is required and must be a non-empty string.`);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true };
+}
+export function buildWishlistItemFromIntake(args, timestamp) {
+    const id = args.id.trim();
+    const item = {
+        id,
+        status: "open",
+        title: args.title.trim(),
+        problemStatement: args.problemStatement.trim(),
+        expectedOutcome: args.expectedOutcome.trim(),
+        impact: args.impact.trim(),
+        constraints: args.constraints.trim(),
+        successSignals: args.successSignals.trim(),
+        requestor: args.requestor.trim(),
+        evidenceRef: args.evidenceRef.trim(),
+        createdAt: timestamp,
+        updatedAt: timestamp
+    };
+    return item;
+}
+export function validateWishlistUpdatePayload(updates) {
+    if ("phase" in updates && updates.phase !== undefined) {
+        return { ok: false, errors: ["Wishlist updates cannot set 'phase'."] };
+    }
+    const errors = [];
+    const allowed = new Set([
+        "title",
+        "problemStatement",
+        "expectedOutcome",
+        "impact",
+        "constraints",
+        "successSignals",
+        "requestor",
+        "evidenceRef"
+    ]);
+    for (const key of Object.keys(updates)) {
+        if (!allowed.has(key)) {
+            errors.push(`Cannot update unknown or immutable wishlist field '${key}'.`);
+        }
+    }
+    for (const key of REQUIRED_STRING_FIELDS) {
+        if (key in updates) {
+            const s = nonEmptyString(updates[key], key);
+            if (s === null) {
+                errors.push(`Wishlist '${key}' must be a non-empty string when provided.`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -41,6 +41,7 @@
     "ui:watch": "cd extensions/cursor-workflow-cannon && npm run watch"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.5.0",
     "typescript": "^5.9.3"
   },
@@ -48,5 +49,13 @@
     "dist",
     "src/modules/documentation",
     "package.json"
-  ]
+  ],
+  "dependencies": {
+    "better-sqlite3": "^12.8.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
+  }
 }

package/src/modules/documentation/README.md

@@ -24,6 +24,7 @@ Files under `templates/`; `documentType` is the filename (basename). Keep this l
 - `AGENTS.md`
 - `ARCHITECTURE.md`
 - `PRINCIPLES.md`
+- `README.md`
 - `RELEASING.md`
 - `ROADMAP.md`
 - `SECURITY.md`

package/src/modules/documentation/instructions/document-project.md

@@ -18,6 +18,7 @@ All `.md` files under `sources.templatesRoot` (default `src/modules/documentatio
 - `AGENTS.md`
 - `ARCHITECTURE.md`
 - `PRINCIPLES.md`
+- `README.md`
 - `RELEASING.md`
 - `ROADMAP.md`
 - `SECURITY.md`

package/src/modules/documentation/instructions/generate-document.md

@@ -8,6 +8,7 @@ Generate a single document for both canonical AI and human-readable surfaces usi
   - `AGENTS.md`
   - `ARCHITECTURE.md`
   - `PRINCIPLES.md`
+  - `README.md`
   - `RELEASING.md`
   - `ROADMAP.md`
   - `SECURITY.md`

package/src/modules/documentation/templates/README.md

@@ -0,0 +1,89 @@
+<!--
+  Human output path: docs/maintainers/README.md (image uses ../title_image.png from that location).
+  Root README.md: mirror this body but use title_image.png and keep the agent notice line at the very top.
+  Audience: developers cloning the repo or adding @workflow-cannon/workspace-kit to a project who want to run something useful in minutes.
+-->
+
+<div align="center">
+  <img src="../title_image.png" alt="Workflow Cannon" width="720" />
+</div>
+
+# Workflow Cannon
+
+**[`@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.
+
+## Quick start (clone this repo)
+
+**Needs:** Node.js **22+** (see CI), **pnpm 10** (see `packageManager` in `package.json`).
+
+```bash
+git clone https://github.com/NJLaPrell/workflow-cannon.git
+cd workflow-cannon
+pnpm install
+pnpm run build
+```
+
+Verify the kit sees your workspace:
+
+```bash
+node dist/cli.js doctor
+node dist/cli.js --help
+```
+
+Try **read-only** task-engine queries:
+
+```bash
+node dist/cli.js run list-tasks '{}'
+node dist/cli.js run get-next-actions '{}'
+```
+
+**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).
+
+## Quick start (use the package in another project)
+
+```bash
+npm install @workflow-cannon/workspace-kit
+npx workspace-kit --help
+```
+
+Or with pnpm: `pnpm add @workflow-cannon/workspace-kit` then `pnpm exec workspace-kit --help`.
+
+## What this repo contains
+
+| 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 maintainer runbooks). |
+| **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`. |
+
+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.
+
+## Policy and approvals (read this before mutating state)
+
+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.
+
+- **Human guide:** [`docs/maintainers/POLICY-APPROVAL.md`](POLICY-APPROVAL.md)
+- **Copy-paste table:** [`docs/maintainers/AGENT-CLI-MAP.md`](AGENT-CLI-MAP.md)
+
+## Project status and roadmap
+
+Release cadence, phase history, and strategic decisions: [`docs/maintainers/ROADMAP.md`](ROADMAP.md). **Live execution queue:** `.workspace-kit/tasks/state.json` (`status` and `id` are authoritative — not this README’s milestone bullets).
+
+Snapshot: [`docs/maintainers/data/workspace-kit-status.yaml`](data/workspace-kit-status.yaml).
+
+## Where to go next
+
+| Goal | Start here |
+| --- | --- |
+| Goals, trade-offs, gates | [`.ai/PRINCIPLES.md`](../.ai/PRINCIPLES.md) |
+| Roadmap & versions | [`ROADMAP.md`](ROADMAP.md) |
+| Changelog | [`CHANGELOG.md`](CHANGELOG.md) |
+| Release process | [`RELEASING.md`](RELEASING.md) |
+| Glossary | [`TERMS.md`](TERMS.md) |
+| Architecture | [`ARCHITECTURE.md`](ARCHITECTURE.md) |
+| Agent/CLI execution | [`AGENTS.md`](AGENTS.md) |
+
+## License
+
+MIT. See [`LICENSE`](../LICENSE) at the repository root.