@plainconceptsplatform/agent-harness 2.4.0 → 2.5.0

package/harness/.agents/skills/pc-make-evidence-scaffold/evidence-contract.md

@@ -1,29 +1,29 @@
-# Evidence contract
-
-Evidence captured by `/plan-goal` lives at `openspec/changes/archive/<dated>-<id>/evidence/`. A standalone pre-archive capture may use `openspec/changes/<id>/evidence/`, but archive moves it into the archived change before publication. That folder contains only:
-- ordered capture images (`01-{label}.png/webp`, ...) and/or `flow.gif`
-- `evidence.json`: the manifest, schema below.
-
-## version 1 schema
-
-```jsonc
-{
-  "version": 1,
-  "changeId": "...",
-  "required": true,
-  "status": "passed",            // passed | skipped | failed | blocked
-  "assets": [ { "type": "screenshot", "path": "openspec/changes/archive/<dated>-<id>/evidence/01-final.png", "caption": "...", "bytes": 0, "format": "png" } ],
-  "reason": "...",                 // skipped | blocked
-  "failedStep": "...",             // failed
-  "prMarkdown": "## Evidence ..."
-}
-```
-
-## Statuses
-
-- `passed`: evidence required and produced.
-- `skipped`: evidence not required (see decision rule). Exit success.
-- `blocked`: required but could not run (no harness, app won't start, budget exceeded). Not a skip. Surface it.
-- `failed`: a project harness ran and its assertions failed. Surface it.
-
-`blocked` (required but unrunnable) is never treated as a skip.
+# Evidence contract
+
+Evidence captured by `/ops-evidence` lives at `openspec/changes/archive/<dated>-<id>/evidence/`. A standalone pre-archive capture may use `openspec/changes/<id>/evidence/`, but archive moves it into the archived change before publication. That folder contains only:
+- ordered capture images (`01-{label}.png/webp`, ...) and/or `flow.gif`
+- `evidence.json`: the manifest, schema below.
+
+## version 1 schema
+
+```jsonc
+{
+  "version": 1,
+  "changeId": "...",
+  "required": true,
+  "status": "passed",            // passed | skipped | failed | blocked
+  "assets": [ { "type": "screenshot", "path": "openspec/changes/archive/<dated>-<id>/evidence/01-final.png", "caption": "...", "bytes": 0, "format": "png" } ],
+  "reason": "...",                 // skipped | blocked
+  "failedStep": "...",             // failed
+  "prMarkdown": "## Evidence ..."
+}
+```
+
+## Statuses
+
+- `passed`: evidence required and produced.
+- `skipped`: evidence not required (see decision rule). Exit success.
+- `blocked`: required but could not run (no harness, app won't start, budget exceeded). Not a skip. Surface it.
+- `failed`: a project harness ran and its assertions failed. Surface it.
+
+`blocked` (required but unrunnable) is never treated as a skip.

package/harness/.agents/skills/pc-make-guardrails/SKILL.md

@@ -1,74 +1,43 @@
----
-name: pc-make-guardrails
-description: Generate or update the pc-guardrails-project skill from ARCHITECTURE.md and relevant project files, then wire it into every engineer agent. Invoked by the /make-guardrails command and the repo-initialize flow.
-license: MIT
----
-
-# Make Guardrails
-
-Analyze `ARCHITECTURE.md` and other project files to generate or update a `pc-guardrails-project` skill: a set of rules and constraints extracted from the project's own documentation that agents must follow.
-
-## Steps
-
-1. **Check current state**
-
-   Read `.agents/skills/pc-guardrails-project/SKILL.md`. Determine which mode to use:
-   - Does not exist: Generate mode. Create from scratch.
-   - Exists and has a `<!-- Last updated:` footer: Update mode. Incrementally update.
-   - Exists but no timestamp: proceed in Generate mode (full regeneration).
-
-2a. **Generate mode: read source documents**
-
-   Read ALL of the following that exist:
-   - `ARCHITECTURE.md` (primary source)
-   - `DESIGN.md` (design system, component conventions)
-   - `AGENTS.md` (existing agent instructions, optimizations)
-   - `README.md` (setup, conventions)
-   - `CONTRIBUTING.md` (if present)
-   - `.opencode/harness.json` (platform, models, concurrency)
-   - `openspec/config.yaml` (if present: domain context and rules)
-   - Root config files: `package.json`, `tsconfig.json`, `biome.json`, `.eslintrc*`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `pom.xml`: whatever exists
-   - CI/CD workflows: `.github/workflows/*`, `azure-pipelines.yml`: whatever exists
-
-   Use file tools to discover constraints: `read` the documents above, `grep` for lint/formatter config rules.
-
-2b. **Update mode: incremental analysis**
-
-   Extract the `<!-- Last updated: <ISO date> -->` timestamp from the existing skill file. Then:
-   - Read `ARCHITECTURE.md` and check its `<!-- Last updated:` timestamp. If ARCHITECTURE.md hasn't changed since the guardrails were last generated, report "Guardrails up to date" and stop.
-   - Run `git log --oneline --since="<date>" -- <config files, lint configs, CI workflows>` to find what convention/config files changed.
-   - If nothing changed: report "Guardrails up to date" and stop.
-   - Update only the affected rule categories. Preserve manually-added rules in unchanged categories.
-   - If changes are pervasive (new architecture, new framework, new platform), fall back to Generate mode.
-
-3. **Extract guardrails**
-
-   From the documents and code graph analysis, extract concrete, actionable rules. Follow the [category reference](category-reference.md) for the full list of categories, rule quality standards, and the skill file template.
-
-4. **Write the skill**
-
-   Write (or update) `.agents/skills/pc-guardrails-project/SKILL.md` using the template from the [category reference](category-reference.md). Only include sections that have real rules. Omit empty sections.
-
-5. **Update agents**
-
-   For every `*-engineer.md` in `.opencode/agents/`, add `@pc-guardrails-project` to the Guardrails ability line (skip if already present). Keep the line's existing entries exactly as they are: only insert `@pc-guardrails-project` after `@pc-guardrails-generic`, using this pattern:
-   ```markdown
-   ## Abilities
-   - Guardrails: @pc-guardrails-generic, @pc-guardrails-project[, ...existing entries unchanged]
-   ```
-
-   Exclude tier variant files (`*-engineer.build.md`, `*-engineer.fast.md`, `*-engineer.plan.md`): they are generated copies; only update the base templates.
-
-6. **Store summary in configured persistent context**
-
-   `write_note` MCP tool with title `guardrails-summary` containing:
-   - The ISO timestamp of this run
-   - Number of rules per category
-
-7. **Report**
-
-   Tell the user:
-   - Whether the skill was generated or updated (and which categories changed)
-   - Number of rules extracted per category
-   - Number of agent files updated
-   - Tip: "Rerun `/make-guardrails` any time the architecture or conventions change significantly."
+---
+name: pc-make-guardrails
+description: Generate or update the pc-guardrails-project skill from ARCHITECTURE.md and relevant project files, then wire it into every engineer agent. Invoked by the /make-guardrails command and the repo-initialize flow.
+license: MIT
+---
+
+# Make Guardrails
+
+Turn this project's own documentation into `.agents/skills/pc-guardrails-project/SKILL.md`: the rules and constraints its agents work under, per the [category reference](category-reference.md).
+
+## Rules
+
+- Never regenerate over a file that carries a `<!-- Last updated:` footer. `pc-guardrails-project` is the one skill a team is expected to hand-edit, and a full rewrite silently drops that work. Read the file first and pick the mode.
+- Never invent a rule the project does not state somewhere. A guardrail that came from nowhere is one nobody agreed to, and it will be followed anyway.
+- Never write an empty category. Omit it.
+- Never touch a tier variant (`*-engineer.build.md`, `*-engineer.fast.md`, `*-engineer.plan.md`): they are regenerated from the base templates every startup.
+
+## Sources
+
+`ARCHITECTURE.md` is the primary one. Then whatever else exists: `DESIGN.md`, `AGENTS.md`, `README.md`, `CONTRIBUTING.md`, `.opencode/harness.json`, `openspec/config.yaml`, the root manifests (`package.json`, `tsconfig.json`, `biome.json`, `.eslintrc*`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `pom.xml`), and the CI definitions (`.github/workflows/*`, `azure-pipelines.yml`). Lint and formatter config is where the conventions are actually enforced, so it outranks any document that describes them.
+
+## Modes
+
+| The existing skill file | Mode |
+|---|---|
+| Missing | Generate |
+| Has a `<!-- Last updated:` footer | Update |
+| Exists with no footer | Generate |
+
+**Update.** If `ARCHITECTURE.md` has not changed since the footer date, say "Guardrails up to date" and stop. Otherwise `git log --oneline --since="<footer date>" -- <config, lint config, CI workflows>`, update only the affected categories, and leave the rest, including hand-written rules, as they stand. A new architecture, framework or platform is a Generate.
+
+## Wiring
+
+Every `*-engineer.md` in `.opencode/agents/` gets `@pc-guardrails-project` on its Guardrails line, right after `@pc-guardrails-generic`, with its existing entries untouched:
+
+```markdown
+## Abilities
+- Guardrails: @pc-guardrails-generic, @pc-guardrails-project[, ...existing entries unchanged]
+```
+
+## Report
+
+Whether the skill was generated or updated and which categories changed, the rule count per category, how many agent files were wired, and that `/make-guardrails` can be re-run whenever the conventions move.

package/harness/.agents/skills/pc-make-guardrails/category-reference.md

@@ -1,9 +1,9 @@
 # Guardrails category reference
 
-From the documents and code graph analysis, extract concrete, actionable rules in these categories. Only include a category if you found real evidence for it.
+From the documents and code graph analysis, extract the rules an agent could break without noticing. Only include a category if you found real evidence for it.
 
 - Architecture constraints: layer boundaries, module dependencies, forbidden imports, directory ownership rules (e.g. "src/api/ must not import from src/ui/"). Verify actual import boundaries with the project-selected analysis tools.
-- File organization: avoid god-files and dumping-ground constants. Each file should have one clear responsibility. Split by domain or feature instead (e.g. `user-constants.ts`, `order-types.ts`, `auth-config.ts`). A file that imports from 5+ unrelated modules is a sign it should be split.
+- File organization: the god-files and dumping-ground constants this project has already accumulated, named. The general principle is in `pc-guardrails-generic`; what belongs here is where this codebase keeps breaking it.
 - Naming conventions: file naming, component naming, API route conventions, branch naming
 - Code style: formatter config, lint rules, import ordering, max line length. Derive from actual config files.
 - Testing rules: test file locations, naming, coverage gates, what must be tested before merge
@@ -15,9 +15,14 @@ From the documents and code graph analysis, extract concrete, actionable rules i
 - Domain-specific rules: anything in `openspec/config.yaml` context or `ARCHITECTURE.md` constraints/risks sections
 
 Each rule must be:
-- Concrete: "Use `pnpm` not `npm`" not "Use the right package manager"
-- Evidence-based: derive from the files/code graph you analyzed, do not invent rules
-- Actionable: an agent can check it before acting
+
+- **Negative.** State the boundary and what breaks when it is crossed, not the behaviour you want: `Never import Microsoft.EntityFrameworkCore.* in Application; it is a layer violation and the build does not catch it`, not `Keep Application framework-free`. A prohibition removes an option; a preference competes with everything else the model knows about writing code, and loses.
+- **Concrete**: "Use `pnpm` not `npm`" not "Use the right package manager".
+- **Evidence-based**: derived from the files and code graph you analyzed. Never invent a rule the project does not state or demonstrate somewhere.
+- **Not enforced elsewhere.** Skip anything the formatter, linter, type checker, test suite, CI gate or a harness plugin already fails the build on. A rule restating `biome.json` is read on every load and changes nothing: the build was going to catch it. Write the rules that nothing but a careful reader would catch.
+- **Not already in `pc-guardrails-generic`.** That skill loads alongside this one, every request. Secrets, comment discipline, scratch-file location and one-responsibility-per-file are its rules, not this file's.
+
+**At most 40 rules, across all categories.** Rank by what a violation costs and cut from the bottom; a category with nothing consequential in it gets no rules at all. This cap is the point of the exercise, not tidiness: compliance falls away as a rule file grows, so the 41st rule does not just cost its own tokens, it dilutes the 40 that matter. If more than 40 survive every bar above, the excess is a sign the project's constraints belong in a linter rule or a CI check instead.
 
 ## Skill template
 

package/harness/.agents/skills/pc-make-merge-risk-assess/category-reference.md

@@ -2,22 +2,41 @@
 
 From the project guardrails, architecture, and code analysis, extract concrete, testable risk indicators in these categories. Only include a category if you found real evidence for it.
 
-- **Calculation integrity**: changes to pricing, quoting, or calculation engines; modifications to formula inputs, salary tables, assumptions, or margin waterfalls. Any file under a calculation or quoting namespace is a risk indicator.
+- **Calculation integrity**: changes to whatever this project computes and cannot get wrong — an engine, its formula inputs, its reference tables, its assumptions. Any file under that namespace is an indicator. See the worked example below for the shape.
 - **Audit & compliance**: modifications to audit appenders, audit log storage, hash-chaining, or tamper-evident mechanisms. Any change that could affect regulatory traceability.
 - **Authentication & authorization**: changes to auth middleware, permission checks, role definitions, token issuance, or session management. Changes to `.RequirePermission()` calls or permission seed data.
 - **Data schema & migration**: EF Core entity changes, new migrations, column type changes, constraint additions/removals, or seed data modifications. Schema changes are always risky because they affect production data.
-- **Reference data versioning**: changes to effective-dated configuration, salary bands, assumptions, or any "magic number" that affects calculations. Changes to versioning or snapshot logic.
+- **Reference data versioning**: changes to effective-dated configuration, rate or band tables, assumptions, or any constant an output depends on. Changes to versioning or snapshot logic.
 - **Cross-boundary violations**: imports that break the layering direction (e.g. Domain referencing Application, Application referencing ASP.NET), cross-context data access bypassing ports.
 - **Security surface**: new endpoints without authorization, input validation removal, secrets exposure, dependency version downgrades, or changes to security scanning configuration.
-- **Financial correctness**: any change that could produce incorrect monetary values, incorrect tax calculations, incorrect currency handling, or rounding changes. Money is `decimal` — changes to precision or conversion logic are risk indicators.
+- **Financial correctness**: where the project handles money, any change that could produce a wrong amount — tax, currency, precision, rounding, or the type money is stored in.
 - **State machine transitions**: modifications to entity lifecycle transitions (e.g. quote status flow, approval gates, sign-off logic). Breaking a state machine can leave data in unrecoverable states.
 - **Integration contracts**: changes to external API contracts, webhook payloads, or CRM integration ports. Breaking integrations can cascade to downstream systems.
 
 Each indicator must be:
-- **Concrete**: "Changes to `QuoteCalculator.Calculate`" not "Changes to important calculations"
-- **Evidence-based**: derive from the project guardrails, architecture, and actual code paths
-- **Detectable**: an AI agent can find it by reading the PR diff (file paths, class names, method names, import changes)
-- **Exclusive**: do not duplicate indicators across categories — each belongs in its primary category
+
+- **Concrete**: name the type, method or path — "Changes to `OrderTotal.Calculate`" not "Changes to important calculations".
+- **Evidence-based**: derived from the project guardrails, the architecture, and actual code paths.
+- **Detectable**: findable by reading the PR diff alone — file paths, class names, method names, import changes.
+- **Exclusive**: each indicator belongs to one category. Never repeat it in a second.
+- **Not enforced elsewhere.** Skip anything CI already fails the build on. An indicator that duplicates a required check adds a human review the pipeline did not need.
+
+**At most 40 indicators, across all categories.** Rank by what a missed regression costs and cut from the bottom. A file this size is read on every merge decision, and past roughly this many, compliance drops regardless of how good each line is — so an indicator that will not change a verdict is worse than absent.
+
+## Worked example
+
+One project's calculation-integrity indicator, for shape only. Replace it with
+this repository's own: edits between the `PC-PROJECT-EXAMPLE` markers are
+carried over when the harness updates, and anything outside them is replaced by
+the shipped version.
+
+<!-- PC-PROJECT-EXAMPLE-START -->
+```markdown
+### Calculation Integrity
+- Any change under `src/pricing/engine/` — `RateEngine.Compute` is static and deterministic, and every change to it needs a golden vector in `PricingParityTests`. A wrong number here is invisible in review and correct-looking in production.
+- Any change to a rate table, band, or assumption constant, including its effective dates. The engine reads them by date, so an edit silently rewrites past outputs.
+```
+<!-- PC-PROJECT-EXAMPLE-END -->
 
 ## Skill template
 

package/harness/.agents/skills/pc-make-user-model/SKILL.md

@@ -1,66 +1,56 @@
----
-name: pc-make-user-model
-description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override. Invoked by the /make-user-model command.
-license: MIT
----
-Set the concrete model for one tier. Writes to `models` in either the team config (shared, git-tracked) or a user-local override (gitignored).
-
-Usage:
-
-```
-/make-user-model <tier> <model>
-/make-user-model user <tier> <model>
-```
-
-- `user`: optional prefix. If present, writes to `.opencode/harness.user.json` (gitignored, overrides team config for this machine only). If absent, writes to `.opencode/harness.json` (shared with the team).
-- `<tier>`: one of `plan`, `build`, `fast`.
-- `<model>`: a fully-qualified model id (e.g. `opencode/big-pickle`) OR the keyword `current` to use the model active in this session.
-
-Arguments: `$ARGUMENTS`
-
-Steps
-
-1. Parse `$ARGUMENTS`** by whitespace.
-   - If first token is `user`: `isUser = true`, `<tier>` = second token, `<model>` = third token.
-   - Otherwise: `isUser = false`, `<tier>` = first token, `<model>` = second token.
-   - If `$ARGUMENTS` is empty: read both `.opencode/harness.json` and `.opencode/harness.user.json` and show the current `models` from each (team first, user override second), then show the usage above. Change nothing.
-   - If `<tier>` is not exactly one of `plan` / `build` / `fast`, or `<model>` is missing: print the usage and stop. Change nothing.
-
-2. **Resolve `<model>`:**
-   - If it is the literal `current`: use the model id visible in the opencode status line for this session. Use only the model id shown there, not a guessed value.
-   - Otherwise use the value verbatim. It must look like `provider/model-id`. If it contains no `/`, warn that it looks malformed and call the `question` tool to confirm before writing:
-
-     ```json
-     {
-       "questions": [
-         {
-           "header": "Malformed model id",
-           "question": "\"<model>\" doesn't look like a valid model id (expected provider/model-id). Write it anyway?",
-           "options": [
-             { "label": "yes", "description": "Write the value as-is to the config file." },
-             { "label": "no", "description": "Cancel. Do not write anything." }
-           ]
-         }
-       ]
-     }
-     ```
-
-     Only proceed to write if the user answers `yes`.
-
-3. Determine target file.
-   - `isUser = false` -> `.opencode/harness.json` (team). If it does not exist, stop and tell the user onboarding has not generated it yet.
-   - `isUser = true` -> `.opencode/harness.user.json` (user override). If it does not exist, create it with `{ "models": {} }`.
-
-4. Update the config. Read the target file, set `models.<tier>` to the resolved model id (create `models` if absent). Do not touch any other field. Preserve the existing 2-space JSON formatting, then write the file back.
-
-5. Confirm:
-
-   ```
-   <team|user> config updated
-     <tier> model -> <resolved-id>
-     file: <path written>
-   ```
-
-   Restart opencode for the change to take effect. The `pc-subagent-tiers` plugin reads the model configs at startup and injects tier-suffixed agent variants (`<engineer>.<tier>`) into the live config. After restart, `/plan-apply` will spawn agents on the new model.
-
-This command edits `harness.json` (team) or `harness.user.json` (user) only. It never modifies agent files, `opencode.json`, or `tasks.md`. Tier variants are generated in-memory by the `pc-subagent-tiers` plugin at startup: no file re-stamping needed.
+---
+name: pc-make-user-model
+description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override. Invoked by the /make-user-model command.
+license: MIT
+---
+
+Point one tier at one model, in the team config or in a machine-local override.
+
+## Rules
+
+- Only `models.<tier>` in `.opencode/harness.json` or `.opencode/harness.user.json` changes. Agent files, `opencode.jsonc` and `tasks.md` are not this command's business, and tier variants are rebuilt from these configs at startup anyway.
+- Never guess the id behind `current`: read it from the status line. A guessed id writes a model that does not exist into the team's config.
+- Never write anything when the arguments do not parse. Print the usage and stop.
+- Preserve the file's other fields and its 2-space formatting.
+
+## Contract
+
+```
+/make-user-model <tier> <model>
+/make-user-model user <tier> <model>
+```
+
+`user` writes `.opencode/harness.user.json`, which is gitignored and wins on this machine only; without it the target is `.opencode/harness.json`, which is shared. `<tier>` is exactly `plan`, `build` or `fast`. `<model>` is a fully-qualified id (`opencode/big-pickle`) or `current` for the model this session is running.
+
+No arguments means show the `models` block from both files, team first, then the usage. Change nothing.
+
+A team config that does not exist yet is a stop: onboarding has not run. A missing user config is created as `{ "models": {} }`.
+
+An id with no `/` in it is malformed; confirm before writing it:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Malformed model id",
+      "question": "\"<model>\" doesn't look like a valid model id (expected provider/model-id). Write it anyway?",
+      "options": [
+        { "label": "yes", "description": "Write the value as-is to the config file." },
+        { "label": "no", "description": "Cancel. Do not write anything." }
+      ]
+    }
+  ]
+}
+```
+
+## Report
+
+```
+<team|user> config updated
+  <tier> model -> <resolved-id>
+  file: <path written>
+```
+
+The change lands on the next opencode start, when `pc-subagent-tiers` reads the configs and rebuilds the tier variants.
+
+Arguments: `$ARGUMENTS`