@plainconceptsplatform/agent-harness 3.0.3 → 3.1.1

package/cli/steps/metadata/index.js

@@ -1,112 +1,115 @@
-import { execa } from 'execa'
-import fse from 'fs-extra'
-import path from 'path'
-import { createRequire } from 'node:module'
-import { header, success, warn } from '../../utils/exec.js'
-import { configPath } from '../../utils/paths.js'
-
-const require = createRequire(import.meta.url)
-const { version: harnessVersion } = require('../../../package.json')
-
-function clampConcurrency(n) {
-  const v = Number(n)
-  if (!Number.isFinite(v)) return 3
-  return Math.min(5, Math.max(1, Math.round(v)))
-}
-
-async function detectOpencodeVersion() {
-  try {
-    const result = await execa('opencode', ['--version'], { reject: false })
-    if (result.exitCode !== 0) return null
-    const output = (result.stdout || result.stderr || '').trim()
-    return output || null
-  } catch {
-    return null
-  }
-}
-
-export async function writeHarnessConfig(data) {
-  header('Step 10, Writing onboarding metadata')
-
-  const opencodeVersion = await detectOpencodeVersion()
-  const cwd = data.cwd ?? process.cwd()
-  const target = configPath(cwd)
-
-  // Read the existing file so load-bearing config (models, maxConcurrent)
-  // is preserved across metadata refreshes when not explicitly provided.
-  const existing = await fse.readJson(target).catch(() => null)
-
-  const selectedModels = Object.fromEntries(
-    Object.entries({
-      plan: data.planModel,
-      build: data.buildModel,
-      fast: data.fastModel,
-    }).filter(([, value]) => value)
-  )
-  const models = Object.keys(selectedModels).length > 0
-    ? { ...existing?.models, ...selectedModels }
-    : existing?.models ?? null
-  const maxConcurrent = clampConcurrency(data.maxConcurrentAgents ?? existing?.agents?.maxConcurrent ?? 3)
-
-  const optionalTools = data.optionalTools ?? existing?.tools ?? {}
-  const { caveman: _caveman, ...existingTools } = existing?.tools ?? {}
-  const tools = {
-    rtk: !!(optionalTools.rtk?.optedIn ?? optionalTools.rtk),
-    quota: !!(optionalTools.quota?.optedIn ?? optionalTools.quota),
-    simpleEnglish: !!(
-      optionalTools.simpleEnglish?.optedIn ?? optionalTools.simpleEnglish ??
-      optionalTools.caveman?.optedIn ?? optionalTools.caveman
-    ),
-    codegraph: !!(optionalTools.codegraph?.optedIn ?? optionalTools.codegraph),
-    memory: !!(optionalTools.memory?.optedIn ?? optionalTools.memory),
-    // humanizer was missing here, so a selection never survived a metadata
-    // write and patchGuardrails always saw it as off, leaving its marker
-    // section empty however the project was actually set up.
-    humanizer: !!(optionalTools.humanizer?.optedIn ?? optionalTools.humanizer),
-  }
-
-  const payload = {
-    ...existing,
-    version: 2,
-    generatedAt: new Date().toISOString(),
-    harnessVersion,
-    opencodeVersion,
-
-    platform: {
-      ...existing?.platform,
-      backlog: data.backlogPlatform ?? 'none',
-      repo: data.repoPlatform ?? 'none',
-    },
-
-    ...(models ? { models } : {}),
-
-    agents: {
-      ...existing?.agents,
-      maxConcurrent,
-    },
-
-    source: {
-      ...existing?.source,
-      mode: data.sourceMode ?? 'current',
-      roots: data.sourceRoots ?? [],
-    },
-
-    tools: { ...existingTools, ...tools },
-
-    preexisting: {
-      ...existing?.preexisting,
-      design: !!data.hasDesign,
-      architecture: !!data.hasArchitecture,
-      openspec: !!data.hasOpenspec,
-    },
-  }
-
-  try {
-    await fse.ensureDir(path.dirname(target))
-    await fse.writeJson(target, payload, { spaces: 2 })
-    success('Wrote .opencode/harness.json')
-    if (!opencodeVersion) warn('Could not detect opencode version, saved as null')
-  } catch (err) {
-    warn(`Could not write onboarding metadata: ${err.message}`)
-  }
-}
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'path'
+import { createRequire } from 'node:module'
+import { header, success, warn } from '../../utils/exec.js'
+import { configPath } from '../../utils/paths.js'
+
+const require = createRequire(import.meta.url)
+const { version: harnessVersion } = require('../../../package.json')
+
+function clampConcurrency(n) {
+  const v = Number(n)
+  if (!Number.isFinite(v)) return 3
+  return Math.min(5, Math.max(1, Math.round(v)))
+}
+
+async function detectOpencodeVersion() {
+  try {
+    const result = await execa('opencode', ['--version'], { reject: false })
+    if (result.exitCode !== 0) return null
+    // `opencode --version` prints "opencode v2.0.22" on some builds and "2.0.22" on others;
+    // record the bare version so the field does not churn between machines.
+    const output = (result.stdout || result.stderr || '').trim()
+    return output.match(/\d+\.\d+\.\d+[\w.-]*/)?.[0] ?? (output || null)
+  } catch {
+    return null
+  }
+}
+
+export async function writeHarnessConfig(data) {
+  header('Step 10, Writing onboarding metadata')
+
+  const opencodeVersion = await detectOpencodeVersion()
+  const cwd = data.cwd ?? process.cwd()
+  const target = configPath(cwd)
+
+  // Read the existing file so load-bearing config (models, maxConcurrent)
+  // is preserved across metadata refreshes when not explicitly provided.
+  const existing = await fse.readJson(target).catch(() => null)
+
+  const selectedModels = Object.fromEntries(
+    Object.entries({
+      plan: data.planModel,
+      build: data.buildModel,
+      fast: data.fastModel,
+    }).filter(([, value]) => value)
+  )
+  const models = Object.keys(selectedModels).length > 0
+    ? { ...existing?.models, ...selectedModels }
+    : existing?.models ?? null
+  const maxConcurrent = clampConcurrency(data.maxConcurrentAgents ?? existing?.agents?.maxConcurrent ?? 3)
+
+  const optionalTools = data.optionalTools ?? existing?.tools ?? {}
+  const { caveman: _caveman, ...existingTools } = existing?.tools ?? {}
+  const tools = {
+    rtk: !!(optionalTools.rtk?.optedIn ?? optionalTools.rtk),
+    quota: !!(optionalTools.quota?.optedIn ?? optionalTools.quota),
+    simpleEnglish: !!(
+      optionalTools.simpleEnglish?.optedIn ?? optionalTools.simpleEnglish ??
+      optionalTools.caveman?.optedIn ?? optionalTools.caveman
+    ),
+    codegraph: !!(optionalTools.codegraph?.optedIn ?? optionalTools.codegraph),
+    memory: !!(optionalTools.memory?.optedIn ?? optionalTools.memory),
+    // humanizer was missing here, so a selection never survived a metadata
+    // write and patchGuardrails always saw it as off, leaving its marker
+    // section empty however the project was actually set up.
+    humanizer: !!(optionalTools.humanizer?.optedIn ?? optionalTools.humanizer),
+  }
+
+  const payload = {
+    ...existing,
+    // Never lower a schema version a repository already records.
+    version: Math.max(2, Number(existing?.version) || 0),
+    generatedAt: new Date().toISOString(),
+    harnessVersion,
+    opencodeVersion,
+
+    platform: {
+      ...existing?.platform,
+      backlog: data.backlogPlatform ?? 'none',
+      repo: data.repoPlatform ?? 'none',
+    },
+
+    ...(models ? { models } : {}),
+
+    agents: {
+      ...existing?.agents,
+      maxConcurrent,
+    },
+
+    source: {
+      ...existing?.source,
+      mode: data.sourceMode ?? 'current',
+      roots: data.sourceRoots ?? [],
+    },
+
+    tools: { ...existingTools, ...tools },
+
+    preexisting: {
+      ...existing?.preexisting,
+      design: !!data.hasDesign,
+      architecture: !!data.hasArchitecture,
+      openspec: !!data.hasOpenspec,
+    },
+  }
+
+  try {
+    await fse.ensureDir(path.dirname(target))
+    await fse.writeJson(target, payload, { spaces: 2 })
+    success('Wrote .opencode/harness.json')
+    if (!opencodeVersion) warn('Could not detect opencode version, saved as null')
+  } catch (err) {
+    warn(`Could not write onboarding metadata: ${err.message}`)
+  }
+}

package/cli/steps/models/write.js

@@ -1,34 +1,38 @@
-import fse from 'fs-extra'
-import { applyEdits, modify, parse } from 'jsonc-parser'
-import path from 'path'
-import { success, warn } from '../../utils/exec.js'
-
-/**
- * Writes the selected build model as the default model in opencode.jsonc.
- * Per-tier models (plan/build/fast) are recorded in harness.json (models)
- * by the metadata step, then consumed by the agent-variant generator and /plan-apply.
- *
- * opencode tolerates JSONC (comments, trailing commas) in its config, so this
- * must not use readJson/writeJson: a strict parse crashes on valid configs and
- * a strict rewrite deletes user comments. jsonc-parser edits only the `model`
- * key and preserves the rest of the file byte-for-byte.
- */
-export async function writeModelsToConfigs({ buildModel, cwd = process.cwd() }) {
-  const opencodeJsonPath = path.join(cwd, 'opencode.jsonc')
-  if (!await fse.pathExists(opencodeJsonPath)) return
-
-  const text = await fse.readFile(opencodeJsonPath, 'utf-8')
-  const errors = []
-  parse(text, errors)
-  if (errors.length > 0) {
-    warn('opencode.jsonc could not be parsed: leaving it untouched. Set "model" manually.')
-    return
-  }
-
-  // `undefined` removes the key; a string value sets it.
-  const edits = modify(text, ['model'], buildModel || undefined, {
-    formattingOptions: { insertSpaces: true, tabSize: 2 },
-  })
-  await fse.writeFile(opencodeJsonPath, applyEdits(text, edits), 'utf-8')
-  if (buildModel) success(`default model -> ${buildModel} (written to opencode.jsonc)`)
-}
+import fse from 'fs-extra'
+import { applyEdits, modify, parse } from 'jsonc-parser'
+import path from 'path'
+import { success, warn } from '../../utils/exec.js'
+
+/**
+ * Writes the selected build model as the default model in opencode.jsonc.
+ * Per-tier models (plan/build/fast) are recorded in harness.json (models)
+ * by the metadata step, then consumed by the agent-variant generator and /plan-apply.
+ *
+ * opencode tolerates JSONC (comments, trailing commas) in its config, so this
+ * must not use readJson/writeJson: a strict parse crashes on valid configs and
+ * a strict rewrite deletes user comments. jsonc-parser edits only the `model`
+ * key and preserves the rest of the file byte-for-byte.
+ */
+export async function writeModelsToConfigs({ buildModel, keepExisting = false, cwd = process.cwd() }) {
+  const opencodeJsonPath = path.join(cwd, 'opencode.jsonc')
+  if (!await fse.pathExists(opencodeJsonPath)) return
+
+  const text = await fse.readFile(opencodeJsonPath, 'utf-8')
+  const errors = []
+  parse(text, errors)
+  if (errors.length > 0) {
+    warn('opencode.jsonc could not be parsed: leaving it untouched. Set "model" manually.')
+    return
+  }
+
+  // A model the repository already chose is its decision, not the wizard's: `update` used to
+  // reset a deliberately pinned default to the build tier in every consumer it ran in.
+  if (keepExisting && typeof parse(text)?.model === 'string') return
+
+  // `undefined` removes the key; a string value sets it.
+  const edits = modify(text, ['model'], buildModel || undefined, {
+    formattingOptions: { insertSpaces: true, tabSize: 2 },
+  })
+  await fse.writeFile(opencodeJsonPath, applyEdits(text, edits), 'utf-8')
+  if (buildModel) success(`default model -> ${buildModel} (written to opencode.jsonc)`)
+}

package/cli/steps/optimization/index.js

@@ -4,7 +4,6 @@ import fse from 'fs-extra'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import { code, commandExists, header, info, loading, success, warn } from '../../utils/exec.js'
-import { installQuota } from './quota.js'
 import { installSimpleEnglish } from './simple-english.js'
 import { installCodegraph } from './codegraph.js'
 import { installMemory } from './memory.js'
@@ -92,10 +91,6 @@ export async function tokenOptimizationStep(options = {}) {
     ? await checkRtk({ skipHeader: true, skipPrompt: true })
     : { optedIn: false, checked: false, available: false }
 
-  const quota = has('quota')
-    ? await installQuota({ skipHeader: true, skipPrompt: true })
-    : { optedIn: false, installed: false }
-
   const simpleEnglish = has('simpleEnglish')
     ? await installSimpleEnglish({
       skipHeader: true,
@@ -132,7 +127,7 @@ export async function tokenOptimizationStep(options = {}) {
   if (selected.length === 0) warn('No token optimization tools selected')
   else success('Token optimization step completed')
 
-  return { rtk, quota, simpleEnglish, codegraph, memory, humanizer }
+  return { rtk, simpleEnglish, codegraph, memory, humanizer }
 }
 
 async function syncSkillsLock() {

package/cli/utils/paths.js

@@ -1,67 +1,80 @@
-import os from 'node:os'
-import path from 'node:path'
-
-/**
- * Every harness path that lands in a consumer repo, in one place.
- *
- * These filenames are a contract with every repo the harness has been
- * installed into: the CLI writes them, and the opencode plugins shipped in
- * harness/.opencode/plugins/ read them back at runtime. Changing a name
- * here means changing it in that payload too, or the plugins go blind.
- *
- * They are deliberately named for the harness rather than for the CLI, so a
- * future rename of the package does not become a rename of the on-disk state.
- */
-export const OPENCODE_DIR = '.opencode'
-
-/** Project config written by the metadata step. */
-export const CONFIG_FILE = 'harness.json'
-
-/** Per-developer model override, gitignored, never committed. */
-export const USER_CONFIG_FILE = 'harness.user.json'
-
-/** Hashes of every managed file, so `update` can detect local edits. */
-export const MANIFEST_FILE = 'harness-managed.json'
-
-/** Live subagent wave state, owned by the pc-subagent-monitor plugin. */
-export const RUN_STATE_FILE = 'harness-run.json'
-
-/** Names `.opencode/.gitignore` must cover. Mirrored in content/.opencode/_gitignore. */
-export const IGNORED_ENTRIES = [
-  'node_modules',
-  RUN_STATE_FILE,
-  USER_CONFIG_FILE,
-  MANIFEST_FILE,
-  'source-roots.json',
-  '*-engineer.*.md',
-  // Regenerated from fullstack-engineer.md by pc-subagent-tiers every startup.
-  'agents/build.md',
-  'agents/plan.md',
-]
-
-export function configPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, CONFIG_FILE)
-}
-
-export function userConfigPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, USER_CONFIG_FILE)
-}
-
-export function manifestPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, MANIFEST_FILE)
-}
-
-/** Cross-run models cache, keyed to the CLI rather than to any one repo. */
-export function modelsCacheDir() {
-  return path.join(os.homedir(), '.config', 'agent-harness')
-}
-
-/**
- * Filenames written by opencode-onboard v1.x. Only used to detect a v1 repo
- * and refuse to half-patch it: nothing reads their contents.
- */
-export const LEGACY_CONFIG_FILES = [
-  'opencode-onboard.json',
-  'opencode-onboard.user.json',
-  'opencode-onboard-managed.json',
-]
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * Every harness path that lands in a consumer repo, in one place.
+ *
+ * These filenames are a contract with every repo the harness has been
+ * installed into: the CLI writes them, and the opencode plugins shipped in
+ * harness/.opencode/plugins/ read them back at runtime. Changing a name
+ * here means changing it in that payload too, or the plugins go blind.
+ *
+ * They are deliberately named for the harness rather than for the CLI, so a
+ * future rename of the package does not become a rename of the on-disk state.
+ */
+export const OPENCODE_DIR = '.opencode'
+
+/** Project config written by the metadata step. */
+export const CONFIG_FILE = 'harness.json'
+
+/** Per-developer model override, gitignored, never committed. */
+export const USER_CONFIG_FILE = 'harness.user.json'
+
+/** Hashes of every managed file, so `update` can detect local edits. */
+export const MANIFEST_FILE = 'harness-managed.json'
+
+/** Live subagent wave state, owned by the pc-subagent-monitor plugin. */
+export const RUN_STATE_FILE = 'harness-run.json'
+
+/** Names `.opencode/.gitignore` must cover. Mirrored in content/.opencode/_gitignore. */
+export const IGNORED_ENTRIES = [
+  'node_modules',
+  RUN_STATE_FILE,
+  USER_CONFIG_FILE,
+  MANIFEST_FILE,
+  'source-roots.json',
+  '*-engineer.*.md',
+  // Regenerated from fullstack-engineer.md by pc-subagent-tiers every startup.
+  'agents/build.md',
+  'agents/plan.md',
+]
+
+/**
+ * Files the harness shipped and has since retired. `update` deletes them, because a skill or
+ * command left behind keeps being offered to agents long after the procedure it describes is
+ * gone. pc-ops-evidence wrote a capturePlan for a CI workflow that no longer exists; the
+ * verification plan from pc-repo-verify is what the evidence workflow replays now.
+ */
+export const RETIRED_PATHS = [
+  '.agents/skills/pc-ops-evidence',
+  '.agents/skills/pc-make-evidence-scaffold',
+  '.opencode/commands/ops-evidence.md',
+  '.opencode/commands/make-evidence-scaffold.md',
+]
+
+export function configPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, CONFIG_FILE)
+}
+
+export function userConfigPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, USER_CONFIG_FILE)
+}
+
+export function manifestPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, MANIFEST_FILE)
+}
+
+/** Cross-run models cache, keyed to the CLI rather than to any one repo. */
+export function modelsCacheDir() {
+  return path.join(os.homedir(), '.config', 'agent-harness')
+}
+
+/**
+ * Filenames written by opencode-onboard v1.x. Only used to detect a v1 repo
+ * and refuse to half-patch it: nothing reads their contents.
+ */
+export const LEGACY_CONFIG_FILES = [
+  'opencode-onboard.json',
+  'opencode-onboard.user.json',
+  'opencode-onboard-managed.json',
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "description": "Installs the Plain Concepts Platform Harness into any codebase, and keeps it up to date. Wires OpenCode, OpenSpec, codegraph, and agentmemory into a multi-agent workflow that runs on native parallel subagents.",
   "keywords": [
     "opencode",

package/skills/pc-plan-goal/SKILL.md

@@ -64,7 +64,11 @@ Tick `propose` when the proposal commit exists.
 
 Load `pc-plan-apply` in autonomous mode with `start_from: load-plan`. It owns worker resolution, subagent waves, commits, verification, and re-waves.
 
-Require it to return every task complete and `VERIFIED`, then load `pc-repo-verify`. Tick `apply` when apply returns `VERIFIED`; tick `verify` when `pc-repo-verify` returns `PLAN_WRITTEN` or `STUB_WRITTEN`.
+Require it to return every task complete and `VERIFIED`, then load `pc-repo-verify`. Tick `apply` when apply returns `VERIFIED`. When `pc-repo-verify` returns `PLAN_WRITTEN` or `STUB_WRITTEN`, commit the plan, which the evidence workflow replays once the pull request merges, then tick `verify`:
+
+```bash
+git add openspec/changes/{change-id}/verification-plan.md && git commit -m "verify: {title} ({change-id})"
+```
 
 ## Phase 5: Archive