@brainervirus/workit-core 8.18.0 → 8.19.1

package/package.json

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

package/skills/workit-implement/SKILL.md

@@ -24,7 +24,10 @@ description: Build a requested change in small verified steps - follow local pat
    lease waits and names its holder (`workit lock status`).
 5. Prove the feature on its real surface with the project's `verify-<app>`
    skill; none yet? Write one (workit-verify-app). Tests show branch behavior,
-   not that the feature works.
+   not that the feature works. The report carries what you observed: a UI
+   change a screenshot or console/network check (chrome devtools or
+   agent-browser), an API a quoted real response. App not runnable? Say so
+   plainly, never claim success.
 6. Commit: `workit git commit -m "<type>: <what>" -- <paths>` (or `--all`).
    No endpoint named? Stop here and state the next command. Hand delivery to
    ship, which pushes and opens the PR with its body shape (workit-ship), only
@@ -55,8 +58,7 @@ flag was never invoked)
 
 Good: "Added `--since`. measured: `workit check test` exit 0;
 `mytool log --since 2d` printed 3 entries against the fixture repo. inferred:
-the GitLab path behaves the same (shared parser, not run). Verification handed
-to the verifier agent."
+the GitLab path behaves the same (not run). Handed to the verifier agent."
 
 ## Check
 

package/skills/workit-verify-app/SKILL.md

@@ -27,7 +27,10 @@ way a user would.
    - **Drive:** how to exercise it: CLI invocations, `curl` against routes, a
      browser tool for UI, with fixture data.
    - **Evidence:** what to capture (exit code, response body, screenshot path)
-     and the command that records it.
+     and the command that records it. A UI is driven with chrome devtools or
+     agent-browser, with a screenshot or console/network observation; an API
+     with a real call, response quoted. The report carries the observation.
+     App not runnable? Say so plainly, never claim success.
    - **Cleanup:** stop processes, remove temp data.
    - **Feature map:** feature, how to drive it, expected observation.
 3. **Prove it end-to-end once:** launch, drive one feature, capture evidence,
@@ -54,7 +57,8 @@ report `clean`, `changed` (what) or `blocked` (why).
 Bad: "Verify by running the tests." (that is not the real surface)
 
 Good: "Launch `bun run dev` (ready: `listening on :5173`, 30 s). Drive:
-`curl -s localhost:5173/api/health` returns `{"ok":true}`. Evidence:
+`curl -s localhost:5173/api/health` returned `{"ok":true}`; screenshot of
+/settings at .workit-scratch/settings.png. Evidence:
 `workit check --name verify-web -- bun scripts/smoke.ts` exit 0."
 
 ## Check

package/skills/workit-verify-app/references/template.md

@@ -30,6 +30,8 @@ description: Launch, drive and observe <app> on its real surface (<cli|web|api>)
 ## Evidence
 `workit check --name verify-<app> -- <driver command>` records exit code and log.
 Screenshots go to `<tmp dir>/verify-<app>/<feature>.png`; cite the path.
+UI: also report a console or network observation. API: quote the real response.
+If the app cannot be run, say so plainly instead of claiming success.
 
 ## Cleanup
 `<command>` (stop servers, remove `<tmp dir>`).

package/src/hooks/handle.ts

@@ -8,7 +8,7 @@ import {
 import type { HostDescriptor, Support } from "./descriptor";
 import { branchGuidance } from "../core/branch";
 import { workspaceTrailers } from "../core/workspaces";
-import { recordIssuedSession } from "../host-session";
+import { judgeBranch, recordIssuedSession, verdictCommand } from "../host-session";
 import { heavyDenial, heavyGate, rewriteNote, splitDenial } from "./heavy-gate";
 import { shellPolicy } from "./policy";
 import {
@@ -114,9 +114,15 @@ const subagentStartText = (
   // and only with the token it hands to this subagent alone.
   // (An isolated judge's text is rebuilt with cwd "": the hook's own cwd then.)
   // Issued once: a replayed SubagentStart for the same id gets no token.
-  const token = session ? recordIssuedSession(input.cwd || process.cwd(), session, own) : null;
-  const flags = token ? `--session ${own} --token ${token}` : `--session ${own}`;
-  return `${readOnly} Its own Workit session is ${own}: record verdicts with \`workit ledger verdict <result> ${flags} ...\` so the ledger tells it apart from the author.${token ? " The token is this subagent's alone: never write it into a report, a file or a commit. --token needs a workit CLI at least as new as this plugin; if the CLI answers that --token is an unknown option, update the workit CLI (workit upgrade --cli) and record again." : ""}`;
+  const cwd = input.cwd || process.cwd();
+  const token = session ? recordIssuedSession(cwd, session, own) : null;
+  // Already issued: without its token the id is refused (unbound_session).
+  if (session && !token)
+    return `${readOnly} ${own} was already issued to an earlier subagent, so no token is handed out again and a verdict under it would be refused (unbound_session). Record no verdict as ${own}: spawn a fresh verifier or reviewer, which gets its own session and token.`;
+  const judge = event.agentType.endsWith("reviewer") ? "reviewer" : "verifier";
+  const line = verdictCommand({ branch: judgeBranch(cwd), judge, session: own, token });
+  const pick = judge === "verifier" ? ", --kind live when you drove the real surface" : "";
+  return `${readOnly} Its own Workit session is ${own}, so the ledger tells its verdicts apart from the author's. Record the verdict with exactly this command (pick the result${pick}, name the candidate branch if it differs, say what you ran): \`${line}\`.${token ? " The token is this subagent's alone: never write it into a report, a file or a commit. --token needs a workit CLI at least as new as this plugin; if the CLI answers that --token is an unknown option, update the workit CLI (workit upgrade --cli) and record again." : ""}`;
 };
 
 export function handleHook(input: HookInput, deps: HookDeps): HookDecision {

package/src/host-session.ts

@@ -10,7 +10,9 @@
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { isProtectedTarget } from "./core/branch";
 import { resolveStateDir } from "./core/logger";
+import { currentBranch } from "./git/rev";
 import { resolveStore } from "./store/paths";
 
 export type HostSession = { host: string | null; session: string | null };
@@ -217,6 +219,46 @@ export function recordIssuedSession(cwd: string, lead: string, issued: string):
   }
 }
 
+/**
+ * The branch a judge spawned from `cwd` most likely verifies: the checkout's
+ * branch, or null on a detached HEAD or a protected branch (a lead on `main`
+ * fanning out names the candidate in its brief, never its own branch).
+ */
+export function judgeBranch(cwd: string): string | null {
+  const branch = currentBranch(cwd);
+  return branch && !isProtectedTarget(cwd, branch) ? branch : null;
+}
+
+/**
+ * The exact verdict command a verifier or reviewer runs, filled in (#271
+ * S2a). `--token=` keeps a token from ever parsing as a flag. Hosts whose
+ * child shell carries its own session (OpenCode, Pi) pass no session.
+ * `--kind` is always named: left out, the CLI records `review`.
+ */
+export function verdictCommand(options: {
+  branch: string | null;
+  judge: "verifier" | "reviewer" | null;
+  session?: string | null;
+  token?: string | null;
+}): string {
+  const kind =
+    options.judge === "verifier"
+      ? "<live|unit>"
+      : options.judge === "reviewer"
+        ? "review"
+        : "<live|unit|review>";
+  return [
+    "workit ledger verdict <verified|failed|blocked>",
+    `--kind ${kind}`,
+    `--branch ${options.branch ?? "<branch>"}`,
+    options.session ? `--session ${options.session}` : null,
+    options.token ? `--token=${options.token}` : null,
+    '--how "<what you ran and saw>"',
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
 /** Keep the newest ISSUED_PER_LEAD ids of one lead (and their token hashes); `own` is never pruned. */
 function pruneIssued(dir: string, own: string, tokens: string): void {
   try {