@brainervirus/workit-core 6.0.1 → 7.0.0

package/src/core/policy/derive.ts

@@ -0,0 +1,338 @@
+// S17 slim policy: requirements derived deterministically from the four
+// judgments plus project constraints (design §4.3), and the status of the
+// rules that read the ledger or the plan instead of task evidence.
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { currentBranch } from "../../git/rev";
+import { STRONG_RESULTS, checkVerdicts, readLedger, type ReadRow } from "../../ledger";
+import type { VerificationMode } from "../../autonomy";
+import {
+  requirementId,
+  sha256,
+  type Constraint,
+  type Judgment,
+  type Requirement,
+  type Scope,
+  type TaskRecord,
+} from "../task-contract";
+
+export const RULES = {
+  test: "check:test",
+  self: "verdict:self",
+  nonAuthor: "verdict:non-author",
+  verified: "verdict:verified",
+  product: "decision:product",
+  plan: "plan",
+} as const;
+
+const derived = (spec: Omit<Requirement, "id">): Requirement => ({
+  ...spec,
+  id: requirementId({
+    ruleId: spec.ruleId,
+    scope: spec.scope,
+    satisfaction: spec.satisfaction,
+    before: spec.before,
+    dependentAction: spec.dependentAction,
+  }),
+});
+
+const sorted = (values: string[]) => [...new Set(values)].toSorted();
+const normalizedScope = (scope: Scope): Scope => ({
+  description: scope.description,
+  paths: sorted(scope.paths),
+  exclusions: sorted(scope.exclusions),
+});
+
+/**
+ * | judgment                         | requirement                                  |
+ * | behaviorChange                   | check:test (configured, fresh tree), close   |
+ * | behaviorChange && risk = normal  | verdict:self (default) or verdict:non-author  |
+ * |                                  | (workspace verification: independent), close |
+ * | risk = high                      | verdict:verified (ledger), close             |
+ * | productChoiceOpen                | decision:product, before write               |
+ * | needsPlan or risk = high         | plan (doc ref, soft), before write           |
+ * | always                           | project constraints                          |
+ */
+export function deriveRequirements(
+  judgment: Judgment,
+  scope: Scope,
+  constraints: Constraint[],
+  /** The workspace's user-config verification mode (autonomy.ts). */
+  verification: VerificationMode = "self",
+): Requirement[] {
+  const out: Requirement[] = [];
+  const base = { scope, dependentAction: null };
+  if (judgment.behaviorChange)
+    out.push(
+      derived({
+        ...base,
+        ruleId: RULES.test,
+        dimension: "testing",
+        reason: "Behavior changes: the configured test check must pass on the final tree.",
+        satisfaction: "Run `workit check test` on the final tree.",
+        before: "close",
+        acceptanceAllowed: false,
+      }),
+    );
+  if (judgment.behaviorChange && judgment.riskTier === "normal")
+    out.push(
+      verification === "independent"
+        ? derived({
+            ...base,
+            ruleId: RULES.nonAuthor,
+            dimension: "review",
+            reason:
+              "This workspace requires independent verification: a session that did not author the change records the verdict.",
+            satisfaction:
+              "An independent session records a passing verdict: `workit ledger verdict verified --how <what it exercised>`.",
+            before: "close",
+            acceptanceAllowed: false,
+          })
+        : derived({
+            ...base,
+            ruleId: RULES.self,
+            dimension: "review",
+            reason:
+              "A behavior change needs a recorded verdict; the author's own is allowed and is shown as self-reviewed, never verified.",
+            satisfaction:
+              "After an observed passing `workit check test`, record `workit ledger verdict tests-verified --self --how <what you ran>` (or have a verifier record one).",
+            before: "close",
+            acceptanceAllowed: false,
+          }),
+    );
+  if (judgment.riskTier === "high")
+    out.push(
+      derived({
+        ...base,
+        ruleId: RULES.verified,
+        dimension: "review",
+        reason: "High risk: an independent verifier must exercise the live surface.",
+        satisfaction:
+          "An independent verifier runs the real surface and records `workit ledger verdict verified --kind live --how <what it exercised>`.",
+        before: "close",
+        acceptanceAllowed: false,
+      }),
+    );
+  if (judgment.productChoiceOpen)
+    out.push(
+      derived({
+        ...base,
+        ruleId: RULES.product,
+        dimension: "decisions",
+        reason:
+          "A product or preference choice is open; the user decides it before code is written.",
+        satisfaction:
+          'Ask the user (with your recommendation), then record the answer: `workit ledger decision "<choice>" --why "<reason>"`.',
+        before: "write",
+        acceptanceAllowed: false,
+      }),
+    );
+  if (judgment.needsPlan || judgment.riskTier === "high")
+    out.push(
+      derived({
+        ...base,
+        ruleId: RULES.plan,
+        dimension: "artifacts",
+        reason: judgment.needsPlan
+          ? "The work needs a written plan or spec before implementation."
+          : "High-risk work needs a written plan before implementation.",
+        satisfaction:
+          "Write the plan or spec (e.g. docs/plans/<slug>.md; docs and Markdown writes stay allowed), then record it: `workit policy assess --ref <path>`.",
+        before: "write",
+        acceptanceAllowed: true,
+      }),
+    );
+  for (const constraint of constraints)
+    for (const obligation of constraint.requires)
+      out.push(
+        derived({
+          ruleId: `project-constraint:${constraint.id}:${obligation.kind}:${sha256({
+            kind: obligation.kind,
+            scope: normalizedScope(obligation.scope),
+            refs: obligation.refs.map((ref) => JSON.stringify(ref)).toSorted(),
+            method: obligation.method,
+            before: obligation.before,
+            dependentAction: obligation.dependentAction,
+          })}`,
+          dimension:
+            obligation.method ??
+            (obligation.kind === "check"
+              ? "verification"
+              : obligation.kind === "decision"
+                ? "decisions"
+                : "challenge"),
+          scope: obligation.scope,
+          reason: `${constraint.kind} constraint requires ${obligation.kind}: ${constraint.statement}`,
+          satisfaction: `Satisfy the constraint obligation using its referenced ${obligation.kind}.`,
+          before: obligation.before,
+          dependentAction: obligation.dependentAction,
+          acceptanceAllowed: constraint.acceptanceAllowed && obligation.kind !== "decision",
+        }),
+      );
+  const seen = new Set<string>();
+  return out.filter((item) => (seen.has(item.id) ? false : (seen.add(item.id), true)));
+}
+
+export const latestJudgment = (task: TaskRecord): Judgment | null =>
+  task.judgments?.at(-1)?.data ?? null;
+
+/** Lazily read ledger rows and the checked-out branch, once per evaluation. */
+export type LedgerView = { branch: () => string | null; rows: () => readonly ReadRow[] };
+export const ledgerView = (root: string): LedgerView => {
+  let branch: string | null | undefined;
+  let rows: readonly ReadRow[] | undefined;
+  return {
+    branch: () => (branch === undefined ? (branch = currentBranch(root)) : branch),
+    rows: () => {
+      if (rows === undefined) {
+        const read = readLedger(root);
+        rows = read.ok ? read.value.rows : [];
+      }
+      return rows;
+    },
+  };
+};
+
+export type RuleStatus = { met: boolean; reason: string; decisionIds: string[] };
+
+/** A user decision recorded on the task, or a ledger decision on this branch since the task began. */
+const productDecision = (task: TaskRecord, ledger: LedgerView): RuleStatus => {
+  const decisions = task.decisions.filter(
+    (entry) =>
+      entry.data.revoked === null &&
+      (entry.data.response === "approved" || entry.data.response === "stated") &&
+      entry.data.purpose !== "limitation",
+  );
+  if (decisions.length)
+    return {
+      met: true,
+      reason: "the user's decision is recorded on the task",
+      decisionIds: decisions.map((entry) => entry.id),
+    };
+  const since = Date.parse(task.createdAt);
+  const branch = ledger.branch();
+  // Outside git (no branch) the checkout's own ledger rows carry no branch either.
+  const row = ledger
+    .rows()
+    .findLast(
+      (item) =>
+        item.type === "decision" &&
+        !item.superseded &&
+        (item.branch ?? null) === branch &&
+        Date.parse(item.at) >= since,
+    );
+  return row
+    ? { met: true, reason: `ledger decision ${row.id} records the choice`, decisionIds: [] }
+    : {
+        met: false,
+        reason:
+          'open product choice: ask the user, then `workit ledger decision "<choice>" --why "<reason>"` (or re-judge productChoiceOpen=false if it is not open)',
+        decisionIds: [],
+      };
+};
+
+/** The latest judgment cites an existing doc or a URL, or an artifact passed. */
+const planRecorded = (task: TaskRecord, root: string): RuleStatus => {
+  const cited = (latestJudgment(task)?.refs ?? []).find(
+    (ref) =>
+      ref.kind === "external" || (ref.kind === "file" && existsSync(path.resolve(root, ref.path))),
+  );
+  if (cited)
+    return {
+      met: true,
+      reason: `plan recorded: ${cited.kind === "file" ? cited.path : cited.kind === "external" ? cited.url : ""}`,
+      decisionIds: [],
+    };
+  const artifact = task.evidence.some(
+    (entry) => entry.data.kind === "artifact" && entry.data.result === "passed",
+  );
+  return artifact
+    ? { met: true, reason: "a passing artifact records the plan", decisionIds: [] }
+    : {
+        met: false,
+        reason:
+          "no plan recorded: write it (docs/ and Markdown writes stay allowed), then `workit policy assess --ref <path>`",
+        decisionIds: [],
+      };
+};
+
+/**
+ * Verdict rules over the D18 ledger. `type-check-only` never proves a
+ * behavior change. `verdict:self` takes the author's own current `--self`
+ * verdict (shown as self-reviewed) or an independent one; `verdict:non-author`
+ * an accepted independent one; `verdict:verified` an accepted independent
+ * `verified` verdict of kind `live`.
+ */
+const verdict = (requirement: Requirement, root: string, ledger: LedgerView): RuleStatus => {
+  const branch = ledger.branch();
+  if (!branch)
+    return { met: false, reason: "no branch is checked out to hold a verdict", decisionIds: [] };
+  const check = checkVerdicts(root, branch, ledger.rows());
+  const failing = check.accepted.reasons.includes("failing_verdict");
+  const strong = (entry: (typeof check.verdicts)[number]) =>
+    STRONG_RESULTS.has(String(entry.verdict.result));
+  const met =
+    !failing &&
+    (requirement.ruleId === RULES.verified
+      ? check.verdicts.find(
+          (entry) =>
+            entry.accepted && entry.kind === "live" && String(entry.verdict.result) === "verified",
+        )
+      : requirement.ruleId === RULES.nonAuthor
+        ? check.verdicts.find((entry) => entry.accepted && strong(entry))
+        : check.verdicts.find((entry) => entry.current && strong(entry)));
+  if (met)
+    return {
+      met: true,
+      reason: `${met.accepted ? "accepted independent" : "self-reviewed (author's own)"} ${String(met.verdict.result)} verdict ${met.verdict.id}`,
+      decisionIds: [],
+    };
+  const why = failing
+    ? "a current independent verdict fails"
+    : check.verdicts.some((entry) => entry.current && entry.verdict.result === "type-check-only")
+      ? "type-check-only does not prove a behavior change"
+      : (check.accepted.reasons.join(", ") || "no_verdict").replace(/_/g, " ");
+  const unblock =
+    requirement.ruleId === RULES.self
+      ? "record your own verdict after an observed `workit check test`: `workit ledger verdict tests-verified --self --how <what you ran>` (shown as self-reviewed), or have a verifier record one"
+      : `an independent session records \`workit ledger verdict verified${requirement.ruleId === RULES.verified ? " --kind live" : ""} --how <what it exercised>\``;
+  return { met: false, reason: `${why}: ${unblock}`, decisionIds: [] };
+};
+
+/** Status of a derived rule that is not decided by task evidence; null for every other rule. */
+export function derivedRuleStatus(
+  task: TaskRecord,
+  requirement: Requirement,
+  root: string,
+  ledger: LedgerView,
+): RuleStatus | null {
+  switch (requirement.ruleId) {
+    case RULES.product:
+      return productDecision(task, ledger);
+    case RULES.plan:
+      return planRecorded(task, root);
+    case RULES.self:
+    case RULES.nonAuthor:
+    case RULES.verified:
+      return verdict(requirement, root, ledger);
+    default:
+      return null;
+  }
+}
+
+export type WriteBlocker = { ruleId: string; reason: string };
+
+/**
+ * Unmet before-write requirements of a task (S17 write gate). Only derived
+ * rules are decided here, cheaply and without capturing a candidate;
+ * constraint write obligations stay advisory.
+ */
+export function writeBlockers(task: TaskRecord, root: string): WriteBlocker[] {
+  if (task.status === "closed" || !task.policy) return [];
+  const ledger = ledgerView(root);
+  return task.policy.requirements.flatMap((requirement) => {
+    if (requirement.before !== "write") return [];
+    const status = derivedRuleStatus(task, requirement, root, ledger);
+    return status && !status.met ? [{ ruleId: requirement.ruleId, reason: status.reason }] : [];
+  });
+}

package/src/core/policy/judgment.ts

@@ -0,0 +1,192 @@
+// The agent's policy judgment as sent: four flat calls with aliases, or a
+// ≤6.x assessment (facts/signals/…), mapped leniently for one major (D17).
+import { refOf } from "../operation-input";
+import {
+  failure,
+  judgmentSchema,
+  success,
+  type Judgment,
+  type Result,
+  type RiskTier,
+} from "../task-contract";
+
+type Json = Record<string, unknown>;
+const isObject = (value: unknown): value is Json =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Keys compared without case, `_` or `-`: `needs_plan`, `Needs-Plan` → `needsplan`. */
+const squash = (key: string) => key.toLowerCase().replace(/[_-]/g, "");
+const ALIASES: Record<keyof Omit<Judgment, "refs" | "note"> | "note" | "refs", string[]> = {
+  riskTier: ["risktier", "risk", "risklevel", "tier"],
+  behaviorChange: ["behaviorchange", "behavior", "behaviour", "behaviourchange"],
+  productChoiceOpen: ["productchoiceopen", "openproductchoice", "productchoice", "openchoice"],
+  needsPlan: ["needsplan", "plan", "needsspec", "spec"],
+  note: ["note", "notes", "reason", "why"],
+  refs: ["refs", "ref", "references"],
+};
+const LEGACY_KEYS = new Set(["assessment", "facts", "signals", "consequences", "verification"]);
+
+const RISK: Record<string, RiskTier> = {
+  trivial: "trivial",
+  low: "trivial",
+  minor: "trivial",
+  mechanical: "trivial",
+  none: "trivial",
+  normal: "normal",
+  medium: "normal",
+  med: "normal",
+  moderate: "normal",
+  high: "high",
+  critical: "high",
+  major: "high",
+};
+const YES = new Set(["true", "yes", "y", "1", "on"]);
+const NO = new Set(["false", "no", "n", "0", "off", "none"]);
+
+type Field = { ok: true; value: boolean } | { ok: false };
+const flag = (value: unknown, unknownAs: boolean): Field => {
+  if (typeof value === "boolean") return { ok: true, value };
+  if (typeof value === "number" && (value === 0 || value === 1))
+    return { ok: true, value: value === 1 };
+  if (typeof value !== "string") return { ok: false };
+  const text = value.trim().toLowerCase();
+  if (YES.has(text)) return { ok: true, value: true };
+  if (NO.has(text)) return { ok: true, value: false };
+  if (text === "unknown" || text === "maybe") return { ok: true, value: unknownAs };
+  return { ok: false };
+};
+
+/**
+ * A ≤6.x assessment's signals mapped onto the four judgments, conservatively:
+ * risk is capped at normal and is high only where the 6.x resolver itself
+ * demanded fresh-context review (an explicit behavior change with a
+ * security, data, public-contract or operations consequence). An `unknown`
+ * signal keeps the previous judgment (else false).
+ */
+const fromLegacy = (raw: Json, previous: Judgment | null): Partial<Judgment> => {
+  const source = isObject(raw.assessment) ? raw.assessment : raw;
+  const signals = isObject(source.signals) ? source.signals : {};
+  const value = (name: string): unknown =>
+    isObject(signals[name]) ? signals[name].value : undefined;
+  const known = (name: string, fallback: boolean): boolean =>
+    typeof value(name) === "boolean" ? (value(name) as boolean) : fallback;
+  const behaviorChange = known("behaviorChange", previous?.behaviorChange ?? false);
+  const consequences = Array.isArray(source.consequences) ? source.consequences : [];
+  const freshReview =
+    value("behaviorChange") === true &&
+    consequences.some(
+      (item) =>
+        isObject(item) &&
+        ["security", "data", "public_contract", "operations"].includes(String(item.area)),
+    );
+  return {
+    riskTier: freshReview
+      ? "high"
+      : value("mechanicalLowRisk") === true && !behaviorChange
+        ? "trivial"
+        : "normal",
+    behaviorChange,
+    productChoiceOpen: known("productChoiceOpen", previous?.productChoiceOpen ?? false),
+    needsPlan:
+      known("durableAgreementNeeded", previous?.needsPlan ?? false) ||
+      value("coordinationPlanNeeded") === true,
+  };
+};
+
+const DEFAULT: Judgment = {
+  riskTier: "normal",
+  behaviorChange: false,
+  productChoiceOpen: false,
+  needsPlan: false,
+  note: null,
+  refs: [],
+};
+
+export type NormalizedJudgment = { judgment: Judgment; ignored: string[]; legacy: boolean };
+
+/**
+ * Map a judgment as sent onto the stored shape. Omitted judgments keep the
+ * `previous` values and refs accumulate (a re-assessment can add only a plan ref), else the
+ * defaults (normal risk, no behavior change, no open choice, no plan). A
+ * ≤6.x assessment maps what it can and ignores the rest. Only an
+ * unrecognizable value for a known judgment is invalid input.
+ */
+export function normalizeJudgment(
+  raw: unknown,
+  previous: Judgment | null,
+): Result<NormalizedJudgment> {
+  const input = isObject(raw) ? raw : {};
+  const legacy = Object.keys(input).some((key) => LEGACY_KEYS.has(key));
+  // Refs accumulate across re-assessments; a new note replaces the old one.
+  const base: Judgment = { ...DEFAULT, ...previous, refs: [...(previous?.refs ?? [])] };
+  const judgment: Judgment = legacy ? { ...base, ...fromLegacy(input, previous) } : { ...base };
+  const ignored: string[] = [];
+  const fields: { path: string; reason: string }[] = [];
+  for (const [key, value] of Object.entries(input)) {
+    if (LEGACY_KEYS.has(key)) continue;
+    const name = (Object.keys(ALIASES) as (keyof typeof ALIASES)[]).find((field) =>
+      ALIASES[field].includes(squash(key)),
+    );
+    if (!name) {
+      ignored.push(key);
+      continue;
+    }
+    if (name === "riskTier") {
+      const tier = typeof value === "string" ? RISK[value.trim().toLowerCase()] : undefined;
+      if (tier) judgment.riskTier = tier;
+      else fields.push({ path: key, reason: "expected trivial|normal|high (or low|medium)" });
+    } else if (name === "note") {
+      judgment.note = typeof value === "string" && value.trim() ? value.trim() : null;
+    } else if (name === "refs") {
+      const items = Array.isArray(value) ? value : [value];
+      judgment.refs.push(
+        ...(items.filter((item) => item !== null && item !== "").map(refOf) as Judgment["refs"]),
+      );
+    } else {
+      // `plan: docs/plans/x.md` both flags the plan and names it.
+      if (
+        name === "needsPlan" &&
+        typeof value === "string" &&
+        !flag(value, false).ok &&
+        value.trim()
+      ) {
+        judgment.needsPlan = true;
+        judgment.refs.push(refOf(value.trim()) as Judgment["refs"][number]);
+        continue;
+      }
+      const parsed = flag(value, name === "behaviorChange");
+      if (parsed.ok) judgment[name] = parsed.value;
+      else fields.push({ path: key, reason: "expected true|false (yes|no accepted)" });
+    }
+  }
+  if (fields.length) return failure("invalid_input", "judgment values are invalid", { fields });
+  const seen = new Set<string>();
+  judgment.refs = judgment.refs.filter((ref) => {
+    const key = JSON.stringify(ref);
+    return seen.has(key) ? false : (seen.add(key), true);
+  });
+  const parsed = judgmentSchema.safeParse(judgment);
+  if (!parsed.success)
+    return failure("invalid_input", "judgment is invalid", {
+      fields: parsed.error.issues.map((issue) => ({
+        path: issue.path.join("."),
+        reason: issue.message,
+      })),
+    });
+  return success(null, null, { judgment: parsed.data, ignored, legacy });
+}
+
+/** Parse `key=value` tokens (`workit policy assess --judge behavior=yes risk=normal`). */
+export const judgeTokens = (tokens: string[]): Json => {
+  const out: Json = {};
+  for (const token of tokens) {
+    const at = token.indexOf("=");
+    const key = at < 0 ? token : token.slice(0, at);
+    const value = at < 0 ? "true" : token.slice(at + 1);
+    if (!key) continue;
+    if (ALIASES.refs.includes(squash(key)))
+      out.refs = [...(Array.isArray(out.refs) ? out.refs : []), value];
+    else out[key] = value;
+  }
+  return out;
+};