@principles/workbuddy-adapter 0.2.2 → 0.2.3

package/dist/explicit-owner-statement.d.ts

@@ -0,0 +1,3 @@
+import type { HostEvent } from '@principles/core/host';
+/** Only this native current-user hook can assert Owner authorship. No transcript is read. */
+export declare function recordWorkbuddyOwnerStatement(event: HostEvent, workspaceDir: string): Promise<string | undefined>;

package/dist/explicit-owner-statement.js

@@ -0,0 +1,52 @@
+import { admitGovernanceSignals, ensureGovernanceDiagnosticianTask, parseOwnerStatementPrefix } from '@principles/host-runtime';
+/** Only this native current-user hook can assert Owner authorship. No transcript is read. */
+export async function recordWorkbuddyOwnerStatement(event, workspaceDir) {
+    if (event.kind !== 'before_prompt_build')
+        return undefined;
+    const parsed = parseOwnerStatementPrefix(event.context.promptContent);
+    if (!parsed.matched)
+        return undefined;
+    const rejected = (reason, nextAction) => `[PD] host=workbuddy status=rejected reason=owner_statement_${reason} nextAction=${nextAction}`;
+    if (parsed.text === null)
+        return rejected(parsed.reason ?? 'statement_empty', 'Resubmit PD记录痛苦：<Owner statement of 1–500 characters>; nothing was recorded.');
+    const raw = event.rawPayload;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)
+        || Object.getOwnPropertyDescriptor(raw, 'is_internal_continuation')?.value !== false) {
+        return rejected('owner_source_unverified', 'Submit a new current-user message; native is_internal_continuation=false is required. Nothing was recorded.');
+    }
+    const { sessionId, turnId } = event.context;
+    if (sessionId.trim().length === 0 || turnId === undefined || turnId.trim().length === 0) {
+        return rejected('lineage_invalid', 'Native session_id and generation_id are required; nothing was recorded. Submit a new message.');
+    }
+    // A tuple avoids delimiter collisions; the occurrence namespace prevents
+    // collisions with Codex without changing its established canonical IDs.
+    const nativeIdentity = JSON.stringify(['workbuddy', sessionId, turnId]);
+    const logicalObservationKey = `${nativeIdentity}|user`;
+    try {
+        const admitted = admitGovernanceSignals({ workspaceDir, candidates: [{
+                    kind: 'user_correction', hostKind: 'workbuddy', logicalObservationKey,
+                    rolloutIdentity: JSON.stringify(['workbuddy', sessionId]), rootSessionId: sessionId,
+                    hostTurnId: nativeIdentity, text: parsed.text, observedAt: new Date().toISOString(), explicitOwnerStatement: true,
+                }] });
+        if (!admitted.ok)
+            return rejected('continuation_failed', `${admitted.reason}: ${admitted.nextAction}`);
+        const [outcome] = admitted.outcomes;
+        if (outcome === undefined)
+            return rejected('continuation_failed', 'Admission returned no outcome; inspect PD status and retry the same event.');
+        // Admission outcomes are a trusted discriminated union from the shared runtime.
+        // eslint-disable-next-line no-restricted-syntax
+        if (!('disposition' in outcome))
+            return rejected('continuation_failed', `${outcome.reason}: ${outcome.nextAction}`);
+        if (outcome.disposition === 'rate_limited')
+            return rejected('rate_limited', 'The existing per-session quota is exhausted; resubmit later. Nothing was recorded.');
+        if (outcome.disposition !== 'admitted' && outcome.disposition !== 'already_admitted')
+            return rejected('continuation_failed', 'The signal was not admitted; inspect PD status.');
+        const ensured = await ensureGovernanceDiagnosticianTask({ workspaceDir, logicalObservationKey, canonicalPainId: outcome.canonicalPainId });
+        if (!ensured.ok)
+            return rejected('continuation_failed', `painId=${outcome.canonicalPainId}; ${ensured.reason}: ${ensured.nextAction}. The pain may already be durable; retry the same event.`);
+        return `[PD] host=workbuddy status=received painId=${outcome.canonicalPainId} taskId=${ensured.taskId} disposition=${outcome.disposition}. Owner statement recorded as unverified owner_statement; diagnosis, candidate admission, approval and activation are not complete.`;
+    }
+    catch {
+        return rejected('continuation_failed', 'Inspect PD workspace storage and retry the same event; a durable pain may exist. No completed receipt is available.');
+    }
+}

package/dist/pd-hook.js

@@ -14,9 +14,9 @@
  *   encode/serialization fails
  *     → exit 2 + bounded stderr + EMPTY stdout (P02 verified exit 2 blocks
  *       the tool even when stdout is closed);
- *   UserPromptSubmit ANY failure
- *     → EMPTY stdout + exit 0 + degraded stderr (P02: exit 2 would CLEAR the
- *       user's prompt — protecting the prompt outranks reporting);
+ *   UserPromptSubmit failure
+ *     → exit 0 + degraded stderr; explicit Owner submissions may also carry
+ *       a bounded rejection context (exit 2 would CLEAR the user's prompt);
  *   PostToolUse ANY failure
  *     → EMPTY stdout + exit 0 + evidence-degradation stderr (the tool already
  *       ran; nothing can be blocked, so blocking language is never used);
@@ -37,12 +37,13 @@ import path from 'node:path';
 import process from 'node:process';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { appendEventLogLine, redactTelemetryString, isRuleHostEvaluatedEventData } from '@principles/core/runtime-v2';
-import { createProductionHostRuntime, loadPdConfigForPlugin } from '@principles/host-runtime';
+import { createProductionHostRuntime, loadPdConfigForPlugin, parseOwnerStatementPrefix } from '@principles/host-runtime';
 import { computeFeatureFlagsFromConfig } from '@principles/core/runtime-v2';
 import { WorkBuddyHooksHostAdapter } from './host-adapter.js';
 import { WORKBUDDY_TOOL_SEMANTICS } from './tool-semantics.js';
 import { resolveWorkbuddyWorkspace } from './workspace-resolution.js';
 import { WorkBuddyDecoderError, WorkBuddyEncoderError, isWorkBuddyHookOutput, WORKBUDDY_EVENT_PRE_TOOL_USE } from './codec/index.js';
+import { recordWorkbuddyOwnerStatement } from './explicit-owner-statement.js';
 import { recordWorkbuddyPromptDeliveryEvidence, recordWorkbuddyDenyEvidence } from './workbuddy-evidence-recorder.js';
 const MAX_DIAGNOSTIC = 500;
 function bound(text) {
@@ -206,7 +207,24 @@ export async function processWorkbuddyHookInvocation(rawStdin, channelEventName,
     catch (error) {
         const reason = error instanceof WorkBuddyDecoderError ? error.reason : `decode_threw:${errorMessage(error)}`;
         const nextAction = error instanceof WorkBuddyDecoderError ? error.nextAction : 'Inspect the WorkBuddy hook payload against the Phase 0 host contract.';
-        return channelFailure(channelEventName, reason, nextAction);
+        const failure = channelFailure(channelEventName, reason, nextAction);
+        // Rejection communicates failure, never grants Owner authority or bypasses
+        // decoding. Keep malformed native identity visible to the requesting Owner.
+        if (channelEventName === 'UserPromptSubmit' && typeof parsed === 'object' && parsed !== null
+            && Object.getOwnPropertyDescriptor(parsed, 'hook_event_name')?.value === 'UserPromptSubmit'
+            && parseOwnerStatementPrefix(Object.getOwnPropertyDescriptor(parsed, 'prompt')?.value).matched) {
+            const workspace = resolveWorkbuddyWorkspace(os.homedir());
+            if (workspace.status === 'ok') {
+                const config = loadPdConfigForPlugin(workspace.workspaceDir);
+                if (config.ok && computeFeatureFlagsFromConfig(config.effective).flags['host.workbuddy']?.enabled === true) {
+                    failure.stdout = { hookSpecificOutput: {
+                            hookEventName: 'UserPromptSubmit',
+                            additionalContext: '[PD] host=workbuddy status=rejected reason=owner_statement_decode_invalid nextAction=Native hook input is invalid; nothing was recorded. Check PD status and submit a new current-user message.',
+                        } };
+                }
+            }
+        }
+        return failure;
     }
     // OD-07/P06 governance workspace: explicit, user-level, shared across
     // projects; never auto-created here and never falling back to another host.
@@ -234,6 +252,12 @@ export async function processWorkbuddyHookInvocation(rawStdin, channelEventName,
     // it before replacing with the governance workspace.
     const projectDir = event.context.workspaceDir.length > 0 ? event.context.workspaceDir : undefined;
     event = { ...event, context: { ...event.context, workspaceDir: resolution.workspaceDir } };
+    const ownerReceipt = channelEventName === 'UserPromptSubmit'
+        ? await recordWorkbuddyOwnerStatement(event, resolution.workspaceDir)
+        : undefined;
+    const receiptOutput = (output) => ownerReceipt === undefined ? output : {
+        hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: [ownerReceipt, output?.hookSpecificOutput.additionalContext].filter(Boolean).join('\n\n') },
+    };
     try {
         if (event.kind === 'session_start') {
             // SPEC §4.2: health check only — first version injects NO body, and the
@@ -337,7 +361,7 @@ export async function processWorkbuddyHookInvocation(rawStdin, channelEventName,
             ...evaluationDiagnostics,
             ...evidenceDiagnostics,
         ];
-        return { stdout: encoded, exitCode: 0, stderr };
+        return { stdout: receiptOutput(encoded), exitCode: 0, stderr: [...stderr, ...(ownerReceipt === undefined ? [] : [ownerReceipt])] };
     }
     catch (error) {
         const reason = error instanceof WorkBuddyEncoderError ? error.reason : `runtime_failed:${errorMessage(error)}`;
@@ -349,7 +373,7 @@ export async function processWorkbuddyHookInvocation(rawStdin, channelEventName,
         }
         // UserPromptSubmit: protect the prompt (exit 2 clears it — P02).
         // after_tool_call: the tool already ran — report evidence degradation only.
-        return neutralWithDiagnostics([diagnostic('degraded', reason, nextAction)]);
+        return { stdout: receiptOutput(null), exitCode: 0, stderr: [diagnostic('degraded', reason, nextAction), ...(ownerReceipt === undefined ? [] : [ownerReceipt])] };
     }
 }
 // ─── Process-boundary belt (PRI-943 pattern, WorkBuddy exit-code semantics) ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/workbuddy-adapter",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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",
@@ -42,8 +42,8 @@
     "lint": "eslint \"src/**/*.ts\""
   },
   "dependencies": {
-    "@principles/core": "^1.293.0",
-    "@principles/host-runtime": "^0.10.0",
+    "@principles/core": "^1.293.4",
+    "@principles/host-runtime": "^0.10.2",
     "@principles/install-layout": "^0.4.0"
   },
   "devDependencies": {

package/plugin/scripts/pd-control.cjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+'use strict';
+
+const { existsSync } = require('node:fs');
+const { homedir } = require('node:os');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+async function main() {
+  if (process.argv.length !== 3 || process.argv[2] !== 'disable') {
+    throw new Error('Usage: node pd-control.cjs disable');
+  }
+  const home = homedir();
+  const workspace = path.join(home, '.workbuddy', 'pd-workspace');
+  const entry = path.join(home, '.pd', 'bootstrap', 'executor', 'dist', 'installers', 'workbuddy-host-installer.js');
+  if (!existsSync(entry)) throw new Error(`official_installer_api_missing: ${entry}`);
+  if (!existsSync(path.join(workspace, '.pd', 'config.yaml'))) {
+    throw new Error(`workbuddy_governance_config_missing: ${workspace}`);
+  }
+  const api = await import(pathToFileURL(entry).href);
+  if (typeof api.setWorkbuddyGovernanceFlag !== 'function'
+    || typeof api.readWorkbuddyGovernanceFlagOverride !== 'function') {
+    throw new Error('official_installer_api_unavailable');
+  }
+  const result = api.setWorkbuddyGovernanceFlag(workspace, false);
+  if (!result.ok) {
+    process.stdout.write(JSON.stringify({ ...result, host: 'workbuddy', workspace }) + '\n');
+    process.exitCode = 1;
+    return;
+  }
+  if (api.readWorkbuddyGovernanceFlagOverride(workspace) !== false) {
+    throw new Error('workbuddy_disable_readback_failed');
+  }
+  process.stdout.write(JSON.stringify({ ok: true, host: 'workbuddy', workspace, enabled: false }) + '\n');
+}
+
+main().catch((error) => {
+  process.stdout.write(JSON.stringify({
+    ok: false,
+    host: 'workbuddy',
+    reason: error instanceof Error ? error.message : String(error),
+    nextAction: 'Use the official installer: npx create-principles-disciple repair-update-chain; if the WorkBuddy workspace is missing, run npx create-principles-disciple --host workbuddy.',
+  }) + '\n');
+  process.exitCode = 1;
+});

package/plugin/skills/pd-disable/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pd-disable
+description: 当 Owner 要求停止或关闭 WorkBuddy 的 Principles Disciple 行为时，关闭此宿主治理开关并保留数据。
+---
+
+# 关闭 WorkBuddy PD
+
+Owner 的关闭请求已经授权这次操作。根据本技能文件的路径定位同一插件根目录（`skills/pd-disable/SKILL.md` 的上三级目录），运行随插件交付的控制脚本：
+
+```text
+node "<插件根目录>/scripts/pd-control.cjs" disable
+```
+
+脚本调用正式安装器的 `setWorkbuddyGovernanceFlag` API，在用户固定工作区 `~/.workbuddy/pd-workspace` 关闭 `host.workbuddy` 并读回验证。它保留治理数据和其他宿主配置，不手工修改数据库或已安装运行时代码。
+
+只有退出码为 0 且 JSON 回执 `ok=true`、`enabled=false`、`host=workbuddy` 时才确认开关已关闭。报告回执中的工作区和状态；新 Hook 调用将读取该配置。已运行中的任务是否停止须另查证。
+
+如果正式安装器 API 或工作区缺失，脚本明确失败；按回执使用官方安装/修复流程恢复能力。不要搜索 npm 缓存、拼装第二套写开关逻辑或用删除文件替代关闭。

package/plugin/skills/pd-record-pain/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: pd-record-pain
+description: 记录 WorkBuddy 行为失误或痛苦反馈。当 Owner 要求登记痛苦、记录错误或留下行为改进证据时使用。
+---
+
+# WorkBuddy 痛苦登记
+
+入口是 Owner 在当前 WorkBuddy 会话提交的一条消息：
+
+```text
+PD记录痛苦：<Owner 原文>
+```
+
+1. 仅使用当前 Owner 明确提供的陈述，正文须为 1–500 个字符。保留原文，不补写技术根因、评分或模型自述；超长时请 Owner 提供较短原文，不静默截断。
+2. 若当前消息已以 `PD记录痛苦：` 开头，检查本次 UserPromptSubmit Hook 的真实回执。Hook 使用宿主的会话标识登记到 `~/.workbuddy/pd-workspace`。
+3. 若 Owner 仅要求登记而消息没有该前缀，给出带前缀和 Owner 原文的完整消息，请 Owner 在当前会话提交。代理输出、引用和工具输出不构成新的 Owner 提交。不要代发或模拟宿主事件。
+4. 只有回执包含真实 `painId`、`taskId`、`host=workbuddy` 和状态时才报告登记成功；原样呈现这些字段。缺失回执或返回拒绝时，说明尚未确认登记并报告真实原因，使用 `pd-status` 检查运行状态。
+
+Owner 陈述是未经独立验证的 `owner_statement`。登记成功只证明痛苦和任务已登记；诊断、准入、原则审批和生效须分别查证。Owner 审批沿用 `pd-review`，不得自动批准或激活。
+
+此入口不要求模型猜测 session/turn 标识或扫描最新会话。不要改用 OpenClaw `/pd-pain` 或 CLI `pd pain record --host workbuddy`，也不要通过省略宿主参数绕过限制。

package/plugin/skills/pd-review/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: pd-review
+description: 打开 WorkBuddy 的 PD Owner 审阅控制台，查看痛苦、诊断、原则候选或进行 Owner 审批。
+---
+
+# WorkBuddy Owner 审阅
+
+将用户主目录解析为绝对路径，然后运行正式 CLI：
+
+```text
+pd console open --workspace "<用户主目录>/.workbuddy/pd-workspace"
+```
+
+只报告命令实际返回的控制台地址和状态。失败时保留错误原因，不声称已打开。此工作区与 WorkBuddy Hook、worker 使用的治理库相同；当前项目目录不能替代它。
+
+Owner 在控制台审阅证据并决定批准、拒绝或关闭。展示 Owner 原话、模型诊断和已核实证据之间的区别。打开控制台不构成审批或激活，代理不得自动代替 Owner 决策。

package/plugin/skills/pd-status/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: pd-status
+description: 检查 WorkBuddy 的 Principles Disciple 运行状态、治理开关或诊断 worker 状态。
+---
+
+# WorkBuddy PD 状态
+
+使用当前用户固定治理工作区 `~/.workbuddy/pd-workspace`，将 `~` 解析为操作系统用户主目录的绝对路径，再运行：
+
+```text
+pd runtime features --workspace "<用户主目录>/.workbuddy/pd-workspace" --json
+pd workbuddy worker --status --workspace "<用户主目录>/.workbuddy/pd-workspace" --json
+```
+
+报告实际命令结果、`host.workbuddy` 有效开关和 worker 模式；命令失败或安装缺失时如实报告错误，建议通过正式安装器修复。不要初始化项目目录或切换到其他宿主的治理库。
+
+worker 状态不证明当前痛苦已完成诊断，插件存在也不证明技能已加载或原则已生效。核对具体任务应使用真实登记回执中的 ID，在 `pd-review` 指向的同一工作区审阅。