@deftai/directive-core 0.89.0 → 0.91.0

package/dist/tool-events/summarize.js

@@ -0,0 +1,93 @@
+/**
+ * Aggregate tool-event classifications into counts, anomalies, and status lines (#2967).
+ * Pure: no I/O.
+ */
+import { classifyToolEvent } from "./classify.js";
+import { TOOL_EVENT_BUCKETS, } from "./types.js";
+export function emptyBucketCounts() {
+    return {
+        explore: 0,
+        commit: 0,
+        verify: 0,
+        coordinate: 0,
+        unknown: 0,
+    };
+}
+/** Count classified buckets for a sequence of tool events. */
+export function countToolEventBuckets(events) {
+    const counts = {
+        explore: 0,
+        commit: 0,
+        verify: 0,
+        coordinate: 0,
+        unknown: 0,
+    };
+    for (const event of events) {
+        const { bucket } = classifyToolEvent(event);
+        counts[bucket] += 1;
+    }
+    return counts;
+}
+/**
+ * Detect operator-facing anomalies from bucket counts.
+ *
+ * Rules (conservative — only fire when the mix is clearly wrong):
+ * - commit-without-explore: commit > 0 and explore === 0
+ * - verify-skipped: commit > 0 and verify === 0 (ship without gates)
+ * - explore-only: explore > 0, commit === 0, verify === 0, and total >= 3
+ *   (thrash / stuck-reading signal; small explore-only sessions stay quiet)
+ */
+export function detectToolEventAnomalies(counts) {
+    const anomalies = [];
+    const total = counts.explore + counts.commit + counts.verify + counts.coordinate + counts.unknown;
+    if (counts.commit > 0 && counts.explore === 0) {
+        anomalies.push({
+            code: "commit-without-explore",
+            message: `commit-without-explore: ${counts.commit} commit event(s) with 0 explore`,
+        });
+    }
+    if (counts.commit > 0 && counts.verify === 0) {
+        anomalies.push({
+            code: "verify-skipped",
+            message: `verify-skipped: ${counts.commit} commit event(s) with 0 verify`,
+        });
+    }
+    if (counts.explore > 0 && counts.commit === 0 && counts.verify === 0 && total >= 3) {
+        anomalies.push({
+            code: "explore-only",
+            message: `explore-only: ${counts.explore} explore event(s) with 0 commit and 0 verify (possible thrash)`,
+        });
+    }
+    return anomalies;
+}
+/**
+ * Compact status line for swarm monitor / review-cycle batch brief.
+ * Example: `tools: explore=3 commit=2 verify=1 coordinate=0 unknown=0`
+ */
+export function formatToolEventStatusLine(counts) {
+    const parts = TOOL_EVENT_BUCKETS.map((b) => `${b}=${counts[b]}`);
+    return `tools: ${parts.join(" ")}`;
+}
+/**
+ * One-line anomaly suffix for status surfaces.
+ * Empty string when no anomalies.
+ */
+export function formatToolEventAnomalyLine(anomalies) {
+    if (anomalies.length === 0)
+        return "";
+    return `anomalies: ${anomalies.map((a) => a.code).join(",")}`;
+}
+/**
+ * Full summary for a tool-event sequence — counts, anomalies, status line.
+ * When anomalies exist, statusLine appends `| anomalies: …`.
+ */
+export function summarizeToolEvents(events) {
+    const counts = countToolEventBuckets(events);
+    const anomalies = detectToolEventAnomalies(counts);
+    const total = counts.explore + counts.commit + counts.verify + counts.coordinate + counts.unknown;
+    const base = formatToolEventStatusLine(counts);
+    const anomalyLine = formatToolEventAnomalyLine(anomalies);
+    const statusLine = anomalyLine.length > 0 ? `${base} | ${anomalyLine}` : base;
+    return { total, counts, anomalies, statusLine };
+}
+//# sourceMappingURL=summarize.js.map

package/dist/tool-events/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool-event taxonomy types for explore/commit/verify classification (#2967).
+ * Pure types only — no I/O.
+ */
+/** Deterministic activity buckets for swarm/review operator skim. */
+export type ToolEventBucket = "explore" | "commit" | "verify" | "coordinate" | "unknown";
+/** All buckets in stable report order (unknown last). */
+export declare const TOOL_EVENT_BUCKETS: readonly ToolEventBucket[];
+/**
+ * Minimal tool-event input. Prefer tool name + coarse args; never require
+ * full host payloads. Shell tools should pass `command` when known.
+ */
+export interface ToolEventInput {
+    /** Host tool name (e.g. `Read`, `Shell`, `Write`, `Task`). */
+    readonly name: string;
+    /**
+     * Coarse args bag — common keys: `command`, `cmd`, `path`, `file_path`,
+     * `query`, `pattern`. Values may be strings or other JSON-ish primitives.
+     */
+    readonly args?: Readonly<Record<string, unknown>> | null;
+    /**
+     * Explicit shell/command string when not nested under `args`.
+     * Wins over `args.command` / `args.cmd` when both are set.
+     */
+    readonly command?: string | null;
+}
+/** Result of classifying one tool event. */
+export interface ClassifyToolEventResult {
+    readonly bucket: ToolEventBucket;
+    /** Stable machine-oriented reason code for tests and debug. */
+    readonly reason: string;
+}
+/** Per-bucket event counts (always includes every bucket key). */
+export type ToolEventBucketCounts = Readonly<Record<ToolEventBucket, number>>;
+/**
+ * Operator-facing anomaly codes derived from a sequence of classified events.
+ * Detection is conservative: only fire when the mix is clearly wrong.
+ */
+export type ToolEventAnomalyCode = "commit-without-explore" | "verify-skipped" | "explore-only";
+export interface ToolEventAnomaly {
+    readonly code: ToolEventAnomalyCode;
+    readonly message: string;
+}
+/** Aggregate summary for monitor status lines and batch briefs. */
+export interface ToolEventSummary {
+    readonly total: number;
+    readonly counts: ToolEventBucketCounts;
+    readonly anomalies: readonly ToolEventAnomaly[];
+    /** Compact one-liner: `tools: explore=3 commit=2 verify=1 coordinate=0 unknown=0`. */
+    readonly statusLine: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tool-events/types.js

@@ -0,0 +1,13 @@
+/**
+ * Tool-event taxonomy types for explore/commit/verify classification (#2967).
+ * Pure types only — no I/O.
+ */
+/** All buckets in stable report order (unknown last). */
+export const TOOL_EVENT_BUCKETS = [
+    "explore",
+    "commit",
+    "verify",
+    "coordinate",
+    "unknown",
+];
+//# sourceMappingURL=types.js.map

package/dist/triage/welcome/index.d.ts

@@ -3,5 +3,5 @@ export { type DefaultModeOptions, formatWelcomeCommand, normalizeTaskPrefix, run
 export { DEFAULT_ONBOARD_PRESET, type OnboardOptions, type OnboardOutcome, runOnboardMode, } from "./onboard.js";
 export { candidatesLogPath, classifyOnboarding, detectPriorState, type PriorState, pendingDecisionsNudgeLine, } from "./prior-state.js";
 export { computeSummary, emitOneliner, formatOneLiner, formatSummary, type SummaryResult, } from "./summary.js";
-export { appendAuditEntry, previewWipRelief, type ReliefPreview, subscriptionPreset, writeTriageScope, writeWipCap, } from "./writers.js";
+export { appendAuditEntry, previewWipRelief, type ReliefPreview, subscriptionPreset, writeTriageScope, writeWipCap, writeWipCapDecision, } from "./writers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/triage/welcome/index.js

@@ -3,5 +3,5 @@ export { formatWelcomeCommand, normalizeTaskPrefix, runDefaultMode, } from "./de
 export { DEFAULT_ONBOARD_PRESET, runOnboardMode, } from "./onboard.js";
 export { candidatesLogPath, classifyOnboarding, detectPriorState, pendingDecisionsNudgeLine, } from "./prior-state.js";
 export { computeSummary, emitOneliner, formatOneLiner, formatSummary, } from "./summary.js";
-export { appendAuditEntry, previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap, } from "./writers.js";
+export { appendAuditEntry, previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap, writeWipCapDecision, } from "./writers.js";
 //# sourceMappingURL=index.js.map

package/dist/triage/welcome/onboard.js

@@ -7,7 +7,7 @@ import { DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, TRIAGE_SKILL_PATH } from "./cons
 import { formatWelcomeCommand } from "./default-mode.js";
 import { detectPriorState } from "./prior-state.js";
 import { emitOneliner } from "./summary.js";
-import { previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap } from "./writers.js";
+import { previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap, writeWipCapDecision, } from "./writers.js";
 /** Default triage-scope preset applied when `--onboard` is run without `--preset`. */
 export const DEFAULT_ONBOARD_PRESET = "small";
 function failure(exitCode) {
@@ -66,8 +66,14 @@ export function runOnboardMode(projectRoot, options = {}) {
     const [triageScopeChanged] = writeTriageScope(projectRoot, rules, { presetLabel: preset });
     let wipCapChanged = false;
     if (wipCap !== null) {
+        // writeWipCap also records out-of-band decision-provenance (#1694).
         [wipCapChanged] = writeWipCap(projectRoot, wipCap);
     }
+    else {
+        // Accepting the framework default is a real onboarding decision: record it
+        // without materializing plan.policy.wipCap (#1694 / #1186 D1 / #1250).
+        writeWipCapDecision(projectRoot, { acceptedDefault: true });
+    }
     emitOneliner(projectRoot, {
         writeHistory: options.writeHistory !== false,
         now: options.now,

package/dist/triage/welcome/prior-state.d.ts

@@ -3,7 +3,14 @@ export interface PriorState {
     readonly triageScopeSummary: string;
     readonly cacheEmpty: boolean;
     readonly cacheEntryCount: number;
+    /** True when plan.policy.wipCap is materialized (deliberate non-default override). */
     readonly wipCapSet: boolean;
+    /**
+     * True when an out-of-band decision-provenance marker records that the
+     * operator considered WIP cap (#1694). Orthogonal to {@link wipCapSet}:
+     * accepting the framework default sets this without materializing the field.
+     */
+    readonly wipCapDecided: boolean;
     readonly wipCap: number;
     readonly wipCount: number;
     readonly auditLogPresent: boolean;

package/dist/triage/welcome/prior-state.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveAuditPath, resolveLifecycleRoot, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
-import { readPlanPolicy } from "../../policy/plan-extensions.js";
+import { readPlanOnboarding, readPlanPolicy } from "../../policy/plan-extensions.js";
 import { resolveCandidatesLogPath } from "../cache-path.js";
 import { CACHE_DIR_NAME, CACHE_SOURCE, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WIP_LIFECYCLE_DIRS, } from "./constants.js";
 function loadProjectDefinition(projectRoot) {
@@ -152,6 +152,17 @@ export function detectPriorState(projectRoot) {
             wipCapSet = true;
         }
     }
+    // Decision-provenance is out-of-band from the value field (#1694 / #1695).
+    // Accepting the framework default records wipCapDecided without materializing
+    // plan.policy.wipCap. A materialized override also counts as a decision.
+    const onboarding = readPlanOnboarding(plan);
+    let wipCapDecided = false;
+    if (typeof onboarding === "object" && onboarding !== null && !Array.isArray(onboarding)) {
+        wipCapDecided = onboarding.wipCapDecided === true;
+    }
+    if (wipCapSet) {
+        wipCapDecided = true;
+    }
     const [scopeSet, scopeLabel] = summarizeScope(scopeRules);
     const cacheCount = countCacheEntries(projectRoot);
     return {
@@ -160,6 +171,7 @@ export function detectPriorState(projectRoot) {
         cacheEmpty: cacheCount === 0,
         cacheEntryCount: cacheCount,
         wipCapSet,
+        wipCapDecided,
         wipCap,
         wipCount: countWip(projectRoot),
         auditLogPresent: existsSync(candidatesLogPath(projectRoot)),
@@ -167,10 +179,12 @@ export function detectPriorState(projectRoot) {
     };
 }
 export function classifyOnboarding(state) {
+    // wipCap onboarding completeness is decision-provenance, not field presence
+    // (#1694). Omission of plan.policy.wipCap with wipCapDecided=true is fully set up.
     const signals = {
         "candidates.jsonl": state.auditLogPresent,
         triageScope: state.triageScopeSet,
-        wipCap: state.wipCapSet,
+        wipCap: state.wipCapDecided,
     };
     const present = Object.keys(signals).filter((k) => signals[k]);
     const missing = Object.keys(signals).filter((k) => !signals[k]);

package/dist/triage/welcome/writers.d.ts

@@ -3,6 +3,16 @@ export declare function writeTriageScope(projectRoot: string, rules: Array<Recor
     presetLabel: string;
     actor?: string;
 }): [boolean, string];
+/**
+ * Record out-of-band WIP-cap decision provenance without materializing
+ * `plan.policy.wipCap` (#1694). Accepting the framework default is a real
+ * onboarding decision and MUST be representable without writing the value field.
+ */
+export declare function writeWipCapDecision(projectRoot: string, options?: {
+    actor?: string;
+    acceptedDefault?: boolean;
+    value?: number | null;
+}): [boolean, string];
 export declare function writeWipCap(projectRoot: string, wipCap: number, options?: {
     actor?: string;
 }): [boolean, string];

package/dist/triage/welcome/writers.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, s
 import { dirname, join, resolve } from "node:path";
 import { containedWrite } from "../../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
-import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
+import { migrateLegacyPolicyKey, PLAN_ONBOARDING_KEY, PLAN_POLICY_KEY, } from "../../policy/plan-extensions.js";
 import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 import { AUDIT_LOG_REL_PATH, DEFAULT_RELIEF_AGE_DAYS, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WELCOME_AUDIT_TAG, } from "./constants.js";
 function projectDefinitionPath(projectRoot) {
@@ -97,6 +97,57 @@ export function writeTriageScope(projectRoot, rules, options = { presetLabel: "c
         return [changed, auditEntry];
     });
 }
+/**
+ * Record out-of-band WIP-cap decision provenance without materializing
+ * `plan.policy.wipCap` (#1694). Accepting the framework default is a real
+ * onboarding decision and MUST be representable without writing the value field.
+ */
+export function writeWipCapDecision(projectRoot, options = {}) {
+    return projectDefinitionMutationLock(projectRoot, () => {
+        const path = projectDefinitionPath(projectRoot);
+        if (!existsSync(path))
+            throw new Error(`PROJECT-DEFINITION not found at ${path}`);
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+        }
+        const data = parsed;
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+        }
+        const planRec = plan;
+        const previous = planRec[PLAN_ONBOARDING_KEY];
+        const previousRec = typeof previous === "object" && previous !== null && !Array.isArray(previous)
+            ? previous
+            : {};
+        const alreadyDecided = previousRec.wipCapDecided === true;
+        const acceptedDefault = options.acceptedDefault ?? true;
+        const actor = options.actor ?? WELCOME_AUDIT_TAG;
+        // Rebuild cleanly so acceptedDefault=true never retains a prior custom value.
+        const next = {
+            wipCapDecided: true,
+            acceptedDefault,
+            decidedAt: utcIso(),
+            actor,
+        };
+        if (!acceptedDefault && options.value !== undefined && options.value !== null) {
+            next.value = options.value;
+        }
+        planRec[PLAN_ONBOARDING_KEY] = next;
+        atomicWrite(projectRoot, path, data);
+        const changed = !alreadyDecided || previousRec.acceptedDefault !== acceptedDefault;
+        const auditEntry = [
+            `actor=${actor}`,
+            `field=${PLAN_ONBOARDING_KEY}.wipCapDecided`,
+            "value=true",
+            `acceptedDefault=${acceptedDefault ? "true" : "false"}`,
+            `changed=${changed ? "true" : "false"}`,
+        ].join(" ");
+        appendAuditEntry(projectRoot, auditEntry);
+        return [changed, auditEntry];
+    });
+}
 export function writeWipCap(projectRoot, wipCap, options = {}) {
     if (!Number.isInteger(wipCap) || wipCap < 1) {
         throw new Error(`wipCap must be a positive int, got ${JSON.stringify(wipCap)}`);
@@ -125,8 +176,27 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         const policyRec = policy;
         const previous = policyRec.wipCap;
         const actor = options.actor ?? WELCOME_AUDIT_TAG;
+        // Always record decision-provenance out-of-band (#1694). Accepting the
+        // default omits the value field but still marks the decision complete.
+        // Rebuild the onboarding record (do not spread a prior custom `value` into
+        // an acceptedDefault=true payload -- that is contradictory provenance).
+        const acceptedDefault = wipCap === DEFAULT_WIP_CAP;
+        const onboardingRecord = {
+            wipCapDecided: true,
+            acceptedDefault,
+            decidedAt: utcIso(),
+            actor,
+        };
+        if (!acceptedDefault) {
+            onboardingRecord.value = wipCap;
+        }
+        planRec[PLAN_ONBOARDING_KEY] = onboardingRecord;
         if (previous === undefined && wipCap === DEFAULT_WIP_CAP) {
-            return [false, ""];
+            atomicWrite(projectRoot, path, data);
+            const auditEntry = `actor=${actor} field=${PLAN_ONBOARDING_KEY}.wipCapDecided value=true ` +
+                `acceptedDefault=true changed=true note=default-no-materialize`;
+            appendAuditEntry(projectRoot, auditEntry);
+            return [true, auditEntry];
         }
         if (previous !== undefined && wipCap === DEFAULT_WIP_CAP) {
             delete policyRec.wipCap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.89.0",
+  "version": "0.91.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -263,6 +263,10 @@
       "types": "./dist/swarm/index.d.ts",
       "default": "./dist/swarm/index.js"
     },
+    "./tool-events": {
+      "types": "./dist/tool-events/index.d.ts",
+      "default": "./dist/tool-events/index.js"
+    },
     "./review-monitor": {
       "types": "./dist/review-monitor/index.d.ts",
       "default": "./dist/review-monitor/index.js"
@@ -330,8 +334,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.89.0",
-    "@deftai/directive-types": "^0.89.0",
+    "@deftai/directive-content": "^0.91.0",
+    "@deftai/directive-types": "^0.91.0",
     "archiver": "^8.0.0"
   },
   "scripts": {