@principles/pd-cli 1.135.2 → 1.137.0

package/src/commands/runtime-init.ts

@@ -18,12 +18,38 @@
  */
 
 import * as path from 'path';
-import { SqliteConnection } from '@principles/core/runtime-v2';
-import { SchemaConformanceReadModel } from '@principles/core/runtime-v2';
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import { SqliteConnection, SchemaConformanceReadModel } from '@principles/core/runtime-v2';
+import { getDefaultPdConfig, validatePdConfig } from '@principles/core/runtime-v2';
 import { initTrajectorySchema, initWorkflowSchema } from 'principles-disciple';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { emitResult, emitFlagConflict, emitError } from '../services/cli-output.js';
 
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const CONFIG_DIR = '.pd';
+const CONFIG_FILENAME = 'config.yaml';
+const CONFIG_HEADER =
+  `# PD Runtime Configuration — single source of truth (.pd/config.yaml, ADR-0016)\n` +
+  `# Auto-generated by 'pd runtime init'. Existing config files are never overwritten.\n` +
+  `# Edit to configure feature flags, runtime profiles, internal agents, and UI.\n`;
+
+/**
+ * Type guard for Node.js errno errors (rc-2: no `as` on caught unknown).
+ * Mirrors principle-tree-ledger.ts — uses Object.hasOwn, not `in`.
+ * Structural type (not NodeJS.ErrnoException) to avoid the NodeJS global,
+ * which is not defined in this package's eslint config.
+ * Needed to detect EEXIST from the atomic exclusive write below.
+ */
+interface ErrnoExceptionLike {
+  code?: string;
+}
+
+function isErrnoException(value: unknown): value is ErrnoExceptionLike {
+  return typeof value === 'object' && value !== null && Object.hasOwn(value, 'code');
+}
+
 // ── Output types ─────────────────────────────────────────────────────────────
 
 export interface DatabaseInitResult {
@@ -34,11 +60,18 @@ export interface DatabaseInitResult {
   warnings: string[];
 }
 
+export interface ConfigInitResult {
+  path: string;
+  status: 'initialized' | 'skipped' | 'failed' | 'verified';
+  warnings: string[];
+}
+
 export interface RuntimeInitOutput {
   ok: boolean;
   mode: 'dry-run' | 'confirm';
   workspace: string;
   databases: DatabaseInitResult[];
+  config?: ConfigInitResult;
   warnings: string[];
   reason?: string;
   nextAction?: string;
@@ -52,6 +85,100 @@ const DB_NAMES = {
   workflow: 'subagent_workflows.db',
 } as const;
 
+// ── Config file generation ─────────────────────────────────────────────────────
+
+/**
+ * Build a clean YAML representation of the default PD config, injecting the
+ * workspace.default path so that discoverWorkspaceDefault() can find it.
+ *
+ * Returns the YAML string (with header comment) for writing to disk.
+ */
+function buildConfigYaml(workspaceDir: string): string {
+  const config = getDefaultPdConfig();
+  const yamlObj: Record<string, unknown> = {
+    version: config.version,
+    workspace: {
+      default: workspaceDir,
+    },
+    features: config.features,
+    runtimeProfiles: config.runtimeProfiles,
+    internalAgents: config.internalAgents,
+    ui: config.ui,
+  };
+  return CONFIG_HEADER + yaml.dump(yamlObj, {
+    indent: 2,
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: false,
+    quotingType: '"',
+    forceQuotes: false,
+  });
+}
+
+/**
+ * Generate and write .pd/config.yaml if it does not already exist.
+ * Validates the generated file with a round-trip parse+validate check.
+ */
+function buildConfigInitResult(workspaceDir: string, confirm: boolean): ConfigInitResult {
+  const configPath = path.join(workspaceDir, CONFIG_DIR, CONFIG_FILENAME);
+  const warnings: string[] = [];
+
+  if (!confirm) {
+    return { path: configPath, status: 'skipped', warnings: [] };
+  }
+
+  // Ensure .pd directory exists
+  const configDir = path.dirname(configPath);
+  try {
+    fs.mkdirSync(configDir, { recursive: true });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { path: configPath, status: 'failed', warnings: [`Failed to create ${configDir}: ${reason}`] };
+  }
+
+  // Build and write YAML
+  let yamlContent: string;
+  try {
+    yamlContent = buildConfigYaml(workspaceDir);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { path: configPath, status: 'failed', warnings: [`Failed to build config YAML: ${reason}`] };
+  }
+
+  try {
+    // Atomic exclusive create ('wx'): the write itself is the authoritative
+    // existence check — fails with EEXIST if the file already exists (from a
+    // previous run or a concurrent process). No existsSync pre-check, so there
+    // is no TOCTOU window and the "never overwrite existing config" contract
+    // is race-free (CodeQL js/race-condition).
+    fs.writeFileSync(configPath, yamlContent, { encoding: 'utf8', flag: 'wx' });
+  } catch (err) {
+    if (isErrnoException(err) && err.code === 'EEXIST') {
+      return { path: configPath, status: 'skipped', warnings: ['config.yaml already exists, skipped'] };
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    return { path: configPath, status: 'failed', warnings: [`Failed to write ${configPath}: ${reason}`] };
+  }
+
+  // Round-trip validation: read back, parse, validate
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const parsed: unknown = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+    const validationResult = validatePdConfig(parsed);
+    if (!validationResult.ok) {
+      warnings.push(`config.yaml round-trip validation produced ${validationResult.errors.length} warnings`);
+      for (const ve of validationResult.errors) {
+        warnings.push(`  [${ve.path}] ${ve.reason} — ${ve.nextAction}`);
+      }
+    }
+  } catch (err) {
+    // Non-fatal: proceed even if round-trip check fails
+    warnings.push(`config.yaml round-trip check skipped: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return { path: configPath, status: 'initialized', warnings };
+}
+
 export function buildRuntimeInitOutput(workspaceDir: string, confirm: boolean): RuntimeInitOutput {
   const resolvedWorkspace = path.resolve(workspaceDir);
   const warnings: string[] = [];
@@ -213,11 +340,27 @@ export function buildRuntimeInitOutput(workspaceDir: string, confirm: boolean):
     }
   }
 
+  // 4. config.yaml — scaffold the single source of truth (P0: runtime discovery)
+  const config = buildConfigInitResult(resolvedWorkspace, confirm);
+  if (config.status === 'failed') {
+    return {
+      ok: false,
+      mode: 'confirm',
+      workspace: resolvedWorkspace,
+      databases,
+      config,
+      warnings,
+      reason: config.warnings[0] ?? 'config.yaml initialization failed',
+      nextAction: 'Check .pd directory permissions and disk space, then re-run `pd runtime init --confirm`.',
+    };
+  }
+
   return {
     ok: true,
     mode: confirm ? 'confirm' : 'dry-run',
     workspace: resolvedWorkspace,
     databases,
+    config,
     warnings,
   };
 }
@@ -246,6 +389,17 @@ function formatTextOutput(output: RuntimeInitOutput): string {
     }
   }
 
+  if (output.config) {
+    const icon = output.config.status === 'initialized' ? '[+]' :
+                 output.config.status === 'verified' ? '[v]' :
+                 output.config.status === 'skipped' ? '[ ]' : '[x]';
+    lines.push(`${icon} config.yaml (${output.config.status})`);
+    lines.push(`    path: ${output.config.path}`);
+    for (const w of output.config.warnings) {
+      lines.push(`    warning: ${w}`);
+    }
+  }
+
   if (output.warnings.length > 0) {
     lines.push('');
     lines.push('Warnings:');

package/src/commands/runtime-internalization-run-once.ts

@@ -20,6 +20,8 @@ import {
 import type { WakeOnceResult, DreamerRunnerResult, PhilosopherRunnerResult, ScribeRunnerResult, ArtificerRunnerResult, EvaluatorRunnerResult, RolloutReviewerRunnerResult, PDRuntimeAdapter, PeerRunnerKind, OutputLanguage } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { readOutputLanguageFromWorkspace } from '../config-reader.js';
+import { loadPdConfig } from '../services/pd-config-loader.js';
+import type { EffectivePdConfig } from '@principles/core/runtime-v2';
 import {
   resolveRuntimeAdapterFromConfig,
   ConfigResolutionError,
@@ -447,6 +449,11 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
   const stateManager = new RuntimeStateManager({ workspaceDir });
   await stateManager.initialize();
 
+  // Issue 2: resolve effective config for feature-flag-aware runners
+  // (e.g. `artificer_output_retry`). Mirrors rulehost-pipeline-runner.
+  const configLoad = loadPdConfig(workspaceDir);
+  const effectiveConfig: EffectivePdConfig | undefined = configLoad.ok ? configLoad.effective : configLoad.defaults;
+
   try {
     const orchestrator = new InternalizationOrchestrator(
       { stateManager },
@@ -515,7 +522,7 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
           const validator = new DefaultArtificerValidator();
           const runner = new ArtificerRunner(
             { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore, contentHashFn },
-            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs, effectiveConfig },
           );
           runnerResult = await runner.run(wakeResult.taskId);
         } else if (runnerKind === 'evaluator') {

package/src/index.ts

@@ -45,6 +45,7 @@ import { handleRuntimeInternalizationIntegrityRepair } from './commands/runtime-
 import { handleRuntimeInternalizationEnqueueSuccessors } from './commands/runtime-internalization-enqueue-successors.js';
 import { handleRuntimeInternalizationContextTrace } from './commands/runtime-internalization-context-trace.js';
 import { handleRuntimeDiagnosticsExport } from './commands/runtime-diagnostics-export.js';
+import { registerRuntimeCompatibilityScanCommand } from './commands/runtime-compatibility-scan.js';
 import { handleRuntimeRecoverySweep } from './commands/runtime-recovery.js';
 import { handleRuntimeRecoveryFailedTasks } from './commands/runtime-recovery-failed-tasks.js';
 import {
@@ -341,6 +342,8 @@ runtimeCmd
     });
   });
 
+registerRuntimeCompatibilityScanCommand(runtimeCmd);
+
 const synthCmd = runtimeCmd
   .command('synthetic', { hidden: true })
   .description('Synthetic workload baseline commands');
@@ -455,11 +458,13 @@ demoCmd
   .option('-w, --workspace <path>', 'Workspace directory (default: temp workspace)')
   .option('--json', 'Output raw JSON')
   .option('--channels <channels>', 'Comma-separated channel list (prompt,code_tool_hook,defer_archive)')
+  .option('--allow-demo-write-to-existing-workspace', 'Developer override: permit writing demo artifacts into a workspace that already contains PD state (demo isolation guard)')
   .action(async (opts) => {
     await handleDemoStoryA({
       workspace: opts.workspace,
       json: opts.json,
       channels: opts.channels,
+      allowDemoWriteToExistingWorkspace: opts.allowDemoWriteToExistingWorkspace === true,
     });
   });
 

package/src/services/rulehost-pipeline-runner.ts

@@ -272,6 +272,11 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
   try {
     const artifactStore = stateManager.piArtifactStore;
     const eventEmitter = new StoreEventEmitter();
+    // Issue 2: load effective config once so every stage runner can resolve
+    // feature flags (e.g. `artificer_output_retry`). Mirrors
+    // createEvaluatorRunnerDeps (rc-9: malformed config → fallback defaults).
+    const configLoad = loadPdConfig(opts.workspaceDir);
+    const effectiveConfig = configLoad.ok ? configLoad.effective : configLoad.defaults;
     // Allow the caller's adapter to resolve real artifactIds (needed by
     // test-double adapters whose scripted outputs must match store-assigned IDs).
     opts.onStoreReady?.(artifactStore);
@@ -282,7 +287,7 @@ export async function runRuleHostPipeline(opts: RuleHostPipelineOptions): Promis
       scribe: opts.runtimeAdapter,
       evaluator: opts.runtimeAdapter,
     };
-    const runnerOptsFor = (adapter: PDRuntimeAdapter) => ({ owner, runtimeKind: adapter.kind(), pollIntervalMs, timeoutMs });
+    const runnerOptsFor = (adapter: PDRuntimeAdapter) => ({ owner, runtimeKind: adapter.kind(), pollIntervalMs, timeoutMs, effectiveConfig });
 
     // ── Stage: pain lookup ──
     // Find a dreamer task already seeded for this pain (the pain→dreamer bridge

package/tests/commands/demo-story-a.test.ts

@@ -238,6 +238,69 @@ describe('pd demo story-a CLI', () => {
     expect(parsed.narrative).toContain('[SIMULATED]');
     expect(parsed.narrative).toContain('[REAL]');
   });
+  // ── Demo isolation (2026-08-19): demo must not pollute real PD workspaces ──
+
+  it('refuses to write into a workspace that already contains PD state (default)', async () => {
+    const existing = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-demo-isolation-'));
+    try {
+      fs.mkdirSync(path.join(existing, '.pd'), { recursive: true });
+      fs.writeFileSync(path.join(existing, '.pd', 'state.db'), '');
+
+      await handleDemoStoryA({ workspace: existing, json: true });
+
+      expect(process.exitCode).toBe(1);
+      const output = stdoutSpy.mock.calls.map(c => c[0]).join('');
+      const parsed = JSON.parse(output);
+      expect(parsed.status).toBe('refused');
+      expect(parsed.refusal.reason).toBe('demo_write_to_existing_workspace');
+      expect(parsed.refusal.nextAction).toContain('--allow-demo-write-to-existing-workspace');
+      // cli-5: no mutation on the refused path — the marker file is untouched.
+      const stat = fs.statSync(path.join(existing, '.pd', 'state.db'));
+      expect(stat.size).toBe(0);
+    } finally {
+      fs.rmSync(existing, { recursive: true, force: true });
+    }
+  });
+
+  it('text mode refusal points at the override flag', async () => {
+    const existing = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-demo-isolation-'));
+    try {
+      fs.mkdirSync(path.join(existing, '.pd'), { recursive: true });
+      fs.writeFileSync(path.join(existing, '.pd', 'state.db'), '');
+
+      await handleDemoStoryA({ workspace: existing });
+
+      expect(process.exitCode).toBe(1);
+      const output = stderrSpy.mock.calls.map(c => c[0]).join('');
+      expect(output).toContain('existing PD workspace');
+      expect(output).toContain('--allow-demo-write-to-existing-workspace');
+    } finally {
+      fs.rmSync(existing, { recursive: true, force: true });
+    }
+  });
+
+  it('developer override allows writing into the existing workspace with origin:demo provenance', async () => {
+    const existing = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-demo-override-'));
+    try {
+      fs.mkdirSync(path.join(existing, '.pd'), { recursive: true });
+      fs.writeFileSync(path.join(existing, '.pd', 'config.yaml'), 'features: {}');
+
+      await handleDemoStoryA({ workspace: existing, json: true, allowDemoWriteToExistingWorkspace: true });
+
+      const output = stdoutSpy.mock.calls.map(c => c[0]).join('');
+      const parsed = JSON.parse(output);
+      expect(parsed.status).not.toBe('refused');
+      const db = new Database(path.join(existing, '.pd', 'state.db'), { readonly: true });
+      const rows = db.prepare('SELECT content_json FROM pi_artifacts').all() as { content_json: string }[];
+      db.close();
+      expect(rows.length).toBeGreaterThan(0);
+      for (const row of rows) {
+        expect(JSON.parse(row.content_json).origin).toBe('demo');
+      }
+    } finally {
+      fs.rmSync(existing, { recursive: true, force: true });
+    }
+  });
 });
 
 describe('cleanupTempWorkspace', () => {

package/tests/commands/runtime-compatibility-scan.test.ts

@@ -0,0 +1,146 @@
+/**
+ * runtime compatibility-scan tests — pd runtime compatibility-scan (P1-3).
+ *
+ * Real persisted-workspace fixtures (SqliteConnection + activation store) —
+ * no DB mocks, the production read path is exercised end to end (EP-09).
+ *
+ * Covers:
+ *   - SCAN-01: clean RuleContextV2-only active rule → exit 0, status clean (cli-1/cli-6)
+ *   - SCAN-02: active rule reading session.recentThinking → exit 1,
+ *     reason legacy_rule_contract_dependency, remediation names the rule (cli-6)
+ *   - SCAN-03: workspace without state.db → exit 0, status no_state_db
+ *   - SCAN-04: --json emits exactly one parseable JSON object (cli-1)
+ *   - SCAN-05: command wiring — real Commander registration (cli-7)
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import { SqliteConnection, SqliteActivationStateStore } from '@principles/core/runtime-v2';
+import { handleRuntimeCompatibilityScan } from '../../src/commands/runtime-compatibility-scan.js';
+
+const LEGACY_CODE = `
+function evaluate(input, helpers) {
+  if (input.session && input.session.recentThinking === true) {
+    return { decision: 'block', matched: true };
+  }
+  return { decision: 'allow', matched: false };
+}
+`;
+
+const CLEAN_CODE = `
+function evaluate(input, helpers) {
+  var h = input.context && input.context.history;
+  return { decision: 'allow', matched: false };
+}
+`;
+
+let tempWorkspaceDir: string;
+let conn: SqliteConnection;
+
+beforeEach(() => {
+  vi.spyOn(console, 'log').mockImplementation(() => undefined);
+  vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  process.exitCode = undefined;
+  tempWorkspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-compat-cmd-'));
+  conn = new SqliteConnection(tempWorkspaceDir);
+  conn.getDb();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  try { conn?.close(); } catch { /* best-effort */ }
+  try { fs.rmSync(tempWorkspaceDir, { recursive: true, force: true }); } catch { /* Windows */ }
+});
+
+async function seedActiveRule(artifactId: string, ruleId: string, implementationCode: string): Promise<void> {
+  const now = new Date().toISOString();
+  conn.getDb().prepare(`
+    INSERT INTO pi_artifacts (artifact_id, artifact_kind, source_task_id, source_principle_id, source_rule_id, lineage_artifact_ids, validation_status, content_json, created_at, updated_at)
+    VALUES (?, 'rule', ?, ?, ?, '[]', 'validated', ?, ?, ?)
+  `).run(artifactId, `task-${artifactId}`, `principle-${ruleId}`, ruleId, JSON.stringify({ ruleId, implementationCode }), now, now);
+  await new SqliteActivationStateStore(conn).recordActivation({
+    activationId: `act-${artifactId}`,
+    idempotencyKey: `${artifactId}::code_tool_hook`,
+    artifactId,
+    channel: 'code_tool_hook',
+    action: 'code_tool_hook_live_activate',
+    targetRef: `impl://${ruleId}`,
+    activatedAt: now,
+    deactivatedAt: null,
+  });
+}
+
+function capturedStdout(): string {
+  const calls = (console.log as unknown as { mock: { calls: unknown[][] } }).mock.calls;
+  return calls.map(c => String(c[0] ?? '')).join('\n');
+}
+
+describe('pd runtime compatibility-scan', () => {
+  it('SCAN-01: clean current-contract rule exits 0 with status clean', async () => {
+    await seedActiveRule('art-clean', 'rule-clean', CLEAN_CODE);
+    await handleRuntimeCompatibilityScan({ workspace: tempWorkspaceDir, json: true });
+    expect(process.exitCode).toBeUndefined();
+    const parsed = JSON.parse(capturedStdout()) as Record<string, unknown>;
+    expect(parsed['status']).toBe('clean');
+    expect(parsed['ok']).toBe(true);
+    expect(parsed['findings']).toEqual([]);
+  });
+
+  it('SCAN-02: legacy recentThinking rule exits 1 with structured reason + remediation', async () => {
+    await seedActiveRule('art-legacy', 'rule-real-diagnosis-first', LEGACY_CODE);
+    await handleRuntimeCompatibilityScan({ workspace: tempWorkspaceDir, json: true });
+    expect(process.exitCode).toBe(1);
+    const parsed = JSON.parse(capturedStdout()) as Record<string, unknown>;
+    expect(parsed['ok']).toBe(false);
+    expect(parsed['status']).toBe('legacy_dependency');
+    expect(parsed['reason']).toBe('legacy_rule_contract_dependency');
+    const findings = parsed['findings'] as Array<Record<string, unknown>>;
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ symbol: 'recentThinking', ruleId: 'rule-real-diagnosis-first' });
+    const remediation = parsed['remediation'] as string;
+    expect(remediation).toContain('rule-real-diagnosis-first');
+    expect(remediation).toContain('igrate or deactivate');
+  });
+
+  it('SCAN-03: workspace without state.db exits 0 with status no_state_db', async () => {
+    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-compat-empty-cmd-'));
+    try {
+      await handleRuntimeCompatibilityScan({ workspace: emptyDir, json: true });
+      expect(process.exitCode).toBeUndefined();
+      const parsed = JSON.parse(capturedStdout()) as Record<string, unknown>;
+      expect(parsed['status']).toBe('no_state_db');
+      expect(parsed['ok']).toBe(true);
+      // Side-effect-free: the scan must not create a state.db (cli-5).
+      expect(fs.existsSync(path.join(emptyDir, '.pd', 'state.db'))).toBe(false);
+    } finally {
+      fs.rmSync(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  it('SCAN-04: --json stdout is exactly one parseable JSON object (cli-1)', async () => {
+    await seedActiveRule('art-clean2', 'rule-clean2', CLEAN_CODE);
+    await handleRuntimeCompatibilityScan({ workspace: tempWorkspaceDir, json: true });
+    const out = capturedStdout().trim();
+    expect(out.startsWith('{')).toBe(true);
+    expect(out.endsWith('}')).toBe(true);
+    expect(() => JSON.parse(out)).not.toThrow();
+    expect((out.match(/\{/g) ?? []).length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('SCAN-05: command is registered on a real Commander program (cli-7)', async () => {
+    const { Command } = await import('commander');
+    const { registerRuntimeCompatibilityScanCommand } = await import('../../src/commands/runtime-compatibility-scan.js');
+    const program = new Command();
+    program.name('pd').exitOverride();
+    const runtimeCmd = program.command('runtime').description('Runtime inspection and health checks');
+    registerRuntimeCompatibilityScanCommand(runtimeCmd);
+    const scanCmd = runtimeCmd.commands.find(c => c.name() === 'compatibility-scan');
+    expect(scanCmd).toBeDefined();
+    expect(scanCmd?.description()).toContain('retired RuleHost contract');
+    // Flag wiring: -w/--workspace and --json registered; no mutating flags exist.
+    expect(scanCmd?.options.map(o => o.long)).toContain('--workspace');
+    expect(scanCmd?.options.map(o => o.long)).toContain('--json');
+  });
+});

package/tests/commands/runtime-init-empty-workspace.test.ts

@@ -18,7 +18,9 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import * as yaml from 'js-yaml';
 import Database from 'better-sqlite3';
+import { validatePdConfig } from '@principles/core/runtime-v2';
 import { buildRuntimeInitOutput } from '../../src/commands/runtime-init.js';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
@@ -190,6 +192,26 @@ describe('pd runtime init — empty workspace integration', () => {
         db.close();
       }
     });
+
+    // ── P0: config.yaml scaffolding (Issue 1b) ────────────────────────────────
+
+    it('creates .pd/config.yaml with version 1 and workspace.default set', () => {
+      buildRuntimeInitOutput(tmpDir, true);
+      const configPath = path.join(tmpDir, '.pd', 'config.yaml');
+      expect(fs.existsSync(configPath)).toBe(true);
+      const parsed = yaml.load(fs.readFileSync(configPath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+      const obj = parsed as { version?: unknown; workspace?: { default?: unknown } };
+      expect(obj.version).toBe(1);
+      expect(obj.workspace?.default).toBe(path.resolve(tmpDir));
+    });
+
+    it('generated config.yaml passes validatePdConfig (round-trip)', () => {
+      buildRuntimeInitOutput(tmpDir, true);
+      const configPath = path.join(tmpDir, '.pd', 'config.yaml');
+      const parsed: unknown = yaml.load(fs.readFileSync(configPath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+      const result = validatePdConfig(parsed);
+      expect(result.ok).toBe(true);
+    });
   });
 
   // ── EMPTY-02: idempotency ──────────────────────────────────────────────────
@@ -215,6 +237,12 @@ describe('pd runtime init — empty workspace integration', () => {
       // Table set should be unchanged
       const tables2 = getTableNames(trajDbPath);
       expect(tables2).toEqual(tables1);
+
+      // config.yaml is preserved: second run reports skipped, content unchanged
+      expect(output2.config?.status).toBe('skipped');
+      const configPath = path.join(tmpDir, '.pd', 'config.yaml');
+      const config1 = fs.readFileSync(configPath, 'utf8');
+      expect(fs.readFileSync(configPath, 'utf8')).toBe(config1);
     });
 
     it('dry-run after confirm does not modify existing DBs', () => {

package/tests/commands/runtime-init.test.ts

@@ -40,10 +40,14 @@ vi.mock('principles-disciple', () => ({
   initWorkflowSchema: mockState.initWorkflowSchema,
 }));
 
-vi.mock('@principles/core/runtime-v2', () => ({
-  SqliteConnection: mockState.sqliteConnectionCtor,
-  SchemaConformanceReadModel: mockState.schemaConformanceCtor,
-}));
+vi.mock('@principles/core/runtime-v2', async () => {
+  const actual = await vi.importActual<typeof import('@principles/core/runtime-v2')>('@principles/core/runtime-v2');
+  return {
+    ...actual,
+    SqliteConnection: mockState.sqliteConnectionCtor,
+    SchemaConformanceReadModel: mockState.schemaConformanceCtor,
+  };
+});
 
 vi.mock('../../src/resolve-workspace.js', () => ({
   resolveWorkspaceDir: mockState.resolveWorkspaceDir,
@@ -343,4 +347,67 @@ describe('pd runtime init', () => {
       } finally { rmTmpDir(tmp); }
     });
   });
+
+  // ── INIT-07: config.yaml scaffolding (P0: runtime discovery) ───────────────
+
+  describe('INIT-07: config.yaml scaffolding', () => {
+    it('dry-run reports config.yaml as skipped without writing the file', () => {
+      const tmp = mkTmpDir();
+      try {
+        const output = buildRuntimeInitOutput(tmp, false);
+        expect(output.config).toBeDefined();
+        expect(output.config?.status).toBe('skipped');
+        expect(fs.existsSync(path.join(tmp, '.pd', 'config.yaml'))).toBe(false);
+      } finally { rmTmpDir(tmp); }
+    });
+
+    it('--confirm writes a valid config.yaml with version and workspace.default', async () => {
+      const tmp = mkTmpDir();
+      try {
+        const output = buildRuntimeInitOutput(tmp, true);
+        expect(output.config?.status).toBe('initialized');
+        const configPath = path.join(tmp, '.pd', 'config.yaml');
+        expect(fs.existsSync(configPath)).toBe(true);
+        const yaml = (await import('js-yaml')).default;
+        const raw = fs.readFileSync(configPath, 'utf8');
+        const parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+        expect(typeof parsed).toBe('object');
+        const obj = parsed as { version?: unknown; workspace?: { default?: unknown }; features?: unknown };
+        expect(obj.version).toBe(1);
+        expect(obj.workspace?.default).toBe(path.resolve(tmp));
+        expect(obj.features).toBeDefined();
+        expect(Object.keys(obj.features as Record<string, unknown>).length).toBeGreaterThan(0);
+      } finally { rmTmpDir(tmp); }
+    });
+
+    it('round-trip: generated config passes validatePdConfig', async () => {
+      const tmp = mkTmpDir();
+      try {
+        buildRuntimeInitOutput(tmp, true);
+        const configPath = path.join(tmp, '.pd', 'config.yaml');
+        const yaml = (await import('js-yaml')).default;
+        const { validatePdConfig } = await import('@principles/core/runtime-v2');
+        const parsed: unknown = yaml.load(fs.readFileSync(configPath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+        const result = validatePdConfig(parsed);
+        expect(result.ok).toBe(true);
+      } finally { rmTmpDir(tmp); }
+    });
+
+    it('--confirm skips when config.yaml already exists (preserves user file)', () => {
+      const tmp = mkTmpDir();
+      try {
+        // Pre-create a user-modified config.yaml
+        const configDir = path.join(tmp, '.pd');
+        fs.mkdirSync(configDir, { recursive: true });
+        const userConfig = '# user config\nversion: 1\n';
+        fs.writeFileSync(path.join(configDir, 'config.yaml'), userConfig, 'utf8');
+
+        const output = buildRuntimeInitOutput(tmp, true);
+        expect(output.config?.status).toBe('skipped');
+        expect(output.config?.warnings.some(w => w.includes('already exists'))).toBe(true);
+        // Content must be preserved
+        expect(fs.readFileSync(path.join(configDir, 'config.yaml'), 'utf8')).toBe(userConfig);
+      } finally { rmTmpDir(tmp); }
+    });
+  });
 });

package/tests/e2e/cross-package-acceptance.test.ts

@@ -416,8 +416,8 @@ describe('Cross-Package Acceptance Test (PRI-408 P1/P2 fixes) — unsplippable c
     // undefined (no block) for shadow activations, even for /etc/passwd.
     const makeRuleHostInput = (targetPath: string): RuleHostInput => ({
       action: { toolName: 'write_file', normalizedPath: targetPath, paramsSummary: { path: targetPath } },
-      workspace: { isRiskPath: targetPath.startsWith('/etc'), planStatus: 'NONE', hasPlanFile: false },
-      session: { currentGfi: 0, recentThinking: false },
+      workspace: { isRiskPath: targetPath.startsWith('/etc') },
+      session: { currentGfi: 0 },
       evolution: { epTier: 0 },
       derived: { estimatedLineChanges: 1, bashRisk: 'safe' },
     });

package/tests/services/demo-rule-compiler.test.ts

@@ -108,8 +108,8 @@ function makeRuleHostInput(estimatedLineChanges = 0): RuleHostInput {
       normalizedPath: '/workspace/a.ts',
       paramsSummary: {},
     },
-    workspace: { isRiskPath: false, planStatus: 'READY', hasPlanFile: true },
-    session: { currentGfi: 0, recentThinking: true },
+    workspace: { isRiskPath: false },
+    session: { currentGfi: 0 },
     evolution: { epTier: 0 },
     derived: { estimatedLineChanges, bashRisk: 'safe' },
   };