@principles/pd-cli 1.73.0

package/README.md

@@ -0,0 +1,90 @@
+# @principles/pd-cli
+
+PD CLI — Pain recording, sample management, and evolution tasks for the Principles system.
+
+## Installation
+
+```bash
+npm install -g @principles/pd-cli
+```
+
+## Commands
+
+### `pd pain record`
+
+Record a pain signal to the workspace's `.pain_flag` file.
+
+```bash
+pd pain record --reason "edited file without reading first" --score 75
+```
+
+Options:
+- `--reason, -r` — Pain reason (required)
+- `--score, -s` — Pain score 0-100 (default: 80)
+- `--session-id` — Session ID (default: auto-generated)
+
+## Production Canary Validation
+
+Operator-facing runbook for validating PD runtime health in production. All commands below are read-only and safe to run against a live workspace.
+
+### Validation Sequence
+
+Run these three commands in order to assess runtime health:
+
+```bash
+# 1. Full canary — runs 7 health checks across schema, candidates, GFI, queue, and runtime
+node packages/pd-cli/dist/index.js runtime canary --workspace "D:\.openclaw\workspace" --json
+
+# 2. Internalization queue snapshot — inspect PI task pipeline state
+node packages/pd-cli/dist/index.js runtime internalization queue --workspace "D:\.openclaw\workspace" --json
+
+# 3. Internalization chain integrity — verify candidate→dreamer→philosopher→artifact links
+node packages/pd-cli/dist/index.js runtime internalization integrity --workspace "D:\.openclaw\workspace" --json
+```
+
+Omit `--json` for human-readable text output.
+
+### Interpreting Canary Status
+
+The canary runs 7 checks and reports an `overallStatus`:
+
+| Status | Meaning |
+|--------|---------|
+| `healthy` | All checks pass. No action needed. |
+| `degraded` | Non-critical issues found (orphan candidates, queue blockers, stale GFI sessions). Review `checks` for details. |
+| `error` | Schema conformance failure or check threw an exception. Investigate before proceeding. |
+
+Each check in the `checks` array has its own `status` field. The `recommendedNextActions` array provides targeted remediation suggestions.
+
+### Identifying the Next Internalization Blocker
+
+After a healthy canary, check the queue and integrity for the next PI task to resolve:
+
+**Queue** — look at the `readyTasks` array. If empty, check `noReadyTasks.reason`:
+- `all_tasks_blocked` — examine `blockedSummary.samples` for dependency chains
+- `all_tasks_dependency_failed` — examine `dependencyFailedSummary.samples` for failed dependencies
+- `all_tasks_retry_wait` — tasks are in backoff; check `retryWaitPendingSummary.samples` for retry timers
+
+**Integrity** — look at `brokenLinks`:
+- `severity: "error"` — a broken link in the chain (e.g., missing artifact). This blocks internalization for that candidate.
+- `severity: "warning"` — a data quality issue that may need attention but doesn't block immediately.
+
+Each broken link includes a `recommendedAction` field. The `chainsWithBrokenLinks` count tells you how many candidate chains are affected.
+
+### Remediation
+
+Remediation commands (e.g., `pd candidate audit --repair`, `pd runtime pruning orphans`) should **always** be run with `--dry-run` first:
+
+```bash
+node packages/pd-cli/dist/index.js runtime pruning orphans --workspace "D:\.openclaw\workspace" --dry-run
+```
+
+Only add `--confirm` after reviewing the dry-run output. Never run remediation without understanding what it will change.
+
+## Migration from openclaw tools
+
+The `pd pain record` CLI and the existing `write_pain_flag` tool write to the same pain flag file (`.state/.pain_flag`). They can coexist safely:
+
+- **Concurrency**: `recordPainSignal` in the SDK uses an in-process async queue lock to serialize writes within a single process. For cross-process safety (e.g., simultaneous tool + CLI calls), both paths rely on atomic file rename via `atomicWriteFileSync`.
+- **Progressive migration**: Agents using openclaw tools can migrate to `pd pain record` incrementally — both paths write the same format and are processed identically by the evolution system.
+- **No dual-write data loss**: The pain flag is a point-in-time snapshot; each write is atomic. Conflicting concurrent writes result in last-write-wins on the flag content, which is acceptable for pain signals.

package/dist/commands/artifact.d.ts

@@ -0,0 +1,14 @@
+interface ArtifactShowOptions {
+    artifactId: string;
+    workspace?: string;
+    json?: boolean;
+}
+/**
+ * pd artifact show <artifactId> [--workspace <path>] [--json]
+ *
+ * Shows artifact content and its associated principle candidates.
+ * Returns: artifactId, runId, taskId, artifactKind, contentJson, createdAt, candidates[].
+ */
+export declare function handleArtifactShow(opts: ArtifactShowOptions): Promise<void>;
+export {};
+//# sourceMappingURL=artifact.d.ts.map

package/dist/commands/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../../src/commands/artifact.ts"],"names":[],"mappings":"AAYA,UAAU,mBAAmB;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDjF"}

package/dist/commands/artifact.js

@@ -0,0 +1,67 @@
+/**
+ * pd artifact show command — Artifact registry inspection.
+ *
+ * Usage:
+ *   pd artifact show <artifactId> --workspace <path> [--json]
+ */
+import { RuntimeStateManager, artifactShow, } from '@principles/core/runtime-v2';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+/**
+ * pd artifact show <artifactId> [--workspace <path>] [--json]
+ *
+ * Shows artifact content and its associated principle candidates.
+ * Returns: artifactId, runId, taskId, artifactKind, contentJson, createdAt, candidates[].
+ */
+export async function handleArtifactShow(opts) {
+    const workspaceDir = resolveWorkspaceDir(opts.workspace);
+    const stateManager = new RuntimeStateManager({ workspaceDir });
+    try {
+        await stateManager.initialize();
+        const result = await artifactShow({
+            artifactId: opts.artifactId,
+            stateManager,
+        });
+        if (!result) {
+            console.error(`Artifact not found: ${opts.artifactId}`);
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`\nArtifact: ${result.artifactId}\n`);
+        console.log(`  Kind:       ${result.artifactKind}`);
+        console.log(`  Run:        ${result.runId}`);
+        console.log(`  Task:       ${result.taskId}`);
+        console.log(`  Created:    ${result.createdAt}`);
+        console.log(`  Candidates: ${result.candidates.length}`);
+        // Pretty-print the JSON content
+        try {
+            const parsed = JSON.parse(result.contentJson);
+            console.log(`\n  Content (parsed):`);
+            console.log(`    diagnosisId: ${parsed.diagnosisId ?? 'N/A'}`);
+            console.log(`    summary:     ${parsed.summary ?? 'N/A'}`);
+            if (parsed.recommendations) {
+                console.log(`    recommendations: ${parsed.recommendations.length}`);
+                const principles = parsed.recommendations.filter((r) => r.kind === 'principle');
+                if (principles.length > 0) {
+                    console.log(`      (${principles.length} principle candidates)`);
+                }
+            }
+        }
+        catch {
+            console.log(`  Content:    ${result.contentJson.substring(0, 200)}...`);
+        }
+        if (result.candidates.length > 0) {
+            console.log(`\n  Candidate Details:`);
+            for (const c of result.candidates) {
+                console.log(`    - ${c.candidateId} | ${c.title} | ${c.status}`);
+            }
+        }
+        console.log('');
+    }
+    finally {
+        await stateManager.close();
+    }
+}
+//# sourceMappingURL=artifact.js.map

package/dist/commands/artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../../src/commands/artifact.ts"],"names":[],"mappings":"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"}

package/dist/commands/candidate.d.ts

@@ -0,0 +1,83 @@
+interface CandidateListOptions {
+    taskId: string;
+    workspace?: string;
+    json?: boolean;
+}
+interface CandidateShowOptions {
+    candidateId: string;
+    workspace?: string;
+    json?: boolean;
+}
+interface CandidateIntakeOptions {
+    candidateId: string;
+    workspace?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}
+interface CandidateAuditOptions {
+    workspace?: string;
+    json?: boolean;
+}
+interface CandidateRepairOptions {
+    candidateId: string;
+    workspace?: string;
+    json?: boolean;
+}
+export declare function handleCandidateList(opts: CandidateListOptions): Promise<void>;
+interface CandidateInternalizeOptions {
+    candidateId: string;
+    workspace?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}
+export declare function handleCandidateInternalize(opts: CandidateInternalizeOptions): Promise<void>;
+export declare function handleCandidateShow(opts: CandidateShowOptions): Promise<void>;
+/**
+ * pd candidate intake --candidate-id <id> [--workspace <path>] [--json] [--dry-run]
+ *
+ * Intakes a principle candidate into the ledger.
+ * Wires together CandidateIntakeService + PrincipleTreeLedgerAdapter.
+ * Updates candidate status to 'consumed' (with consumed_at) after successful ledger write.
+ * If ledger write succeeds but DB update fails, exits non-zero with clear error.
+ */
+export declare function handleCandidateIntake(opts: CandidateIntakeOptions): Promise<void>;
+/**
+ * pd candidate audit --workspace <path> [--json]
+ *
+ * Reads workspace/.pd/state.db principle_candidates and
+ * the workspace ledger (same file used by OpenClaw plugin).
+ * Checks each consumed candidate has a ledger entry.
+ * Exits non-zero if any consumed candidate is missing from ledger.
+ */
+export declare function handleCandidateAudit(opts: CandidateAuditOptions): Promise<void>;
+/**
+ * pd candidate repair --candidate-id <id> --workspace <path> [--json]
+ *
+ * Handles consumed but missing ledger entries.
+ * Re-calls CandidateIntakeService.intake() to write ledger entry.
+ * Does not regenerate candidate; does not update status (already consumed).
+ * Fills consumed_at if empty.
+ */
+export declare function handleCandidateRepair(opts: CandidateRepairOptions): Promise<void>;
+interface CandidateBackfillOptions {
+    workspace?: string;
+    json?: boolean;
+    dryRun?: boolean;
+    confirm?: boolean;
+    includePending?: boolean;
+}
+export declare function handleCandidateInternalizationBackfill(opts: CandidateBackfillOptions): Promise<void>;
+interface CandidateRouteOptions {
+    candidateId: string;
+    workspace?: string;
+    json?: boolean;
+}
+/**
+ * pd candidate route --candidate-id <id> --workspace <path> [--json]
+ *
+ * Read-only: shows which internalization pipeline route a candidate will enter,
+ * whether it's ready, and what fields are missing.
+ */
+export declare function handleCandidateRoute(opts: CandidateRouteOptions): Promise<void>;
+export {};
+//# sourceMappingURL=candidate.d.ts.map

package/dist/commands/candidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate.d.ts","sourceRoot":"","sources":["../../src/commands/candidate.ts"],"names":[],"mappings":"AAkCA,UAAU,oBAAoB;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,oBAAoB;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,sBAAsB;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,UAAU,qBAAqB;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,sBAAsB;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA8GD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCnF;AAID,UAAU,2BAA2B;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAWD,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAoJjG;AAID,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCnF;AAID;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0GvF;AAID;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkErF;AAID;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuEvF;AAID,UAAU,wBAAwB;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAiFD,wBAAsB,sCAAsC,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoQ1G;AAID,UAAU,qBAAqB;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+CrF"}