create-principles-disciple 1.144.27 → 1.145.1

package/workbuddy-adapter/dist/workbuddy-evidence-recorder.js

@@ -0,0 +1,238 @@
+/**
+ * WorkBuddy Evidence Recorder — the WorkBuddy source adapter for the PD v2
+ * evidence ledger (ADR-0027; SPEC workbuddy-host-adapter §4.6). Ports the
+ * codex-adapter recorder pattern onto the frozen
+ * `workbuddy_pd_hook_event_log` source kind with WorkBuddy's PROBE-VERIFIED
+ * honesty boundaries:
+ *
+ * - agent_context_delivery: supported, max confirmation 'submitted' — the
+ *   UserPromptSubmit additionalContext channel was verified in model-visible
+ *   context by probe P04, but the adapter proves only submission on stdout;
+ * - enforcement_delivery: supported, max confirmation 'runtime_loaded' —
+ *   probe P02 VERIFIED a deny permissionDecision actually blocks the tool
+ *   (target file not written), so unlike Codex (suspended, PRI-780) this
+ *   host can honestly claim runtime enforcement for v1 live rules;
+ * - application_self_report: unsupported — no self-report capture channel;
+ * - v2 rule context: like Codex, WorkBuddy supplies NO runtime context
+ *   provider, so v2 rules stay suspended (rule_context_v2_unavailable);
+ *   nothing here claims v2 enforcement.
+ *
+ * All writes flow through the shared host-runtime ingress (SPEC §13.7 single
+ * entry). Best-effort: degradation produces a bounded stderr diagnostic and
+ * never changes an already computed tool decision (P02: an already-encoded
+ * deny must survive evidence failure).
+ */
+import { getInterventionEvidenceIngress } from '@principles/host-runtime';
+/** Evidence adapter surface version (matches the frozen core contract test expectations). */
+export const WORKBUDDY_EVIDENCE_ADAPTER_VERSION = 'workbuddy-adapter@0.1.0';
+export function workbuddyCapabilityDeclarations() {
+    return [
+        {
+            hostKind: 'workbuddy', capability: 'agent_context_delivery', status: 'supported',
+            adapterVersion: WORKBUDDY_EVIDENCE_ADAPTER_VERSION, channel: 'pd-hook:UserPromptSubmit',
+            maxConfirmation: 'submitted',
+            note: 'P04 probe: additionalContext verified in model-visible context as a hook system-reminder; stdout submission is the proof boundary',
+        },
+        {
+            hostKind: 'workbuddy', capability: 'enforcement_delivery', status: 'supported',
+            adapterVersion: WORKBUDDY_EVIDENCE_ADAPTER_VERSION, channel: 'code_tool_hook',
+            maxConfirmation: 'runtime_loaded',
+            note: 'P02 probe: PreToolUse deny verified to block tool execution (target file not written); v2 rules stay suspended (no context provider)',
+        },
+        {
+            hostKind: 'workbuddy', capability: 'application_self_report', status: 'unsupported',
+            adapterVersion: WORKBUDDY_EVIDENCE_ADAPTER_VERSION, channel: 'pd-hook',
+            note: 'no self-report capture channel exists on the WorkBuddy host; nothing is claimed',
+        },
+        {
+            hostKind: 'workbuddy', capability: 'behavior_observation', status: 'unknown',
+            adapterVersion: WORKBUDDY_EVIDENCE_ADAPTER_VERSION, channel: 'pd-hook:PostToolUse',
+            note: 'tool episodes are recorded through the shared pain path; no automated outcome source exists yet',
+        },
+        {
+            hostKind: 'workbuddy', capability: 'outcome_observation', status: 'unknown',
+            adapterVersion: WORKBUDDY_EVIDENCE_ADAPTER_VERSION, channel: 'console',
+            note: 'no automated outcome source; outcomes enter via Owner console input only',
+        },
+    ];
+}
+function appendWorkbuddyBatch(workspaceDir, observations, warn) {
+    if (observations.length === 0)
+        return;
+    const ingress = getInterventionEvidenceIngress();
+    const batch = {
+        evidenceScopeId: ingress.evidenceScopeIdFor(workspaceDir),
+        sourceKind: 'workbuddy_pd_hook_event_log',
+        adapterVersion: WORKBUDDY_EVIDENCE_ADAPTER_VERSION,
+        recordedAt: new Date().toISOString(),
+        observations,
+        capabilityDeclarations: workbuddyCapabilityDeclarations(),
+    };
+    const result = ingress.appendObservationBatch({ workspaceDir, batch });
+    if (!result.ok) {
+        warn(`[PD:Evidence] workbuddy append degraded: ${result.reason ?? 'unknown'}; next: ${result.nextAction ?? 'replay from durable source'}`);
+    }
+}
+/**
+ * Record one agent-context delivery attempt per injected principle after the
+ * raw injected-event line has been appended to the durable WorkBuddy event
+ * log — confirmation 'submitted', outcome 'attempted' (submitted ≠ delivered,
+ * SPEC §4.6).
+ */
+export function recordWorkbuddyPromptDeliveryEvidence(input) {
+    if (!input.evidenceEnabled || input.injected.length === 0)
+        return;
+    const ingress = getInterventionEvidenceIngress();
+    const observations = [];
+    for (const entry of input.injected) {
+        const observationKey = `workbuddy|delivery|agent_context|${input.sessionId}|${input.turnId ?? '-'}|${entry.activationId}`;
+        const sourceLocator = `workbuddy-pd-hook-event-log:${input.sessionId}`;
+        const existing = ingress.existingObservationRefs(input.workspaceDir, {
+            sourceKind: 'workbuddy_pd_hook_event_log', sourceLocator, observationKey,
+            principleId: entry.principleId, activationId: entry.activationId, ...(entry.artifactId ? { artifactId: entry.artifactId } : {}),
+        });
+        const activationRef = existing?.activationRef ?? ingress.resolveActivationOccurrenceRef(input.workspaceDir, entry.activationId);
+        if (!activationRef) {
+            input.warn(`[PD:Evidence] workbuddy prompt delivery skipped for activation ${entry.activationId}: occurrence snapshot unresolvable`);
+            continue;
+        }
+        if (entry.artifactId !== undefined && activationRef.artifactId !== entry.artifactId) {
+            input.warn(`[PD:Evidence] workbuddy prompt delivery skipped for activation ${entry.activationId}: source artifact does not match occurrence`);
+            continue;
+        }
+        const contentRef = existing?.contentRef ?? ingress.resolveInterventionContentRef(input.workspaceDir, activationRef, entry.principleId);
+        observations.push({
+            observationKey,
+            sourceLocator,
+            kind: 'delivery',
+            nativeRefs: {
+                hostKind: 'workbuddy',
+                sessionId: input.sessionId,
+                ...(input.turnId ? { turnId: input.turnId } : {}),
+            },
+            principleId: entry.principleId,
+            contentRef: {
+                principleId: entry.principleId,
+                ...(activationRef.artifactId ? { artifactId: activationRef.artifactId } : {}),
+                ...(contentRef?.payloadDigest ? { payloadDigest: contentRef.payloadDigest } : {}),
+                // A stored contentRef is an OBJECT — its truthiness must not upgrade
+                // resolution: only a digest-carrying reference counts as resolved.
+                resolution: contentRef?.payloadDigest !== undefined ? 'resolved' : 'revision_reference_unresolved',
+            },
+            activationRef,
+            payload: { targetKind: 'agent_context', confirmation: 'submitted', outcome: 'attempted' },
+        });
+    }
+    appendWorkbuddyBatch(input.workspaceDir, observations, input.warn);
+}
+/**
+ * Record the enforcement chain for an ATTRIBUTED deny that was successfully
+ * encoded to the WorkBuddy stdout channel. The proof boundary is the encoded
+ * permissionDecision (probe P02 verified the host honors it by blocking the
+ * tool) — PD claims exactly that, nothing broader.
+ *
+ * Episode identity requires the per-call toolCallId (WorkBuddy call_id).
+ * Without it the chain is skipped: a hash fallback would mint an episode
+ * with NO native event key, which the normalizer rejects and drops the
+ * whole batch.
+ */
+export function recordWorkbuddyDenyEvidence(input) {
+    if (!input.activationId || !input.principleId)
+        return;
+    if (!input.toolCallId) {
+        input.warn('[PD:Evidence] workbuddy deny chain skipped: no toolCallId — episode identity would lack a native event key');
+        return;
+    }
+    if (!input.evidenceEnabled)
+        return;
+    const ingress = getInterventionEvidenceIngress();
+    const toolKey = input.toolCallId;
+    const sessionPart = input.sessionId ?? '-';
+    const deliveryKey = `workbuddy|delivery|enforcement|${sessionPart}|${toolKey}|${input.activationId}`;
+    const sourceLocator = `workbuddy-pd-hook-event-log:${sessionPart}`;
+    const existing = ingress.existingObservationRefs(input.workspaceDir, {
+        sourceKind: 'workbuddy_pd_hook_event_log', sourceLocator, observationKey: deliveryKey,
+        principleId: input.principleId, activationId: input.activationId,
+    });
+    const activationRef = existing?.activationRef ?? ingress.resolveActivationOccurrenceRef(input.workspaceDir, input.activationId);
+    if (!activationRef) {
+        input.warn(`[PD:Evidence] workbuddy deny chain skipped for activation ${input.activationId}: occurrence snapshot unresolvable`);
+        return;
+    }
+    const episodeKey = `workbuddy|episode|${sessionPart}|${toolKey}`;
+    const content = existing?.contentRef ?? ingress.resolveInterventionContentRef(input.workspaceDir, activationRef, input.principleId);
+    const contentRef = {
+        principleId: input.principleId,
+        ...(activationRef.artifactId ? { artifactId: activationRef.artifactId } : {}),
+        ...(content?.payloadDigest ? { payloadDigest: content.payloadDigest } : {}),
+        resolution: content?.payloadDigest !== undefined ? 'resolved' : 'revision_reference_unresolved',
+    };
+    const observations = [
+        {
+            observationKey: deliveryKey,
+            sourceLocator,
+            kind: 'delivery',
+            nativeRefs: {
+                hostKind: 'workbuddy',
+                ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+                toolCallId: input.toolCallId,
+                toolName: input.toolName,
+            },
+            principleId: input.principleId,
+            contentRef,
+            activationRef,
+            payload: { targetKind: 'runtime_enforcement', confirmation: 'runtime_loaded', outcome: 'delivered' },
+        },
+        {
+            observationKey: `workbuddy|application|runtime_verified|${sessionPart}|${toolKey}|${input.activationId}`,
+            sourceLocator,
+            kind: 'application',
+            nativeRefs: {
+                hostKind: 'workbuddy',
+                ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+                toolCallId: input.toolCallId,
+                toolName: input.toolName,
+            },
+            principleId: input.principleId,
+            activationRef,
+            episodeKey,
+            payload: { proofMethod: 'runtime_verified', action: 'tool_blocked', enforcementBoundary: 'workbuddy_permission_decision_encoded_p02_verified' },
+        },
+        {
+            observationKey: episodeKey,
+            sourceLocator,
+            kind: 'behavior_episode',
+            nativeRefs: {
+                hostKind: 'workbuddy',
+                ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+                toolCallId: input.toolCallId,
+                toolName: input.toolName,
+            },
+            payload: {
+                status: 'closed',
+                actionSummary: `${input.toolName} denied by rule ${input.ruleId ?? 'unknown'}`,
+                resultSummary: 'deny encoded to WorkBuddy permission decision (P02 verified blocking)',
+            },
+        },
+        {
+            observationKey: `workbuddy|effect|${sessionPart}|${toolKey}|${input.activationId}`,
+            sourceLocator,
+            kind: 'effect',
+            nativeRefs: {
+                hostKind: 'workbuddy',
+                ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+                toolCallId: input.toolCallId,
+                toolName: input.toolName,
+            },
+            principleId: input.principleId,
+            episodeKey,
+            contentRef,
+            activationRef,
+            payload: {
+                status: 'observed',
+                observationSummary: `rule ${input.ruleId ?? 'unknown'} denied ${input.toolName}`,
+            },
+        },
+    ];
+    appendWorkbuddyBatch(input.workspaceDir, observations, input.warn);
+}

package/workbuddy-adapter/dist/worker/workspace-worker.d.ts

@@ -0,0 +1,41 @@
+import { type AdmitBareHostPainsResult, type InternalizationConsumerCycleOutcome, type ConsumerCycleLogger, type ReconcileGovernanceContinuationResult } from '@principles/host-runtime';
+export type WorkbuddyWorkerMode = 'ready' | 'manual_action_required' | 'paused' | 'degraded';
+export interface WorkbuddyWorkerCycleStepReport {
+    readonly reconcile: ReconcileGovernanceContinuationResult;
+    /**
+     * Bare-pain admission sweep (review R2/P1): the WorkBuddy hook writes bare
+     * failure pains with no inline admission, so the worker admits them into the
+     * shared governance queue before the diagnostician step.
+     */
+    readonly admission: AdmitBareHostPainsResult;
+    /** At most ONE diagnostician execution per cycle (bounded work). */
+    readonly diagnostician: {
+        readonly taskId: string;
+        readonly status: 'succeeded' | 'failed' | 'retried' | 'skipped' | 'degraded';
+        readonly message?: string;
+        readonly errorCategory?: string;
+        readonly nextAction?: string;
+    } | null;
+    readonly downstream: InternalizationConsumerCycleOutcome | null;
+}
+export interface WorkbuddyWorkerCycleResult {
+    readonly workspaceDir: string;
+    readonly mode: WorkbuddyWorkerMode;
+    readonly reason?: string;
+    readonly nextAction?: string;
+    readonly report?: WorkbuddyWorkerCycleStepReport;
+}
+export interface WorkbuddyWorkerCycleOptions {
+    readonly workspaceDir: string;
+    readonly now?: Date;
+    readonly logger?: ConsumerCycleLogger;
+    readonly emitEvent?: (event: string, payloadJson: string) => void;
+    /** Cap on diagnostician candidates inspected per cycle (default 5). */
+    readonly diagnosticianCandidateLimit?: number;
+}
+/**
+ * Run ONE bounded worker cycle for a canonical governance workspace. Never
+ * throws: every failure becomes a structured degraded result with a
+ * nextAction.
+ */
+export declare function runWorkbuddyWorkspaceWorkerCycle(options: WorkbuddyWorkerCycleOptions): Promise<WorkbuddyWorkerCycleResult>;

package/workbuddy-adapter/dist/worker/workspace-worker.js

@@ -0,0 +1,219 @@
+/**
+ * WorkBuddy Workspace worker cycle (SPEC workbuddy-host-adapter §5 Part 5;
+ * ADR-0020 §11.1 shape, third host instance).
+ *
+ * ONE Workspace-scoped worker cycle with exactly two background
+ * responsibilities — the Codex catch-up step is DELIBERATELY ABSENT because
+ * the WorkBuddy MVP excludes transcript ingestion (SPEC §1 Excluded; the
+ * hook itself is the only evidence producer):
+ *
+ *   1. run the idempotent reconciliation pass (shared host-runtime authority),
+ *      then admit the hook's BARE failure pains into the same governance
+ *      queue (review R2/P1 — no inline admission exists on this host; the
+ *      sweep reuses the ONE admission table and the crash-safe task ensure)
+ *   2. lease + run one Diagnostician execution, then ONE bounded downstream
+ *      consumer cycle through the SHARED host-neutral executor
+ *      (internalization_auto_consumer = workspace execution authority)
+ *
+ * Every step reuses existing authority: reconciliation reuses
+ * `reconcileGovernanceContinuation`, the diagnostician reuses the
+ * PainSignalBridge lease/runner contract, downstream reuses the same
+ * `runInternalizationConsumerCycle` the OpenClaw auto-consumer and the Codex
+ * worker run. No new task store, no private retry queue, no second
+ * scheduler state — and no Codex flag, path or transcript semantics are
+ * borrowed (SPEC §5: 不借用 Codex flag/日志伪装归因).
+ *
+ * Correctness under concurrent consumers (Companion-spawned `pd workbuddy
+ * worker` + manual `pd runtime internalization run-once`) is owned by the
+ * durable Runtime V2 task lease — never by process-local state. The
+ * governance workspace is the single canonical directory
+ * (`~/.workbuddy/pd-workspace`), so two projects never double-schedule:
+ * they share one workspace and the lease serialises consumption.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { computeFeatureFlagsFromConfig, createRuntimeStateHandle, createPainSignalBridge, isRetryWaitBackoffElapsed, PrincipleTreeLedgerAdapter, resolveDiagnosticianCapability, } from '@principles/core/runtime-v2';
+import { admitBareHostPains, loadPdConfigForPlugin, loadFeatureFlagFromConfig, reconcileGovernanceContinuation, runInternalizationConsumerCycle, saveHostToolDeclaration, } from '@principles/host-runtime';
+import { WORKBUDDY_TOOL_SEMANTICS, WORKBUDDY_TOOL_SEMANTIC_MAPPINGS } from '../tool-semantics.js';
+const WORKER_OWNER = 'companion-worker';
+const DEFAULT_DIAG_CANDIDATE_LIMIT = 5;
+function workerLogger(logger) {
+    return logger ?? {
+        info: () => undefined,
+        warn: () => undefined,
+        error: () => undefined,
+    };
+}
+function directoryExists(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Oldest pending diagnostician first; retry_wait candidates are filtered to
+ * those whose backoff window has ELAPSED (same discipline as the Codex
+ * worker — an old-but-waiting task cannot starve a younger eligible one).
+ */
+async function pickDiagnosticianCandidate(stateManager, limit) {
+    const pending = await stateManager.listTasks({ taskKind: 'diagnostician', status: 'pending', orderBy: 'updated_at_asc', limit });
+    const [first] = pending;
+    if (first !== undefined)
+        return first;
+    const retrying = await stateManager.listTasks({ taskKind: 'diagnostician', status: 'retry_wait', orderBy: 'updated_at_asc', limit });
+    for (const candidate of retrying) {
+        if (isRetryWaitBackoffElapsed(candidate.status, candidate.leaseExpiresAt)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Run ONE bounded worker cycle for a canonical governance workspace. Never
+ * throws: every failure becomes a structured degraded result with a
+ * nextAction.
+ */
+export async function runWorkbuddyWorkspaceWorkerCycle(options) {
+    const workspaceDir = path.resolve(options.workspaceDir);
+    const logger = workerLogger(options.logger);
+    const emitEvent = options.emitEvent ?? ((_event, _payload) => undefined);
+    const base = { workspaceDir };
+    // Step 1 — Workspace eligibility.
+    if (!directoryExists(workspaceDir)) {
+        return { ...base, mode: 'degraded', reason: 'workspace_missing', nextAction: 'The governance workspace directory no longer exists; run the WorkBuddy setup flow to re-initialize it. No PD state was mutated.' };
+    }
+    const config = loadPdConfigForPlugin(workspaceDir);
+    if (!config.ok) {
+        const [first] = config.errors;
+        return { ...base, mode: 'degraded', reason: `pd_config_invalid:${first?.reason ?? 'unknown'}`, nextAction: first?.nextAction ?? 'Repair the governance workspace .pd/config.yaml.' };
+    }
+    const { flags } = computeFeatureFlagsFromConfig(config.effective);
+    if (flags['host.workbuddy']?.enabled !== true) {
+        return { ...base, mode: 'paused', reason: 'host.workbuddy_disabled', nextAction: 'Set features.host.workbuddy.enabled=true in the governance workspace .pd/config.yaml to enable WorkBuddy PD behavior.' };
+    }
+    const consumerFlag = loadFeatureFlagFromConfig(workspaceDir, 'internalization_auto_consumer', { info: (m) => logger.info(m), warn: (m) => logger.warn(m) });
+    // The Diagnostician capability gate resolves from the same canonical
+    // authority as the runtime factory. An Owner-disabled agent is an
+    // intentional governance state: no candidate picking, no provider calls,
+    // no degraded mode; reconciliation and downstream keep running.
+    const capability = resolveDiagnosticianCapability(config.effective);
+    const diagnosticianDisabled = !capability.available;
+    // Step 2 — Idempotent reconciliation (always runs; creates no LLM work).
+    const reconcile = await reconcileGovernanceContinuation({ workspaceDir });
+    // Step 2b — Bare-pain admission (review R2/P1): the hook leaves bare
+    // workbuddy failure pains that no inline admission exists for. Without this
+    // sweep the evidence rows never reach the diagnostician queue. Runs AFTER
+    // reconcile (which continues already-admitted markers) and ensures tasks
+    // through the same crash-safe seam; bounded and idempotent.
+    const admission = await admitBareHostPains({ workspaceDir, hostKind: 'workbuddy' });
+    // Steps 3–5 — execution authority: internalization_auto_consumer.
+    let diagnostician = null;
+    if (diagnosticianDisabled) {
+        diagnostician = {
+            taskId: '',
+            status: 'skipped',
+            message: 'capability_disabled',
+            nextAction: capability.available ? undefined : capability.nextAction,
+        };
+    }
+    else if (!consumerFlag.enabled) {
+        return {
+            ...base,
+            mode: 'paused',
+            reason: 'internalization_auto_consumer_disabled',
+            nextAction: 'Automatic internalization execution is paused for this governance workspace; manual commands remain available: pd diagnose, pd runtime internalization run-once.',
+            report: { reconcile, admission, diagnostician: null, downstream: null },
+        };
+    }
+    else {
+        try {
+            const handle = await createRuntimeStateHandle({ workspaceDir, readonly: false });
+            try {
+                const sweep = await handle.stateManager.runRecoverySweep();
+                if (sweep.recovered > 0 || sweep.errors.length > 0) {
+                    emitEvent('WORKBUDDY_WORKER_RECOVERY_SWEEP', JSON.stringify({ recovered: sweep.recovered, failed: sweep.errors.length }));
+                }
+                const candidate = await pickDiagnosticianCandidate(handle.stateManager, options.diagnosticianCandidateLimit ?? DEFAULT_DIAG_CANDIDATE_LIMIT);
+                if (candidate !== null) {
+                    const stateDir = path.join(workspaceDir, '.state');
+                    const bridge = await createPainSignalBridge({
+                        workspaceDir,
+                        stateDir,
+                        ledgerAdapter: new PrincipleTreeLedgerAdapter({ stateDir }),
+                        owner: WORKER_OWNER,
+                        effectiveConfig: config.effective,
+                        getEnvVar: (name) => process.env[name],
+                    });
+                    const executed = await bridge.executePendingDiagnosis({ taskId: candidate.taskId });
+                    diagnostician = {
+                        taskId: candidate.taskId,
+                        status: executed.status,
+                        ...(executed.message !== undefined ? { message: executed.message.slice(0, 200) } : {}),
+                        ...(executed.errorCategory !== undefined ? { errorCategory: executed.errorCategory } : {}),
+                    };
+                }
+                else {
+                    const waiting = await handle.stateManager.listTasks({ taskKind: 'diagnostician', status: 'retry_wait', orderBy: 'updated_at_asc', limit: 1 });
+                    const [oldestWaiting] = waiting;
+                    if (oldestWaiting !== undefined && !isRetryWaitBackoffElapsed(oldestWaiting.status, oldestWaiting.leaseExpiresAt)) {
+                        diagnostician = { taskId: oldestWaiting.taskId, status: 'skipped', message: 'retry_wait_pending' };
+                    }
+                }
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
+            return {
+                ...base,
+                mode: 'degraded',
+                reason: `diagnostician_execution_failed:${detail}`,
+                nextAction: 'Inspect the governance workspace runtime profile and provider configuration; the task keeps its pending/retry state and no evidence was mutated.',
+                report: { reconcile, admission, diagnostician: null, downstream: null },
+            };
+        }
+    }
+    // Step 6 — ONE bounded downstream consumer cycle via the shared executor,
+    // with the WorkBuddy host declaration (probe-verified tool names: Read /
+    // Write / Edit / Bash are capitalized) persisted for host-neutral consumers.
+    const declared = saveHostToolDeclaration(workspaceDir, {
+        version: 1,
+        hostKind: 'workbuddy',
+        mappings: WORKBUDDY_TOOL_SEMANTIC_MAPPINGS,
+        declaredAt: new Date().toISOString(),
+    });
+    if (!declared.ok) {
+        logger.warn?.(`[PD:WorkbuddyWorker] Failed to persist WorkBuddy tool declaration: ${declared.reason} — host-neutral consumers will not find it (rc-9)`);
+        return {
+            ...base,
+            mode: 'degraded',
+            reason: `host_tool_declaration_persist_failed:${declared.reason}`,
+            nextAction: 'Repair WorkBuddy host declaration persistence (.pd/host-tool-semantics/workbuddy.json) before running the downstream internalization cycle; the worker retries automatically on the next cycle.',
+            report: { reconcile, admission, diagnostician, downstream: null },
+        };
+    }
+    const downstream = await runInternalizationConsumerCycle(workspaceDir, {
+        owner: WORKER_OWNER,
+        logLabel: 'WorkbuddyWorker',
+        logger,
+        emitEvent,
+        toolSemantics: WORKBUDDY_TOOL_SEMANTICS,
+        hostKinds: ['workbuddy'],
+    });
+    const degradedReason = !reconcile.ok ? `reconcile:${reconcile.reason ?? 'failed'}`
+        : !admission.ok ? `admission:${admission.reason ?? 'failed'}`
+            : diagnostician?.status === 'failed' && diagnostician.errorCategory !== 'lease_conflict' ? `diagnostician_failed:${diagnostician.message ?? 'max_attempts_exceeded'}`
+                : diagnostician?.status === 'degraded' ? `diagnostician_degraded:${diagnostician.message ?? 'unknown'}`
+                    : downstream.skipReason === 'runtime_config_error' || downstream.skipReason === 'cycle_error' || downstream.skipReason === 'config_malformed' ? `downstream:${downstream.skipReason}`
+                        : undefined;
+    return {
+        ...base,
+        mode: degradedReason !== undefined ? 'degraded' : 'ready',
+        ...(degradedReason !== undefined ? { reason: degradedReason, nextAction: 'Inspect the governance workspace .pd/config.yaml runtime profile and the per-step report above; the worker retries automatically on the next cycle.' } : {}),
+        report: { reconcile, admission, diagnostician, downstream },
+    };
+}

package/workbuddy-adapter/dist/workspace-resolution.d.ts

@@ -0,0 +1,15 @@
+export type WorkbuddyWorkspaceResolution = {
+    status: 'ok';
+    workspaceDir: string;
+} | {
+    status: 'uninitialized';
+    workspaceDir: string;
+    reason: 'workbuddy_workspace_not_initialized';
+    nextAction: string;
+} | {
+    status: 'degraded';
+    workspaceDir: string;
+    reason: 'workbuddy_workspace_config_invalid' | 'workbuddy_workspace_config_unreadable';
+    nextAction: string;
+};
+export declare function resolveWorkbuddyWorkspace(homeDir: string): WorkbuddyWorkspaceResolution;

package/workbuddy-adapter/dist/workspace-resolution.js

@@ -0,0 +1,53 @@
+/**
+ * WorkBuddy governance workspace resolution (SPEC §4.1 / OD-07, frozen by
+ * Phase 0 probe P06 2026-10-12).
+ *
+ * One explicit user-level governance directory shared across projects:
+ *   getWorkbuddyWorkspaceDir(homeDir) = <home>/.workbuddy/pd-workspace
+ * (the SSoT lives in @principles/install-layout — this module only consumes
+ * it). projectDir (the host cwd) stays separate and is used solely for tool
+ * path judgment by the shared gate.
+ *
+ * P06 semantics frozen here:
+ * - UNINITIALIZED (the governance config does not exist) is a normal,
+ *   actionable state: report the setup action, never fall back to another
+ *   host's database and never auto-create;
+ * - BAD CONFIG (config path exists but is not a readable regular file) is a
+ *   DEGRADED state: report and stop — no silent switch to another library.
+ */
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { getWorkbuddyWorkspaceDir } from '@principles/install-layout';
+export function resolveWorkbuddyWorkspace(homeDir) {
+    const workspaceDir = getWorkbuddyWorkspaceDir(homeDir);
+    const configPath = path.join(workspaceDir, '.pd', 'config.yaml');
+    let stat;
+    try {
+        stat = statSync(configPath);
+    }
+    catch (error) {
+        if (error instanceof Error && Object.hasOwn(error, 'code') && Reflect.get(error, 'code') === 'ENOENT') {
+            return {
+                status: 'uninitialized',
+                workspaceDir,
+                reason: 'workbuddy_workspace_not_initialized',
+                nextAction: `Run the PD WorkBuddy setup to initialize ${workspaceDir} (no other host's database is ever reused).`,
+            };
+        }
+        return {
+            status: 'degraded',
+            workspaceDir,
+            reason: 'workbuddy_workspace_config_unreadable',
+            nextAction: `Restore read access to ${configPath}; PD will not fall back to another workspace while it is unreadable.`,
+        };
+    }
+    if (!stat.isFile()) {
+        return {
+            status: 'degraded',
+            workspaceDir,
+            reason: 'workbuddy_workspace_config_invalid',
+            nextAction: `Repair ${configPath} (expected a regular config file); PD will not fall back to another workspace.`,
+        };
+    }
+    return { status: 'ok', workspaceDir };
+}

package/workbuddy-adapter/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@principles/workbuddy-adapter",
+  "version": "0.2.1",
+  "description": "WorkBuddy host adapter for Principles Disciple — implements the HostAdapter interface for WorkBuddy's Git Bash command-hook model (ADR-0020 third host, SPEC workbuddy-host-adapter v0.3.0).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./pd-hook": {
+      "types": "./dist/pd-hook.d.ts",
+      "default": "./dist/pd-hook.js"
+    },
+    "./host-adapter": {
+      "types": "./dist/host-adapter.d.ts",
+      "default": "./dist/host-adapter.js"
+    },
+    "./workspace-resolution": {
+      "types": "./dist/workspace-resolution.d.ts",
+      "default": "./dist/workspace-resolution.js"
+    },
+    "./tool-semantics": {
+      "types": "./dist/tool-semantics.d.ts",
+      "default": "./dist/tool-semantics.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "plugin",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint \"src/**/*.ts\""
+  },
+  "dependencies": {
+    "@principles/core": "file:../core",
+    "@principles/host-runtime": "file:../host-runtime",
+    "@principles/install-layout": "file:../install-layout"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csuzngjh/principles.git",
+    "directory": "packages/workbuddy-adapter"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/workbuddy-adapter/plugin/.codebuddy-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "principles-disciple",
+  "version": "0.1.0",
+  "description": "Principles Disciple — Owner-governed behavior internalization for AI agents (WorkBuddy host adapter, ADR-0020 third host). Requires explicit setup and host.workbuddy feature enablement; inactive until then.",
+  "defaultEnabled": false
+}