@brainervirus/workit-core 6.0.0 → 7.0.0

package/README.md

@@ -1,42 +1,24 @@
 # @brainervirus/workit-core
 
 [![CI](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml/badge.svg)](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@brainervirus/workit-core.svg)](https://www.npmjs.com/package/@brainervirus/workit-core)
-[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
+[![npm](https://img.shields.io/npm/v/@brainervirus/workit-core.svg)](https://www.npmjs.com/package/@brainervirus/workit-core)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/BrainerVirus/workit/blob/main/LICENSE)
 
-Shared core for the workit plugins — the single source of workflow logic that the OpenCode, Cursor, and CLI packages adapt to their native surfaces.
+The shared core of [Workit](https://github.com/BrainerVirus/workit): task event store, run ledger,
+policy, checks, forge and stack logic, host-hook protocol, and the single
+source of the eleven method skills. Every host adapter and the CLI bundle it.
 
-## When you need it directly
-
-End users do **not** install this package directly — install `@brainervirus/workit-cli` (wizard) or the platform plugin (`@brainervirus/workit-opencode`, `@brainervirus/workit-cursor`). The adapters pull core in as a dependency and ship it with their bundles.
-
-You consume `@brainervirus/workit-core` directly only when:
-
-- Building a new host adapter (e.g. a future `codex/` adapter) that maps a host's native surfaces to the shared `src/core/` logic.
-- Reading the canonical source of workflow behavior: task and policy engine, approval flow, commit/PR, changelog, YouTrack, doctor, and diagnostics.
-
-## Layout and ownership
+End users do not install this package; install the CLI or a host plugin (see
+the [root README](https://github.com/BrainerVirus/workit#quickstart)). Use it directly only to build a
+new host adapter.
 
 | Path | Contents |
 | --- | --- |
-| `src/core/` | Shared TS logic (setup, registration, doctor, logger, branch, PR, changelog, YouTrack, task/policy engine, support matrix). |
-| `src/core.ts` | Package entry; adapters import `@brainervirus/workit-core/src/*`. |
-| `skills/` | 11 `workit-*` method skills (single source; adapters ship generated byte-identical copies). |
-| `scripts/` | Shared shell installers/launchers and the release-time workspace-dep rewrite. |
-| `templates/` | Execution and Superpowers contract templates. |
-
-Adapters map host-native surfaces to `src/core/`; they never re-implement core logic. Keep shared behavior here and host-specific presentation in each adapter.
-
-## Exports
-
-- Main entry: `./src/core.ts`.
-- Subpath exports: `./src/*.ts` (e.g. `@brainervirus/workit-core/src/core/task-store`), plus `./package.json`.
-- Setup, doctor, upgrade, uninstall and host-install code lives in `@brainervirus/workit-cli` (`src/admin/`), not here, so host hooks and plugins never bundle it.
-
-## Package scripts
-
-```bash
-bun run typecheck   # tsc --noEmit
-```
-
-Core has no build step — the adapters bundle it at build time. See the root [README](../../README.md) for the full development, CI, and versioning notes.
+| `src/` | Store, ledger, checks, forge, stack, grants, hooks (`src/hooks/`), task/policy engine (`src/core/`) |
+| `skills/` | The `workit-*` method skills; adapters ship generated copies |
+| `scripts/` | Installers, launchers and release helpers |
+| `templates/` | Contract and issue-update templates |
+
+Exports: `./src/core.ts` and `./src/*.ts` subpaths. Setup, doctor, upgrade and
+uninstall live in `@brainervirus/workit-cli`. There is no build step; adapters
+bundle core. Development: [AGENTS.md](https://github.com/BrainerVirus/workit/blob/main/AGENTS.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-deslop/SKILL.md

@@ -22,7 +22,7 @@ behavior. A change that wants new behavior is its own change.
    validator that changes behavior is not deslop.
 5. **Re-run the checks** and report lines removed, not lines written. Nothing
    to clean is a valid result: say what you checked ("0 removals; ran knip and
-   read the diff"). When a tracked task lists a `pre-pr-cleanup` requirement,
+   read the diff"). When a tracked task lists a `pre-pr-cleanup` requirement (≤6.x tasks),
    record this result as its evidence.
 
 ## Example

package/skills/workit-implement/SKILL.md

@@ -11,6 +11,9 @@ description: Build a requested change in small verified steps - follow local pat
    neighbour that already does something similar. Copy its patterns, names and
    error handling. Repo rules (AGENTS.md, CLAUDE.md, lint config) win.
 2. On the default branch? Branch first: `workit git branch --kind feature --slug <s>`.
+   Tracking it? Judge once: `workit policy assess --judge risk=normal
+   behavior=yes product-choice=no plan=no` (trivial and no for a mechanical
+   fix); Workit derives what close needs.
 3. Small steps that each leave the tree green. Behavior change: write the
    acceptance as Given/When/Then and see a test fail first (workit-bdd).
    Mechanical change: the existing checks are enough.
@@ -24,10 +27,12 @@ description: Build a requested change in small verified steps - follow local pat
    PR (`workit git push`, `workit pr create --fill`, then workit-ship) only when
    that was requested, or the request implies delivery and `workit grant show`
    reports `defaultEndpoint` `pr`; otherwise the endpoint is `commit`.
-7. Hand off verification. Never record a passing verdict on your own work.
-   Start a fresh verifier with its own session (`WORKIT_SESSION_ID=<yours>-v1`;
-   Claude Code: the `verifier` agent, which the hook gives one); it runs
-   verify-<app> and `workit ledger verdict`. Before saying done, reconcile
+7. Verify. Normal risk: after `workit check test` passes, record your own
+   `workit ledger verdict tests-verified --self --how "<what you ran>"`; it
+   reads self-reviewed, never verified. High risk, a workspace with
+   `verification: independent` (`workit grant show`) or a verified merge needs
+   a fresh verifier with its own session (`WORKIT_SESSION_ID=<yours>-v1`;
+   Claude Code: the `verifier` agent). Before saying done, reconcile
    every named deliverable against the target checkout and observe it (for a push:
    `workit verify-delivery push`).
 

package/skills/workit-review/SKILL.md

@@ -8,6 +8,8 @@ description: Independent review of a diff, branch or PR - intent fidelity and st
 Review the candidate, never the author's summary of it. A session that wrote a
 commit on the branch cannot record a passing verdict: if that is you, hand the
 review to a fresh agent (Claude Code: the `reviewer` or `verifier` agent).
+An author's `--self` verdict reads self-reviewed and never counts as
+independent; `type-check-only` never proves a behavior change.
 
 1. Pin the candidate: `git rev-parse HEAD`, the base, `git diff <base>...HEAD`;
    for a PR, `workit pr status --json` (checks, unresolved threads).

package/skills/workit-shape/SKILL.md

@@ -43,7 +43,7 @@ a choice that is hard to reverse, surprising and a real trade-off; a glossary
 entry for a term you had to resolve; `.out-of-scope/<concept>.md` for a rejected
 request that will come back. A one-file mechanical fix gets none. Formats and
 triggers: `references/knowledge.md`. Record each settled choice once:
-`workit ledger decision "<what>" --why "<why>"`.
+`workit ledger decision "<what>" --why "<why>"`; cite a plan: `workit policy assess --ref <path>`.
 
 ## 5. Slice as tracer bullets
 

package/skills/workit-ship/SKILL.md

@@ -33,7 +33,7 @@ merge: Stop at PR-ready unless the user set merge as the endpoint.
    `workit ci rerun --failed --reason flake` (once per head). Real: reproduce
    with `workit check`, fix the root cause, batch fixes into one push.
 6. **Verified.** After the last push a non-author records a verdict
-   (workit-review). Land only when granted: `workit stack land` (the
+   (workit-review); `pr status` showing self-reviewed is not verified. Land only when granted: `workit stack land` (the
    contiguous verified run from the root) or `workit pr merge`.
 7. **Observe it landed:** `workit verify-delivery pr` or `merge`.
 

package/src/autonomy.ts

@@ -92,6 +92,19 @@ export const DEFAULT_GRANTS: Readonly<Grants> = Object.freeze({
  */
 export type DefaultEndpoint = "commit" | "pr";
 export const DEFAULT_ENDPOINT: DefaultEndpoint = "commit";
+/**
+ * How a normal-risk behavior change is verified (S17). `self` (default): an
+ * observed passing `workit check test` plus the author's own `--self`
+ * verdict, labelled self-reviewed. `independent`: a verdict from a session
+ * that did not author the branch. User config only, like grants.
+ */
+export type VerificationMode = "self" | "independent";
+export const DEFAULT_VERIFICATION: VerificationMode = "self";
+export const verificationOf = (entry: unknown): VerificationMode =>
+  (entry as { verification?: unknown } | null)?.verification === "independent"
+    ? "independent"
+    : "self";
+
 const endpointOf = (entry: unknown): DefaultEndpoint =>
   (entry as { defaultEndpoint?: unknown } | null)?.defaultEndpoint === "pr" ? "pr" : "commit";
 
@@ -106,6 +119,7 @@ export type Autonomy = {
   source: AutonomySource;
   accountConfigured: boolean;
   defaultEndpoint: DefaultEndpoint;
+  verification: VerificationMode;
   /** Set when the grants file was not read (see grantsOverride). */
   note?: string;
 };
@@ -182,6 +196,7 @@ export function resolveAutonomy(cwd: string): Autonomy {
       source: "default",
       accountConfigured: false,
       defaultEndpoint: DEFAULT_ENDPOINT,
+      verification: DEFAULT_VERIFICATION,
       note: override,
     };
   const workspace = resolveWorkspaceFrom(
@@ -197,6 +212,7 @@ export function resolveAutonomy(cwd: string): Autonomy {
     source,
     accountConfigured: Boolean(workspace?.vcs?.account),
     defaultEndpoint: endpointOf(workspace),
+    verification: verificationOf(workspace),
   };
 }
 
@@ -282,6 +298,7 @@ export type GrantWrite =
       grants: Grants;
       configured: GrantKind[];
       defaultEndpoint: DefaultEndpoint;
+      verification: VerificationMode;
     }
   | { ok: false; code: "not_found" | "invalid_input" | "failed"; error: string };
 
@@ -298,6 +315,8 @@ export function writeGrants(
   dir: string = grantsDir(),
   /** A new default endpoint; `null` removes it (back to `commit`). */
   endpoint?: DefaultEndpoint | null,
+  /** A new verification mode; `null` removes it (back to `self`). */
+  verification?: VerificationMode | null,
 ): GrantWrite {
   const current = readWorkspacesResult(dir);
   if (current.status === "missing")
@@ -329,6 +348,8 @@ export function writeGrants(
   delete entry.autoApprove;
   if (endpoint === null || endpoint === DEFAULT_ENDPOINT) delete entry.defaultEndpoint;
   else if (endpoint) entry.defaultEndpoint = endpoint;
+  if (verification === null || verification === DEFAULT_VERIFICATION) delete entry.verification;
+  else if (verification) entry.verification = verification;
   const autonomy = {
     ...unknown,
     ...Object.fromEntries(
@@ -366,6 +387,7 @@ export function writeGrants(
     grants: { ...DEFAULT_GRANTS, ...grants },
     configured: GRANT_KINDS.filter((kind) => grants[kind] !== undefined),
     defaultEndpoint: endpointOf(entry),
+    verification: verificationOf(entry),
   };
 }
 
@@ -378,6 +400,7 @@ export function listGrants(dir: string = grantsDir()): {
     grants: Grants;
     configured: GrantKind[];
     defaultEndpoint: DefaultEndpoint;
+    verification: VerificationMode;
   }[];
   error?: string;
 } {
@@ -394,6 +417,7 @@ export function listGrants(dir: string = grantsDir()): {
         grants: { ...DEFAULT_GRANTS, ...grants },
         configured: GRANT_KINDS.filter((kind) => grants[kind] !== undefined),
         defaultEndpoint: endpointOf(entry),
+        verification: verificationOf(entry),
       };
     }),
   };

package/src/core/methods.ts

@@ -114,10 +114,10 @@ Autonomy contract:
   inferred, or guess. Prose is a note: only a configured check the CLI ran
   (\`workit check <name>\`) satisfies a gate; an ad-hoc
   \`workit check -- <cmd>\` never does.
-- Author is not verifier: never record a passing verdict on work your session
-  wrote. The lead starts each verifier with its own session
-  (\`WORKIT_SESSION_ID=<lead>-v<n>\`; Claude Code subagents get one from the
-  hook), and the verifier records \`workit ledger verdict\`.
+- Author is not verifier: your own verdict is \`--self\` (after an observed
+  \`workit check test\`), shown as self-reviewed, never verified. High risk,
+  \`verification: independent\` and merge need a verifier with its own
+  session (\`WORKIT_SESSION_ID=<lead>-v<n>\`; Claude Code subagents get one).
 - A local-commit endpoint does not imply PR readiness, and a local commit alone
   is not evidence of a requested remote push. Before reporting delivery,
   reconcile every requested item and observe it (\`workit verify-delivery\`).
@@ -130,7 +130,9 @@ PATH, \`npx -y @brainervirus/workit-cli\`). \`busy\` is retryable
 The task families (task, policy, evidence, finding, decision, worker, state)
 are optional continuity for tracked work; each branch has one implicit task
 that the first recording creates, and a solo edit needs no task. A decision
-records a user choice; it never authorizes an effect.
+records a user choice; it never authorizes an effect. Judge work once with
+\`workit policy assess --judge risk= behavior= product-choice= plan=\`; an
+open choice or missing plan blocks edits until recorded.
 Omit revisions; a revision_conflict means one you passed is stale, so re-read.
 Across repositories, bind each item to its checkout, branch and endpoint,
 resolve competing targets before a mutation, and reconcile an uncertain