create-principles-disciple 1.130.1 → 1.130.3

package/host-runtime/dist/host-tool-declaration.js

@@ -0,0 +1,161 @@
+/**
+ * Host Tool Declaration Store — PRI-634-F R2 (review P1-2, multi-host)
+ *
+ * PURPOSE: durable, host-authored provenance of which raw tool names each
+ * workspace host dispatches to the RuleHost gate. Each host persists its OWN
+ * declaration file — `.pd/host-tool-semantics/<hostKind>.json` — so OpenClaw
+ * and Codex sharing one workspace never overwrite each other (R1's single
+ * file was last-writer-wins: verification results depended on startup
+ * order). Host-neutral consumers load ALL declarations and resolve a merged
+ * registry via the host-tool-semantic-resolver.
+ *
+ * The host code stays the source of truth; the per-host file is a
+ * workspace-local projection, refreshed on every host startup.
+ *
+ * Trust boundary: file content is UNTRUSTED input at read time — parsed as
+ * unknown and structurally validated (rc-1/rc-2/rc-4); malformed files fail
+ * loud with a typed per-host reason, never degrade silently (rc-3/rc-9).
+ */
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { validateToolSemanticMappings, } from '@principles/core/runtime-v2';
+export const HOST_TOOL_DECLARATION_DIRNAME = 'host-tool-semantics';
+export const HOST_TOOL_DECLARATION_VERSION = 1;
+const MAX_DECLARATION_BYTES = 256 * 1024;
+/** hostKind doubles as a filename — code-controlled but validated anyway. */
+const HOST_KIND_PATTERN = /^[a-z][a-z0-9_-]*$/;
+function declarationsDir(workspaceDir) {
+    return path.join(workspaceDir, '.pd', HOST_TOOL_DECLARATION_DIRNAME);
+}
+function declarationPath(workspaceDir, hostKind) {
+    return path.join(declarationsDir(workspaceDir), `${hostKind}.json`);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseDeclaration(hostKind, raw) {
+    if (Buffer.byteLength(raw, 'utf8') > MAX_DECLARATION_BYTES) {
+        return { invalidReason: `declaration exceeds ${MAX_DECLARATION_BYTES} bytes` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { invalidReason: 'not valid JSON' };
+    }
+    if (!isRecord(parsed) || parsed.version !== HOST_TOOL_DECLARATION_VERSION) {
+        return { invalidReason: `version must be ${HOST_TOOL_DECLARATION_VERSION}` };
+    }
+    const { mappings, declaredAt } = parsed;
+    if (typeof declaredAt !== 'string' || declaredAt.trim() === '') {
+        return { invalidReason: 'declaredAt must be a non-empty string' };
+    }
+    const validation = validateToolSemanticMappings(mappings);
+    if (!validation.valid) {
+        return { invalidReason: `mappings invalid: ${validation.errors.slice(0, 3).join('; ')}` };
+    }
+    if (!Array.isArray(mappings) || mappings.length === 0) {
+        return { invalidReason: 'declaration must contain at least one mapping' };
+    }
+    return {
+        version: HOST_TOOL_DECLARATION_VERSION,
+        hostKind,
+        mappings,
+        declaredAt,
+    };
+}
+/**
+ * Persist ONE host's declaration (idempotent; hosts refresh on startup).
+ * Per-host file layout means concurrent/multi-host workspaces never
+ * overwrite each other (R2 P1-2). Atomic replace via a mkdtemp-unique
+ * staging dir (the sanctioned pattern for a possibly-shared location).
+ */
+export function saveHostToolDeclaration(workspaceDir, declaration) {
+    if (!isRecord(declaration) || typeof declaration.hostKind !== 'string' || !HOST_KIND_PATTERN.test(declaration.hostKind)) {
+        return { ok: false, reason: `hostKind must match ${HOST_KIND_PATTERN.source}` };
+    }
+    const payload = JSON.stringify({
+        version: declaration.version,
+        hostKind: declaration.hostKind,
+        mappings: declaration.mappings,
+        declaredAt: declaration.declaredAt,
+    });
+    if (Buffer.byteLength(payload, 'utf8') > MAX_DECLARATION_BYTES) {
+        return { ok: false, reason: `host tool declaration exceeds ${MAX_DECLARATION_BYTES} bytes` };
+    }
+    const dir = declarationsDir(workspaceDir);
+    const finalPath = declarationPath(workspaceDir, declaration.hostKind);
+    try {
+        mkdirSync(dir, { recursive: true });
+        const stagingDir = mkdtempSync(path.join(dir, 'declaration-'));
+        try {
+            const tmpPath = path.join(stagingDir, 'declaration.json');
+            writeFileSync(tmpPath, payload, 'utf8');
+            renameSync(tmpPath, finalPath);
+        }
+        finally {
+            rmSync(stagingDir, { recursive: true, force: true });
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Load ALL host declarations for the workspace. Typed result —
+ *   ok:false reason=host_tool_declaration_missing : no declarations persisted
+ *   ok:false reason=host_tool_declaration_invalid : at least one persisted
+ *     file is malformed (named by hostKind — a broken host declaration is a
+ *     defect the host must fix; consumers refuse rather than validate against
+ *     a partial view).
+ * Consumers decide policy — this module never guesses.
+ */
+export function loadHostToolDeclarations(workspaceDir) {
+    let entries;
+    try {
+        entries = readdirSync(declarationsDir(workspaceDir));
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'host_tool_declaration_missing',
+            nextAction: 'start each workspace host once (OpenClaw plugin / Codex worker) so it persists its tool declaration',
+        };
+    }
+    const declarations = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith('.json'))
+            continue;
+        const hostKind = entry.slice(0, -'.json'.length);
+        let raw;
+        try {
+            raw = readFileSync(path.join(declarationsDir(workspaceDir), entry), 'utf8');
+        }
+        catch {
+            return {
+                ok: false,
+                reason: `host_tool_declaration_invalid (${hostKind}: unreadable)`,
+                nextAction: `inspect ${declarationsDir(workspaceDir)}/${entry}`,
+            };
+        }
+        const parsed = parseDeclaration(hostKind, raw);
+        if ('invalidReason' in parsed) {
+            return {
+                ok: false,
+                reason: `host_tool_declaration_invalid (${hostKind}: ${parsed.invalidReason})`,
+                nextAction: `re-run host '${hostKind}' to refresh ${declarationsDir(workspaceDir)}/${entry}`,
+            };
+        }
+        declarations.push(parsed);
+    }
+    if (declarations.length === 0) {
+        return {
+            ok: false,
+            reason: 'host_tool_declaration_missing',
+            nextAction: 'start each workspace host once (OpenClaw plugin / Codex worker) so it persists its tool declaration',
+        };
+    }
+    return { ok: true, declarations };
+}

package/host-runtime/dist/host-tool-semantic-resolver.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Host Tool Semantic Resolver — PRI-634-F R2 Phase 1 (SPEC §五 P1-1/P1-2)
+ *
+ * PURPOSE: the ONE deep module every entry point uses to answer "which raw
+ * tool names can really reach this workspace's RuleHost gate, and what kind
+ * is each?" — load (all persisted host declarations) → merge (every declared
+ * host contributes its gate-reachable names; no host is guessed, no host is
+ * dropped) → validate (structural, fail-loud) → resolve (a merged
+ * ToolSemanticRegistry). Consumers:
+ *
+ *   - pd-cli activation / approval / promotion-readiness
+ *   - pd-console ApprovalsConsoleModel / ActivationsConsoleModel (R2 P1-1:
+ *     previously constructed RuleHostWriter directly and validated with the
+ *     bare baseline — the same artifact could refuse on the CLI and approve
+ *     on the Console)
+ *   - auto-consumer / codex worker (host-threaded registries, already
+ *     host-exact; the resolver exists for host-neutral entries)
+ *
+ * Multi-host semantics (R2 P1-2): declarations are PER-HOST files under
+ * `.pd/host-tool-semantics/<hostKind>.json` (last-writer-wins on a shared
+ * workspace was the R1 defect — startup order must not change verification
+ * results). The merged registry is the UNION of all declared hosts'
+ * gate-reachable names, so a rule generated under any co-installed host
+ * validates against its own host's surface.
+ *
+ * Pure logic + declared-file I/O only. Merging is order-independent.
+ */
+import { type ToolSemanticRegistry } from '@principles/core/runtime-v2';
+import { saveHostToolDeclaration, type HostToolDeclaration } from './host-tool-declaration.js';
+export type HostToolSemanticResolution = {
+    readonly ok: true;
+    readonly registry: ToolSemanticRegistry;
+    readonly hostKinds: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly nextAction: string;
+};
+/**
+ * Resolve the merged workspace registry from durable host provenance.
+ * Fails loud when no declaration is persisted or any persisted declaration
+ * is malformed — never falls back to the core baseline (an existence check
+ * against baseline names is a forged proof; ERR-114).
+ */
+export declare function resolveWorkspaceHostToolSemantics(workspaceDir: string): HostToolSemanticResolution;
+export { saveHostToolDeclaration };
+export type { HostToolDeclaration };

package/host-runtime/dist/host-tool-semantic-resolver.js

@@ -0,0 +1,73 @@
+/**
+ * Host Tool Semantic Resolver — PRI-634-F R2 Phase 1 (SPEC §五 P1-1/P1-2)
+ *
+ * PURPOSE: the ONE deep module every entry point uses to answer "which raw
+ * tool names can really reach this workspace's RuleHost gate, and what kind
+ * is each?" — load (all persisted host declarations) → merge (every declared
+ * host contributes its gate-reachable names; no host is guessed, no host is
+ * dropped) → validate (structural, fail-loud) → resolve (a merged
+ * ToolSemanticRegistry). Consumers:
+ *
+ *   - pd-cli activation / approval / promotion-readiness
+ *   - pd-console ApprovalsConsoleModel / ActivationsConsoleModel (R2 P1-1:
+ *     previously constructed RuleHostWriter directly and validated with the
+ *     bare baseline — the same artifact could refuse on the CLI and approve
+ *     on the Console)
+ *   - auto-consumer / codex worker (host-threaded registries, already
+ *     host-exact; the resolver exists for host-neutral entries)
+ *
+ * Multi-host semantics (R2 P1-2): declarations are PER-HOST files under
+ * `.pd/host-tool-semantics/<hostKind>.json` (last-writer-wins on a shared
+ * workspace was the R1 defect — startup order must not change verification
+ * results). The merged registry is the UNION of all declared hosts'
+ * gate-reachable names, so a rule generated under any co-installed host
+ * validates against its own host's surface.
+ *
+ * Pure logic + declared-file I/O only. Merging is order-independent.
+ */
+import { buildToolSemanticRegistry, } from '@principles/core/runtime-v2';
+import { loadHostToolDeclarations, saveHostToolDeclaration, } from './host-tool-declaration.js';
+/**
+ * Resolve the merged workspace registry from durable host provenance.
+ * Fails loud when no declaration is persisted or any persisted declaration
+ * is malformed — never falls back to the core baseline (an existence check
+ * against baseline names is a forged proof; ERR-114).
+ */
+export function resolveWorkspaceHostToolSemantics(workspaceDir) {
+    const loaded = loadHostToolDeclarations(workspaceDir);
+    if (!loaded.ok) {
+        return { ok: false, reason: loaded.reason, nextAction: loaded.nextAction };
+    }
+    const mappings = [];
+    for (const declaration of loaded.declarations) {
+        for (const mapping of declaration.mappings) {
+            // Same raw name from two hosts must agree on kind; a conflict means a
+            // host declared a name it does not own — fail loud rather than pick a
+            // winner by startup order (P4 one-source-of-truth).
+            const existing = mappings.find((m) => m.rawToolName === mapping.rawToolName);
+            if (existing && existing.canonicalKind !== mapping.canonicalKind) {
+                return {
+                    ok: false,
+                    reason: `host_tool_declaration_invalid (conflicting canonicalKind for '${mapping.rawToolName}': ${existing.canonicalKind} vs ${mapping.canonicalKind})`,
+                    nextAction: 'each raw tool name must resolve to one canonical kind across all co-installed hosts — fix the conflicting host declaration',
+                };
+            }
+            if (!existing)
+                mappings.push(mapping);
+        }
+    }
+    const built = buildToolSemanticRegistry(mappings);
+    if (!built.ok) {
+        return {
+            ok: false,
+            reason: 'host_tool_declaration_invalid',
+            nextAction: `merged host tool mappings invalid: ${built.errors.slice(0, 3).join('; ')}`,
+        };
+    }
+    return {
+        ok: true,
+        registry: built.registry,
+        hostKinds: loaded.declarations.map((d) => d.hostKind).sort(),
+    };
+}
+export { saveHostToolDeclaration };

package/host-runtime/dist/index.d.ts

@@ -3,7 +3,7 @@ import { buildActivePrinciplePromptContext } from './active-principle-prompt.js'
 import { type RuleContextProvider, type RuleInputEnrichmentProvider } from './production-rulehost-gate.js';
 import type { RuleImplementationRuntime } from './rule-implementation-runtime.js';
 import { type PainDatabaseFactory, type PainEnrichmentProvider } from './production-pain-evidence.js';
-import type { GovernanceHostKind } from '@principles/core/runtime-v2';
+import type { GovernanceHostKind, ToolSemanticRegistry } from '@principles/core/runtime-v2';
 export * from './active-principle-prompt.js';
 export * from './pd-config.js';
 export * from './production-rulehost-gate.js';
@@ -15,6 +15,8 @@ export * from './pain-evidence-ingress.js';
 export * from './host-liveness-contract.js';
 export * from './internalization-consumer-governance.js';
 export * from './internalization-consumer-cycle.js';
+export * from './host-tool-declaration.js';
+export * from './host-tool-semantic-resolver.js';
 export * from './workspace-telemetry-emitter.js';
 export * from './product-telemetry/consent-store.js';
 export * from './product-telemetry/eligibility.js';
@@ -57,4 +59,6 @@ export declare function createProductionHostRuntime(options?: Partial<Pick<HostR
     painDatabaseFactory?: PainDatabaseFactory;
     /** PRI-640: host attribution supplied by the constructing host adapter (OpenClaw / Codex). */
     hostKind?: GovernanceHostKind;
+    /** PRI-634-F: host-declared tool semantics supplied by the constructing host adapter. */
+    toolSemantics?: ToolSemanticRegistry;
 }): HostRuntime;

package/host-runtime/dist/index.js

@@ -17,6 +17,10 @@ export * from './host-liveness-contract.js';
 // auto-consumer + Companion workspace worker call the same cycle).
 export * from './internalization-consumer-governance.js';
 export * from './internalization-consumer-cycle.js';
+// PRI-634-F R2: durable host-authored tool declaration — hosts persist, host-
+// neutral consumers (pd-cli/pd-console) resolve through the ONE resolver.
+export * from './host-tool-declaration.js';
+export * from './host-tool-semantic-resolver.js';
 // PRI-634 A3: workspace-scoped critical telemetry — canonical implementation
 // moved from openclaw-plugin so both hosts share ONE semantics.
 export * from './workspace-telemetry-emitter.js';
@@ -144,6 +148,7 @@ export function createProductionHostRuntime(options = {}) {
         ...(options.ruleContextProvider ? { ruleContextProvider: options.ruleContextProvider } : {}),
         ...(options.ruleInputEnrichmentProvider ? { ruleInputEnrichmentProvider: options.ruleInputEnrichmentProvider } : {}),
         ...(options.ruleImplementationRuntime ? { implementationRuntime: options.ruleImplementationRuntime } : {}),
+        ...(options.toolSemantics ? { toolSemantics: options.toolSemantics } : {}),
     });
     return createHostRuntime({
         afterToolCall: options.afterToolCall ?? createProductionPainEvidenceHandler({

package/host-runtime/dist/internalization-consumer-cycle.d.ts

@@ -1,3 +1,4 @@
+import { type ToolSemanticRegistry } from '@principles/core/runtime-v2';
 import { type ConsumerGovernanceLogger } from './internalization-consumer-governance.js';
 export declare const INTERNALIZATION_AUTO_CONSUMER_FLAG_ID = "internalization_auto_consumer";
 /** Structural logger port — OpenClaw PluginLogger and worker loggers satisfy this. */
@@ -23,6 +24,14 @@ export interface InternalizationConsumerCyclePorts {
      * catalog would be worse than none.
      */
     readonly hostToolCatalog?: ConsumerHostToolCatalog;
+    /**
+     * PRI-634-F: host-declared ToolSemanticRegistry (raw tool name → canonical
+     * kind). Threaded into the activation gate (RuleHostWriter) and its
+     * gateDeps so sandbox replay resolves tool semantics IDENTICALLY to the
+     * host's production gate (replay/production input parity). Optional:
+     * hosts that have not declared semantics keep core-baseline behavior.
+     */
+    readonly toolSemantics?: ToolSemanticRegistry;
     /** Log label used in human log prefixes ('AutoConsumer' | 'CodexWorker' | …). */
     readonly logLabel: string;
     readonly envGetter?: (name: string) => string | undefined;

package/host-runtime/dist/internalization-consumer-cycle.js

@@ -140,7 +140,7 @@ async function runReconciliationBudget(workspaceDir, orchestrator, ports) {
  */
 export async function runInternalizationConsumerCycle(workspaceDir, ports) {
     const { logger, emitEvent, logLabel, owner } = ports;
-    const { hostToolCatalog } = ports;
+    const { hostToolCatalog, toolSemantics } = ports;
     const envGetter = ports.envGetter ?? ((name) => process.env[name]);
     let orchestrator = null;
     const flag = loadFeatureFlagFromConfig(workspaceDir, INTERNALIZATION_AUTO_CONSUMER_FLAG_ID, {
@@ -368,7 +368,13 @@ export async function runInternalizationConsumerCycle(workspaceDir, ports) {
                     ...createEvaluatorRepairDeps(workspaceDir, stateManager, logger),
                 }, {
                     ...runnerOptions,
-                    gateDeps: createProductionGateDeps(),
+                    // PRI-634-F: host registry + workspace root (when declared) make
+                    // the evaluator's adversarial replay resolve tool semantics and
+                    // normalizedPath identically to the host production gate.
+                    gateDeps: createProductionGateDeps({
+                        ...(toolSemantics ? { toolSemantics } : {}),
+                        projectDir: workspaceDir,
+                    }),
                     ...(hostToolCatalog
                         ? { hostToolCatalog: { readOnlyTools: [...hostToolCatalog.readOnlyTools], writeTools: [...hostToolCatalog.writeTools] } }
                         : {}),
@@ -386,7 +392,7 @@ export async function runInternalizationConsumerCycle(workspaceDir, ports) {
                 runner = new RolloutReviewerRunner({
                     stateManager, runtimeAdapter: adapter, eventEmitter: storeEmitter,
                     artifactStore: stateManager.piArtifactStore, validator: new DefaultRolloutReviewerValidator(),
-                    ...createRolloutGovernanceDeps(workspaceDir, orchestrator, logger),
+                    ...createRolloutGovernanceDeps(workspaceDir, orchestrator, { logger, ...(toolSemantics ? { toolSemantics } : {}) }),
                 }, runnerOptions);
                 break;
             default:

package/host-runtime/dist/internalization-consumer-governance.d.ts

@@ -14,14 +14,17 @@
  * dedupes by `${artifactId}::${channel}`; reopen idempotency is owned by
  * orchestrator.reopenTaskForRevision.
  */
-import { type RolloutAutoDispatchInput, type RolloutAutoDispatchOutcome, type RolloutRevisionRoutingInput, type SeedArtificerRepairParams, type RuntimeStateManager, type InternalizationOrchestrator } from '@principles/core/runtime-v2';
+import { type RolloutAutoDispatchInput, type RolloutAutoDispatchOutcome, type RolloutRevisionRoutingInput, type SeedArtificerRepairParams, type RuntimeStateManager, type InternalizationOrchestrator, type ToolSemanticRegistry } from '@principles/core/runtime-v2';
 /** Structural logger port — PluginLogger satisfies this without adaptation. */
 export interface ConsumerGovernanceLogger {
     info?: (msg: string) => void;
     warn?: (msg: string) => void;
 }
 /** rollout → ActivationDispatcher 的生产接线 (per dispatch 打开短连接, 与 Console 模式一致) */
-export declare function dispatchRolloutActivation(workspaceDir: string, input: RolloutAutoDispatchInput, logger?: ConsumerGovernanceLogger): Promise<RolloutAutoDispatchOutcome>;
+export declare function dispatchRolloutActivation(workspaceDir: string, input: RolloutAutoDispatchInput, options?: {
+    logger?: ConsumerGovernanceLogger;
+    toolSemantics?: ToolSemanticRegistry;
+}): Promise<RolloutAutoDispatchOutcome>;
 /** flag 探针: config 异常 → 全 false (fail-closed, 不 throw) */
 /** evaluator repair deps (PRI-509 机制的生产接线; flag 语义保留为运行时开关) */
 export declare function createEvaluatorRepairDeps(workspaceDir: string, stateManager: RuntimeStateManager, logger?: ConsumerGovernanceLogger): {
@@ -29,7 +32,10 @@ export declare function createEvaluatorRepairDeps(workspaceDir: string, stateMan
     seedArtificerRepairTask: (params: SeedArtificerRepairParams) => Promise<string>;
 };
 /** rollout reviewer 治理 deps: dispatch + revision reopen */
-export declare function createRolloutGovernanceDeps(workspaceDir: string, orchestrator: InternalizationOrchestrator, logger?: ConsumerGovernanceLogger): {
+export declare function createRolloutGovernanceDeps(workspaceDir: string, orchestrator: InternalizationOrchestrator, options?: {
+    logger?: ConsumerGovernanceLogger;
+    toolSemantics?: ToolSemanticRegistry;
+}): {
     dispatchActivation: (input: RolloutAutoDispatchInput) => Promise<RolloutAutoDispatchOutcome>;
     reopenRevisionTarget: (input: RolloutRevisionRoutingInput) => Promise<{
         ok: boolean;

package/host-runtime/dist/internalization-consumer-governance.js

@@ -38,7 +38,7 @@ function makeFlagProbe(workspaceDir) {
     return (flagId) => isFeatureEnabled(flags, flagId);
 }
 /** rollout → ActivationDispatcher 的生产接线 (per dispatch 打开短连接, 与 Console 模式一致) */
-export async function dispatchRolloutActivation(workspaceDir, input, logger) {
+export async function dispatchRolloutActivation(workspaceDir, input, options = {}) {
     const connection = new SqliteConnection(workspaceDir);
     try {
         const piArtifactStore = new SqlitePIArtifactStore(connection);
@@ -67,7 +67,15 @@ export async function dispatchRolloutActivation(workspaceDir, input, logger) {
         const dispatcher = new ActivationDispatcher(artifactReadModel, activationStateStore, {
             writers: [
                 new PromptWriter(),
-                new RuleHostWriter({ gateDeps: createProductionGateDeps(), featureFlagProbe: flagProbe }),
+                // PRI-634-F: toolSemantics (host-declared) + the workspace root flow
+                // into the activation writer — reliability validation + replay with
+                // production-identical path normalization.
+                new RuleHostWriter({
+                    gateDeps: createProductionGateDeps(options.toolSemantics ? { toolSemantics: options.toolSemantics } : {}),
+                    featureFlagProbe: flagProbe,
+                    ...(options.toolSemantics ? { toolSemantics: options.toolSemantics } : {}),
+                    projectDir: workspaceDir,
+                }),
                 new DeferArchiveWriter(),
             ],
             approvalQueueStore,
@@ -82,7 +90,7 @@ export async function dispatchRolloutActivation(workspaceDir, input, logger) {
             confidence: input.confidence,
         });
         const outcome = normalizeDecision(decision);
-        logger?.info?.(`[PD:Consumer] rollout dispatch: artifact=${input.artifactId} channel=${input.channel} → ${outcome.decision}${outcome.activationId ? ` (${outcome.activationId})` : ''}${outcome.reason ? ` reason=${outcome.reason}` : ''}`);
+        options.logger?.info?.(`[PD:Consumer] rollout dispatch: artifact=${input.artifactId} channel=${input.channel} → ${outcome.decision}${outcome.activationId ? ` (${outcome.activationId})` : ''}${outcome.reason ? ` reason=${outcome.reason}` : ''}`);
         return outcome;
     }
     finally {
@@ -135,9 +143,9 @@ export function createEvaluatorRepairDeps(workspaceDir, stateManager, logger) {
     };
 }
 /** rollout reviewer 治理 deps: dispatch + revision reopen */
-export function createRolloutGovernanceDeps(workspaceDir, orchestrator, logger) {
+export function createRolloutGovernanceDeps(workspaceDir, orchestrator, options = {}) {
     return {
-        dispatchActivation: (input) => dispatchRolloutActivation(workspaceDir, input, logger),
+        dispatchActivation: (input) => dispatchRolloutActivation(workspaceDir, input, options),
         reopenRevisionTarget: async (input) => {
             const result = await orchestrator.reopenTaskForRevision(input.targetTaskId, {
                 revisionFeedback: input.revisionFeedback,

package/host-runtime/dist/production-rulehost-gate.d.ts

@@ -1,3 +1,4 @@
+import { type ToolSemanticRegistry } from '@principles/core/runtime-v2';
 import type { HostEvent, HostEventResult } from '@principles/core/host';
 import { type RuleImplementationRuntime } from './rule-implementation-runtime.js';
 export interface ProductionRuleContextRequest {
@@ -18,5 +19,14 @@ export interface ProductionRuleHostGateOptions {
     ruleContextProvider?: RuleContextProvider;
     ruleInputEnrichmentProvider?: RuleInputEnrichmentProvider;
     implementationRuntime?: RuleImplementationRuntime;
+    /**
+     * PRI-634-F: host-declared ToolSemanticRegistry. Extraction hints and
+     * action.canonicalKind derive from this registry (defaults to the
+     * core-baseline registry when the constructing host has not declared its
+     * tool semantics). Replaces the previous inline bash/write name sets,
+     * which silently disagreed with the OpenClaw host vocabulary
+     * (shell/cmd/insert/patch/delete_file/move_file were never hinted).
+     */
+    toolSemantics?: ToolSemanticRegistry;
 }
 export declare function createProductionRuleHostGate(options?: ProductionRuleHostGateOptions): (event: HostEvent) => Promise<HostEventResult>;

package/host-runtime/dist/production-rulehost-gate.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { buildRuleHostAction, estimateLineChanges, mergeDecisions, SqliteConnection, UNAVAILABLE_RULE_CONTEXT, validateRuleContextV2, validateRuleHostResult, } from '@principles/core/runtime-v2';
+import { buildRuleHostAction, buildToolSemanticRegistry, deriveToolHintsFromCanonicalKind, estimateLineChanges, mergeDecisions, SqliteConnection, UNAVAILABLE_RULE_CONTEXT, validateRuleContextV2, validateRuleHostResult, } from '@principles/core/runtime-v2';
 import { scanRetiredContractSymbols } from './legacy-rule-contract-symbols.js';
 import { createNodeRuleImplementationRuntime, MAX_ACTIVE_RULES, RULE_BATCH_SOURCE_BYTES, RULE_SOURCE_BYTES, } from './rule-implementation-runtime.js';
 const WARNING_LIMIT = 500;
@@ -62,8 +62,15 @@ function isRuleContext(value) {
 function isRuleResult(value) {
     return validateRuleHostResult(value).valid;
 }
+const baselineToolSemanticsResult = buildToolSemanticRegistry();
+// Static baseline input — always builds; throwing here is a programming error.
+if (!baselineToolSemanticsResult.ok) {
+    throw new Error(`baseline tool semantic registry failed to build: ${baselineToolSemanticsResult.errors.join('; ')}`);
+}
+const BASELINE_TOOL_SEMANTICS = baselineToolSemanticsResult.registry;
 export function createProductionRuleHostGate(options = {}) {
     const implementationRuntime = options.implementationRuntime ?? createNodeRuleImplementationRuntime();
+    const toolSemantics = options.toolSemantics ?? BASELINE_TOOL_SEMANTICS;
     return async (event) => {
         const startedAt = Date.now();
         const warnings = [];
@@ -71,9 +78,9 @@ export function createProductionRuleHostGate(options = {}) {
         if (!input || input.toolName !== event.context.toolName) {
             return { decision: 'allow', source: event.source, warnings: [boundedWarning('tool_input_invalid', 'decode and validate toolName and params before dispatch')] };
         }
-        const isBash = new Set(['bash', 'exec', 'execute', 'run_shell_command']).has(input.toolName);
-        const isWrite = new Set(['write', 'write_file', 'edit', 'edit_file', 'replace', 'apply_patch']).has(input.toolName);
-        const action = buildRuleHostAction(input.toolName, input.params, event.context.workspaceDir, { isBashTool: isBash, isWriteTool: isWrite });
+        const canonicalKind = toolSemantics.resolve(input.toolName);
+        const { isBashTool: isBash, isWriteTool: isWrite } = deriveToolHintsFromCanonicalKind(canonicalKind);
+        const action = buildRuleHostAction(input.toolName, input.params, event.context.workspaceDir, { isBashTool: isBash, isWriteTool: isWrite, canonicalKind });
         if (action.normalizedPath === null)
             return { decision: 'allow', source: event.source, metadata: { evaluatedLiveRules: 0 } };
         let context;

package/host-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/host-runtime",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Shared host-neutral orchestration for Principles Disciple MVP-Core hook paths.",
   "type": "module",
   "main": "./dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-principles-disciple",
-  "version": "1.130.1",
+  "version": "1.130.3",
   "description": "Interactive CLI installer for Principles Disciple OpenClaw plugin",
   "type": "module",
   "bin": {
@@ -72,6 +72,6 @@
     "directory": "packages/create-principles-disciple"
   },
   "pd": {
-    "bundledPluginVersion": "1.228.2"
+    "bundledPluginVersion": "1.229.0"
   }
 }

package/pd-cli/dist/commands/rulecode.d.ts

@@ -53,6 +53,17 @@ export interface RulecodeReplayOutput {
     forbiddenPatternViolations: string[];
     reason?: string;
     nextAction?: string;
+    /**
+     * PRI-634-F R2 (review P2): structured failure attribution
+     * ({layer, reasonCode, evidence, nextAction}) — machine-readable on
+     * `--json`, printed on the text path. Absent when replay passed.
+     */
+    failure?: {
+        layer: string;
+        reasonCode: string;
+        evidence: string;
+        nextAction: string;
+    };
 }
 /**
  * Load and validate golden trace cases from a JSON file.

package/pd-cli/dist/commands/rulecode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rulecode.d.ts","sourceRoot":"","sources":["../../src/commands/rulecode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWzC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAKxE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,IAAI,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtE,0BAA0B,EAAE,MAAM,EAAE,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA2CD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB;IAAE,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAuDpF;AAID,UAAU,WAAW;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CASzE;AAED,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDjF;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA2H7E;AAID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAoDnE"}
+{"version":3,"file":"rulecode.d.ts","sourceRoot":"","sources":["../../src/commands/rulecode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWzC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAKxE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,IAAI,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtE,0BAA0B,EAAE,MAAM,EAAE,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACvF;AA2CD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB;IAAE,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAuDpF;AAID,UAAU,WAAW;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CASzE;AAED,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDjF;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA6H7E;AAID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAoDnE"}

package/pd-cli/dist/commands/rulecode.js

@@ -293,10 +293,11 @@ export async function handleRulecodeReplay(opts) {
             message: c.message,
         })),
         forbiddenPatternViolations: gateResult.sandboxResult.forbiddenPatternViolations,
+        ...(gateResult.failure ? { failure: gateResult.failure } : {}),
     };
     if (output.status === 'failed') {
         output.reason = `sandbox replay rejected: ${gateResult.decision}`;
-        output.nextAction = 'fix the code or golden trace cases based on the failed cases above';
+        output.nextAction = gateResult.failure?.nextAction ?? 'fix the code or golden trace cases based on the failed cases above';
     }
     emitResult(output, {
         json,
@@ -304,6 +305,8 @@ export async function handleRulecodeReplay(opts) {
             if (o.status === 'ok')
                 return 'PASSED: all golden trace cases replayed successfully.';
             const lines = [`FAILED: ${o.decision}`];
+            if (o.failure)
+                lines.push(`  - failureLayer: ${o.failure.layer} | reasonCode: ${o.failure.reasonCode}`);
             for (const r of o.reasons)
                 lines.push(`  - ${r}`);
             for (const c of o.failedCases)