@plainconceptsplatform/agent-harness 3.0.3 → 3.1.1

package/cli/fragments/ops-evidence/gh.md

@@ -1,53 +0,0 @@
-GitHub data comes from the `gh` CLI; a page fetch of github.com is denied (pc-system-reminders). If `gh` is unavailable, skip publishing and report it; do not fail the pipeline unless the caller declared publishing a ship gate. Always pass `--repo {owner}/{repo}` (or `repos/{owner}/{repo}` for `gh api`) explicitly.
-
-Publish one status comment for every manifest. A `blocked` or `failed` manifest must include its status and reason, never a success claim.
-
-### Step 1 — Build commit-pinned repository links
-
-An embedded image must be a raw URL pinned to the commit that actually contains it, and that commit must be pushed. For each asset in `evidence.json`:
-
-```bash
-SHA="$(git log -n 1 --format=%H -- '{asset-path}')"          # the commit that added this asset
-[ -z "$SHA" ] && echo "asset not committed: {asset-path}" && exit-skip
-gh api "repos/{owner}/{repo}/contents/{asset-path}?ref=$SHA" --silent   # 404 → not pushed yet → skip embedding
-```
-
-Build a blob link for every committed manifest and asset: `https://github.com/{owner}/{repo}/blob/{SHA}/{asset-path}`. Use the raw URL only for a verified embeddable image: `https://raw.githubusercontent.com/{owner}/{repo}/{SHA}/{asset-path}`. If verification fails, include the asset path and SHA as text; never post a dead link.
-
-### Step 2 — Build the comment body with a stable marker (idempotent)
-
-Prefix the body with a hidden marker so re-runs update the same comment instead of piling on:
-
-```
-<!-- pc-visual-evidence:{change-id} -->
-<!-- pc-visual-evidence-status:{status} -->
-
-Status: `{status}`
-
-{reason?}
-
-Manifest: {commit-pinned evidence.json link}
-
-Assets: {commit-pinned asset links}
-
-{prMarkdown}
-```
-
-### Step 3 — Upsert the comment on BOTH the issue and the PR
-
-For each target number (the originating issue, and the PR number when provided), find an existing marked comment and PATCH it, else POST a new one:
-
-```bash
-# find existing
-ID="$(gh api "repos/{owner}/{repo}/issues/{number}/comments" --paginate --jq \
-  '.[] | select(.body | contains("<!-- pc-visual-evidence:{change-id} -->")) | .id' | head -1)"
-
-if [ -n "$ID" ]; then
-  gh api --method PATCH "repos/{owner}/{repo}/issues/comments/$ID" -f body="$BODY" --silent
-else
-  gh api --method POST  "repos/{owner}/{repo}/issues/{number}/comments" -f body="$BODY" --silent
-fi
-```
-
-- Text-only (no verified image, or `default` mode / nothing pushed): drop the image lines, keep the summary (tasks N/N, verification result, commits).
-- If a comment call fails: report it. Fail the run ONLY when the caller declared publishing a ship gate; otherwise continue.

package/cli/fragments/ops-evidence/jira.md

@@ -1,42 +0,0 @@
-Jira data comes from the `acli` CLI; a page fetch of atlassian.net is denied (pc-system-reminders). If `acli` is unavailable, skip publishing and report it; do not fail the pipeline unless the caller declared publishing a ship gate.
-
-Publish one status comment for every manifest. A `blocked` or `failed` manifest must include its status and reason, never a success claim.
-
-### Step 1 — Image hosting caveat
-
-Jira comments cannot embed an image from a repo blob URL, and `acli` does not upload attachments inline. Use text evidence and derive a commit-pinned repository URL from `git remote get-url origin` when possible. Otherwise include the committed asset path, branch, and SHA:
-
-```
-Screenshot committed at: {asset-path} (branch {branch}, commit {sha})
-```
-
-### Step 2 — Build the comment with a stable marker (idempotent)
-
-```
-<!-- pc-visual-evidence:{change-id} -->
-<!-- pc-visual-evidence-status:{status} -->
-
-Status: `{status}`
-
-{reason?}
-
-Manifest and assets: {commit-pinned links when available, otherwise committed paths and SHA}
-
-{prMarkdown}
-
-{image-line?}
-```
-
-### Step 3 — Upsert the comment on the issue
-
-`acli` cannot edit a comment in place, so match on the status probe rather than the change id alone. Matching the change id alone leaves a stale `blocked` comment standing after a later run succeeds:
-
-```bash
-# Skip only when this exact status is already published for this change.
-acli jira issue comment list --key {issue-key} 2>/dev/null | grep -q "pc-visual-evidence-status:{status}" \
-  || acli jira issue comment --key {issue-key} --body "$BODY"
-```
-
-When an earlier comment carries this change id with a different status, this one supersedes it: open the body with `Supersedes the earlier evidence comment for this change.` so a reader can tell which is current.
-
-- If the comment command fails: report it. Fail the run ONLY when publishing was declared a ship gate; otherwise continue.

package/cli/presets/quota.json

@@ -1,20 +0,0 @@
-{
-  "plugin": "@slkiser/opencode-quota@5.0.1",
-  "prompt": {
-    "message": "Install opencode-quota with recommended defaults?",
-    "default": true,
-    "timeoutMs": 20000
-  },
-  "defaults": {
-    "enabledProviders": "auto",
-    "formatStyle": "singleWindow",
-    "percentDisplayMode": "used",
-    "showSessionTokens": true,
-    "enableToast": false,
-    "resetNotifications": { "enabled": false },
-    "tuiCommandDisplay": "inline",
-    "tuiCompactStatus": { "enabled": false },
-    "tuiPromptBar": { "enabled": false },
-    "tuiSidebarPanel": { "enabled": true }
-  }
-}

package/cli/steps/optimization/quota.js

@@ -1,135 +0,0 @@
-import { confirm } from '@inquirer/prompts'
-import fse from 'fs-extra'
-import path from 'node:path'
-import { fileURLToPath } from 'url'
-import { applyEdits, modify, parse as parseJsonc } from 'jsonc-parser'
-import { error, header, info, loading, success, warn } from '../../utils/exec.js'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const QUOTA_PRESET_PATH = path.resolve(__dirname, '../../presets/quota.json')
-const quotaPreset = await fse.readJson(QUOTA_PRESET_PATH)
-const PLUGIN = quotaPreset.plugin
-
-export function splitPackageSpec(spec) {
-  const separator = spec.startsWith('@') ? spec.indexOf('@', 1) : spec.lastIndexOf('@')
-  if (separator === -1) return { name: spec, version: 'latest' }
-  return { name: spec.slice(0, separator), version: spec.slice(separator + 1) }
-}
-
-export async function installQuota(options = {}) {
-  if (!options.skipHeader) header('Installing opencode-quota')
-
-  let shouldInstall = true
-  if (!options.skipPrompt && process.stdin.isTTY) {
-    // Same abort-on-timeout pattern as tokenOptimizationStep: never race a
-    // live inquirer prompt, it leaks raw-mode stdin and unhandled rejections.
-    const controller = new AbortController()
-    const timer = setTimeout(() => controller.abort(), quotaPreset.prompt.timeoutMs)
-    try {
-      shouldInstall = await confirm(
-        {
-          message: quotaPreset.prompt.message,
-          default: quotaPreset.prompt.default,
-        },
-        { signal: controller.signal },
-      )
-    } catch (err) {
-      if (err.name !== 'AbortPromptError') throw err
-      shouldInstall = true
-    } finally {
-      clearTimeout(timer)
-    }
-  }
-
-  if (!shouldInstall) {
-    warn('Skipped opencode-quota installation')
-    return { optedIn: false, installed: false }
-  }
-
-  loading('configuring opencode-quota...')
-
-  try {
-    const opencodeDir = path.join(process.cwd(), '.opencode')
-    const opencodePath = path.join(process.cwd(), 'opencode.jsonc')
-    const pkgPath = path.join(opencodeDir, 'package.json')
-
-    // opencode-quota 5.x reads its settings from `opencode-quota/quota-toast.jsonc`
-    // next to the OpenCode config (project root), not from `.opencode/`. The old
-    // `.opencode/opencode-quota/quota-toast.json` is the v4 location and is migrated
-    // below so the settings actually take effect.
-    const quotaDir = path.join(process.cwd(), 'opencode-quota')
-    const quotaPath = path.join(quotaDir, 'quota-toast.jsonc')
-    const legacyQuotaPath = path.join(opencodeDir, 'opencode-quota', 'quota-toast.json')
-
-    let opencodeText = JSON.stringify({ $schema: 'https://opencode.ai/config.json' }, null, 2)
-    let opencode
-    if (await fse.pathExists(opencodePath)) {
-      const errors = []
-      opencodeText = await fse.readFile(opencodePath, 'utf-8')
-      opencode = parseJsonc(opencodeText, errors)
-      if (errors.length > 0 || !opencode || typeof opencode !== 'object' || Array.isArray(opencode)) {
-        throw new Error('opencode.jsonc could not be parsed')
-      }
-    } else {
-      opencode = { $schema: 'https://opencode.ai/config.json' }
-    }
-
-    const pkg = await fse.pathExists(pkgPath)
-      ? await fse.readJson(pkgPath)
-      : {}
-
-    // V2 configures server plugins under `plugins`. A V1 `plugin` array found
-    // here is carried over so the quota entry is not lost when the config
-    // patcher has not run first.
-    const plugins = Array.isArray(opencode.plugins)
-      ? [...opencode.plugins]
-      : Array.isArray(opencode.plugin)
-        ? [...opencode.plugin]
-        : []
-    if (!plugins.includes(PLUGIN)) {
-      plugins.push(PLUGIN)
-      opencodeText = applyEdits(opencodeText, modify(opencodeText, ['plugins'], plugins, {
-        formattingOptions: { insertSpaces: true, tabSize: 2 },
-      }))
-    }
-
-    if (!pkg.dependencies) pkg.dependencies = {}
-    const { name: pkgName, version: pkgVersion } = splitPackageSpec(PLUGIN)
-    if (pkg.dependencies[pkgName] !== pkgVersion) pkg.dependencies[pkgName] = pkgVersion
-
-    await fse.ensureDir(opencodeDir)
-    await fse.writeFile(opencodePath, opencodeText, 'utf-8')
-    await fse.writeJson(pkgPath, pkg, { spaces: 2 })
-
-    // Carry over any existing settings (new location first, then the legacy
-    // v4 file) and layer the recommended defaults on top. The edge defaults
-    // disable toasts and reset notifications and keep slash reports inline.
-    let quotaConfig = {}
-    if (await fse.pathExists(quotaPath)) {
-      quotaConfig = await fse.readJson(quotaPath)
-    } else if (await fse.pathExists(legacyQuotaPath)) {
-      quotaConfig = await fse.readJson(legacyQuotaPath)
-    }
-
-    Object.assign(quotaConfig, quotaPreset.defaults)
-
-    await fse.ensureDir(quotaDir)
-    await fse.writeJson(quotaPath, quotaConfig, { spaces: 2 })
-
-    if (await fse.pathExists(legacyQuotaPath)) {
-      await fse.remove(legacyQuotaPath)
-      const legacyDir = path.dirname(legacyQuotaPath)
-      if ((await fse.readdir(legacyDir)).length === 0) {
-        await fse.remove(legacyDir)
-      }
-      info('Moved opencode-quota settings to opencode-quota/quota-toast.jsonc')
-    }
-
-    success('opencode-quota configured (popups and notifications disabled)')
-    info('Restart OpenCode and run /quota to verify')
-    return { optedIn: true, installed: true }
-  } catch (err) {
-    error(`Failed to configure opencode-quota: ${err.message}`)
-    return { optedIn: true, installed: false }
-  }
-}

package/harness/.opencode/commands/ops-evidence.md

@@ -1,9 +0,0 @@
----
-description: Capture a screenshot (or text summary) of a completed change and post it as a comment on the originating issue or work item.
----
-
-Load the `pc-ops-evidence` skill and execute it.
-
-Input:
-
-$ARGUMENTS

package/skills/pc-ops-evidence/SKILL.md

@@ -1,131 +0,0 @@
----
-name: pc-ops-evidence
-description: Writes a capturePlan in evidence.json for the Visual Evidence CI workflow to execute on a runner with Docker and Chrome access. Load after a change is implemented. Invoked by /ops-evidence.
-license: MIT
----
-
-# Ops Evidence
-
-Write a capture plan so the Visual Evidence CI workflow can capture screenshots on a runner with full Docker and Chrome access.
-
-The agent runs inside the awf sandbox where Docker-in-Docker is unsupported and headless Chromium's sandbox is blocked by the container security policy. The agent cannot capture screenshots itself. Instead, it analyzes the diff and writes a `capturePlan` in `evidence.json`. A separate CI workflow executes the plan.
-
-## Convention
-
-Every platform project has `pnpm run dev` at root that starts the **full stack** (database + API + web). The app runs with mock auth in development mode (no real authentication needed). This is the only contract — no per-project evidence harness, fixture apps, or scenario registries.
-
-## Input
-
-The caller provides (all optional):
-- change id: locates `openspec/changes/{change-id}/` (or the archived `archive/*{change-id}/`).
-- issue / work-item ref and PR number: where to publish.
-- output mode (`default` / `push` / `pr`): whether the branch was pushed.
-- operation: `capture` (default), `publish`, or `both`.
-
-## Part 1: Capture (operation: capture / both)
-
-**Step 1: Decide whether evidence is required.** Inspect the change's diff:
-- Required when changed files include user-visible UI: `*.tsx/jsx/vue/svelte`, `*.css/scss/less`, pages, layouts, components, navigation.
-- Skipped when docs-only, internal refactor, dependency-only, test-only, backend-only.
-- Mixed or unknown: required (be safe).
-
-If skipped: write `evidence.json` with `status: "skipped"` and reason. Done.
-
-**Step 2: Discover routes from git diff.** Parse changed files to determine which routes to screenshot:
-- `pages/**/*.tsx` or `app/**/page.tsx` → extract the route path
-- `features/**/*.tsx` or `components/**/*.tsx` → screenshot the homepage and any routes that import the changed component
-- If no routes found → screenshot `/` only
-- Always include `/` (homepage) as a baseline
-
-**Step 3: Write `evidence.json` with `capturePlan`.** The agent never attempts to start the app stack or launch a browser — those always fail inside the awf sandbox. Instead, write a `capturePlan` immediately.
-
-### The `capturePlan` schema
-
-```
-capturePlan:
-  routes:           # Array of route objects to screenshot (at minimum [{ path: "/" }])
-    - path: string  # URL path, e.g. "/items/:id"
-      sampleId:     # string | "first" | "any" — how to resolve dynamic segments
-      caption:      # string — human-readable description of what this screenshot shows
-  viewports:        # Array of viewport objects
-    - width: number
-      height: number
-      label: string # "desktop" | "mobile" | custom
-  requireApi:       # boolean — true when the route needs the backend API running
-  requireLogin:     # boolean — true when the route needs authentication
-  loginMethod:      # string — "mock-sso" | "none" | custom method identifier
-  reason:           # string — why evidence was blocked and what the screenshots should show
-```
-
-### Rules for writing capturePlan
-
-1. `routes` MUST always include `{ path: "/", caption: "Homepage" }` as the first entry.
-2. Every additional route discovered from the diff goes after the homepage entry.
-3. `sampleId: "first"` means the CI workflow should use the first record returned by the API. `sampleId: "any"` means any valid ID.
-4. `requireApi` is `true` when any route needs the backend to return data. It is `false` only for purely static pages (login, not-found).
-5. `requireLogin` is `true` when any route needs authentication. For dev mode with mock auth, `loginMethod` is `"mock-sso"`.
-6. `reason` should explain both WHY capture was blocked and WHAT the screenshots should show once captured.
-
-### Example `evidence.json`
-
-Adapt the routes and captions to this repository. Edits between the `PC-PROJECT-EXAMPLE` markers are carried over when the harness updates; anything outside them is replaced by the shipped version.
-
-<!-- PC-PROJECT-EXAMPLE-START -->
-```json
-{
-  "version": 1,
-  "changeId": "status-badge-in-detail-panel",
-  "required": true,
-  "status": "blocked",
-  "assets": [],
-  "capturePlan": {
-    "routes": [
-      { "path": "/", "sampleId": "any", "caption": "Homepage" },
-      { "path": "/items/:id", "sampleId": "first", "caption": "Item detail with the new status badge" }
-    ],
-    "viewports": [
-      { "width": 1280, "height": 720, "label": "desktop" },
-      { "width": 375, "height": 667, "label": "mobile" }
-    ],
-    "requireApi": true,
-    "requireLogin": true,
-    "loginMethod": "mock-sso",
-    "reason": "Status badge added to the item detail panel; visual change on the detail page."
-  },
-  "reason": "Visual evidence cannot be captured inside the awf sandbox (Docker-in-Docker unsupported, headless Chromium sandbox blocked). A capturePlan has been written for the Visual Evidence CI workflow.",
-  "prMarkdown": "## Evidence\n\nVisual evidence for this change is **blocked** in this agent run. A `capturePlan` has been written to `evidence.json` — the Visual Evidence CI workflow will execute it on a runner with full Docker and Chrome access.\n\nAutomated verification that did run:\n- Lint: clean\n- Tests: all pass\n- Build: success"
-}
-```
-<!-- PC-PROJECT-EXAMPLE-END -->
-
-### When evidence is not required
-
-If evidence is skipped (no UI files changed), write without a `capturePlan`:
-
-```json
-{
-  "version": 1,
-  "changeId": "{change-id}",
-  "required": false,
-  "status": "skipped",
-  "assets": [],
-  "reason": "No user-visible UI files changed in this PR.",
-  "prMarkdown": "## Evidence\n\nSkipped: no user-visible UI changes."
-}
-```
-
-Capture never commits, stages, or pushes. The caller owns git.
-
-## Part 2: Publish (operation: publish / both)
-
-Preconditions:
-- An issue/PR number was provided. Else skip.
-- Image URLs resolve only if the branch was pushed (`pr`/`push` modes).
-- Backlog platform from `.opencode/harness.json`; `none` means skip.
-
-<!-- PC-PLATFORM-EVIDENCE-START -->
-<!-- PC-PLATFORM-EVIDENCE-END -->
-
-## Report
-
-One block: the `status` (passed/skipped/failed/blocked) and why; capturePlan written or why not. Never present a blocked capture as passed.