@plainconceptsplatform/agent-harness 3.7.0 → 3.8.0

package/README.md

@@ -296,7 +296,7 @@ your-project/
 │   └── scripts/
 │       ├── check-diff.mjs           ← the comments and tests gate on the current diff (see below)
 │       ├── code-rules.mjs           ← its rules, the same ones Project-Health scores a repository with
-│       └── platform-manifest.mjs    ← reads .platform/manifest and exceptions in a family app (see below)
+│       └── platform-contract.mjs    ← reads .platform/contract.yml, the platform contract (see below)
 └── .agents/
     └── skills/
         ├── pc-guardrails-generic/  ← foundation for user guardrails
@@ -319,7 +319,9 @@ Platform skills ship as suffixed variants (`pc-userstory-gh`, `pc-userstory-az`,
 - adds a slop shape (banner, region, untracked TODO, a doc comment that repeats the name, commented-out code, an apology), a comment block of five lines or more, an incident story, or a doc comment on an internal symbol;
 - touches a file and leaves slop in it, or leaves it with more comments per code line than before;
 - grows the tests more than the code: test lines beyond the code lines added (40 always allowed), more than 40 cases per 1,000 code lines (3 always allowed), or any new skipped, focused, snapshot, assertion-less or mock-only test;
-- changes a platform file in an app built from the Kitchen-Sink template (see [Platform files in a family app](#platform-files-in-a-family-app)).
+- changes a path the platform contract says a template owns, or finds a contract it cannot read (see [Platform contracts](#platform-contracts)).
+
+It also warns, without failing, on a new file named like something the contract marks for reuse (`reuse-shadow`).
 
 A tool directive (`nosemgrep`, `biome-ignore`, `eslint-disable`, `@ts-expect-error`, coverage ignores) is not a comment and costs nothing. Code added to a file that has methods in the complexity baseline (`scripts/complexity-baseline.json`, keys `path::method`) counts twice toward the test budget: that gate fails a method whose coverage drops, so its new branches need tests.
 
@@ -329,19 +331,95 @@ A tool directive (`nosemgrep`, `biome-ignore`, `eslint-disable`, `@ts-expect-err
 "codeRules": { "commentRatio": 0.1, "commentAllowance": 2, "testRatio": 1, "testAllowance": 40, "casesPerKloc": 40, "caseAllowance": 3, "complexityBaseline": "scripts/complexity-baseline.json" }
 ```
 
-### Platform files in a family app
+## Platform contracts
+
+A repository that receives shared code from an upstream template can describe that relationship in `.platform/contract.yml`. The template can be delivered by Copier, cookiecutter, a git subtree or by hand; the harness reads only the file. It uses the contract to keep agents off the shared code and to point them at what the template already provides.
+
+The format is open. Other tools may read the same file, such as a workflow that syncs the template or a dashboard of template versions. None of them is required, and the harness never calls them.
+
+```yaml
+version: 1
+source:
+  name: Acme app template
+  url: https://github.com/acme/app-template
+  changes: https://github.com/acme/app-template/issues/new
+owned:
+  - .platform/contract.yml
+  - src/platform/**
+reuse:
+  docs: [docs/platform/]
+  packages: ["@acme/ui"]
+  names: [DataTable]
+exceptions: .platform/exceptions.yml
+sync:
+  marker: .copier-answers.yml
+  version:
+    file: .copier-answers.yml
+    key: _commit
+  update: copier update --trust --defaults --conflict inline
+```
+
+The template delivers the file, so the template owns it and lists it under `owned`.
+
+| Field | Required | What the harness does with it |
+| --- | --- | --- |
+| `version` | yes | Reads `1`. Any other value is an error. |
+| `source.name` | yes | Names the owner in every message. |
+| `source.url` | yes | Shown in the AGENTS.md block, and the default for `source.changes`. |
+| `source.changes` | no | Where every message tells the agent to ask for a change. |
+| `owned` | yes | gitwildmatch globs, repository-relative; a leading `/` anchors to the root and `!` excludes. `pc-system-reminders` denies agent edits to these paths, and `check-diff` reports `platform-file` for each one the diff changes. |
+| `reuse.docs` | no | Listed in the AGENTS.md block as reading before building something new. `pc-make-architecture` links to these pages instead of describing their topics again. |
+| `reuse.packages` | no | Listed in the AGENTS.md block. `check-diff` reads each package from `node_modules` and takes its reusable names from the `exports` subpaths and from the identifiers its type declarations export. |
+| `reuse.names` | no | More reusable names, for what cannot be derived from a package. |
+| `exceptions` | no | The exceptions file. Default `.platform/exceptions.yml`. |
+| `sync.marker` | no | A diff that changes this file is a template sync. `check-diff` lets it rewrite owned paths, and `pc-system-reminders` allows edits to them while the file has uncommitted changes, so a sync's conflicts can be resolved. |
+| `sync.version`, `sync.update` | no | Validated but not used: they are for the tool that updates the repository from the template. |
+
+### Reuse before you build
+
+When the contract has `reuse`, `agent-harness` install and `update` write this block into AGENTS.md between `<!-- PC-PLATFORM-CONTRACT-START -->` and `<!-- PC-PLATFORM-CONTRACT-END -->`, appending the pair when AGENTS.md has none. For the example above:
+
+```markdown
+## Reuse before you build
+
+This repository receives shared code from Acme app template (https://github.com/acme/app-template), declared in `.platform/contract.yml`.
+
+- Never design something new before reading `docs/platform/`.
+- Never re-implement an export of `@acme/ui`; import it.
+- Never write your own `DataTable`; reuse the existing one.
+- Never edit a path listed under `owned`. Ask for the change at https://github.com/acme/app-template/issues/new, or add a dated exception to `.platform/exceptions.yml`.
+```
+
+Without a contract, or without `reuse`, the block is empty. With `reuse`, `pc-plan-propose` gives every proposal a `## What is reused` section, and `pc-plan-apply` stops on a proposal that lacks it. `check-diff` warns with `reuse-shadow`, without failing, when a new source file's name matches a reusable name: `data-table.tsx`, `DataTable.tsx` and `data_table.ts` all match `DataTable`.
+
+### Exceptions
 
-An app that receives its platform code from the Kitchen-Sink Copier template carries `.copier-answers.yml` at its root and `.platform/manifest`, one gitwildmatch glob per line for the paths the template owns. In such an app `pc-system-reminders` denies an agent edit to a manifest path, and `check-diff` reports `platform-file` for every manifest path the diff changes. Both point at the fix: change the file in Kitchen-Sink (open an issue there), or add a dated exception to the app's `.platform/exceptions.yml`:
+An app that needs to diverge from an owned path for a while records it in the exceptions file:
 
 ```yaml
 exceptions:
-  - path: apps/api/src/Platform/Audit/**
+  - path: src/platform/audit/**
     reason: Local audit sink until the template supports it
-    issue: https://github.com/PlainConceptsPlatform/Kitchen-Sink/issues/1
+    issue: https://github.com/acme/app-template/issues/12
     expires: 2026-12-31
 ```
 
-An exception covers its path until the end of its `expires` day. A template sync, where `_commit` in `.copier-answers.yml` changes in the same diff, passes `check-diff`. A repository without both marker files sees no change in either tool.
+An exception covers the owned paths its glob matches until the end of its `expires` day, in both `pc-system-reminders` and `check-diff`. An expired entry no longer applies.
+
+### Errors
+
+A contract that does not read gives one error that names the file and the field, such as ``.platform/contract.yml: `source.name` is required and must be a non-empty string.`` The guards never pass silently on it: `check-diff` fails with `platform-contract`, and `pc-system-reminders` denies every edit outside `.platform/` until the file is fixed. Install and update warn and leave the AGENTS.md block as it was.
+
+### The legacy implicit contract
+
+Harness 3.7.0 read `.copier-answers.yml` and `.platform/manifest`, one glob per line. A repository with both files and no `contract.yml` is still read, as this contract:
+
+- `source.name` is the repository name at the end of `_src_path`, and `source.url` and `source.changes` are `_src_path`;
+- `owned` is the manifest's lines;
+- `sync.marker` and `sync.version.file` are `.copier-answers.yml`, with `sync.version.key` `_commit`;
+- there is no `reuse`.
+
+When both exist, `contract.yml` wins. A repository with neither sees no change in any tool.
 
 ## The bootstrap sequence
 

package/cli/steps/copy/agents.js

@@ -2,6 +2,7 @@ import fse from 'fs-extra'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import { info, success, warn } from '../../utils/exec.js'
+import { ContractError, loadContract } from '../../../harness/.opencode/scripts/platform-contract.mjs'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const agentsContent = await fse.readJson(path.resolve(__dirname, '../../presets/agents-content.json'))
@@ -46,6 +47,8 @@ const PLATFORM_WORKFLOW_START = '<!-- PC-PLATFORM-WORKFLOW-START -->'
 const PLATFORM_WORKFLOW_END = '<!-- PC-PLATFORM-WORKFLOW-END -->'
 const PLATFORM_SKILLS_GUIDE_START = '<!-- PC-PLATFORM-SKILLS-GUIDE-START -->'
 const PLATFORM_SKILLS_GUIDE_END = '<!-- PC-PLATFORM-SKILLS-GUIDE-END -->'
+const PLATFORM_CONTRACT_START = '<!-- PC-PLATFORM-CONTRACT-START -->'
+const PLATFORM_CONTRACT_END = '<!-- PC-PLATFORM-CONTRACT-END -->'
 
 function platformContent(platform, key) {
   const p = agentsContent.platform[platform] ?? agentsContent.platform.github
@@ -67,7 +70,42 @@ function replaceBetween(content, start, end, replacement) {
   if (!content.includes(start) || !content.includes(end)) return content
   const pattern = new RegExp(`${start}[\\s\\S]*?${end}`)
   // Replacer function so $&, $' and $` in injected content stay literal.
-  return content.replace(pattern, () => `${start}\n${replacement.trim()}\n${end}`)
+  const body = replacement.trim()
+  return content.replace(pattern, () => (body ? `${start}\n${body}\n${end}` : `${start}\n${end}`))
+}
+
+export function reuseBlock(contract) {
+  const { docs = [], packages = [], names = [] } = contract?.reuse ?? {}
+  if (!docs.length && !packages.length && !names.length) return ''
+  const code = list => list.map(item => `\`${item}\``).join(', ')
+  return [
+    '## Reuse before you build',
+    '',
+    `This repository receives shared code from ${contract.source.name} (${contract.source.url}), declared in \`.platform/contract.yml\`.`,
+    '',
+    ...(docs.length ? [`- Never design something new before reading ${code(docs)}.`] : []),
+    ...(packages.length ? [`- Never re-implement an export of ${code(packages)}; import it.`] : []),
+    ...(names.length ? [`- Never write your own ${code(names)}; reuse the existing one.`] : []),
+    `- Never edit a path listed under \`owned\`. Ask for the change at ${contract.source.changes}, or add a dated exception to \`${contract.exceptions}\`.`,
+  ].join('\n')
+}
+
+function contractBlock(cwd) {
+  try {
+    return reuseBlock(loadContract(cwd))
+  } catch (err) {
+    if (!(err instanceof ContractError)) throw err
+    warn(`${err.message} The "Reuse before you build" block in AGENTS.md was left as it was.`)
+    return null
+  }
+}
+
+// Installs from before the contract have no marker pair, and update never rewrites AGENTS.md: append it then.
+function patchContractBlock(content, cwd) {
+  const block = contractBlock(cwd)
+  if (block == null) return content
+  if (content.includes(PLATFORM_CONTRACT_START)) return replaceBetween(content, PLATFORM_CONTRACT_START, PLATFORM_CONTRACT_END, block)
+  return block ? `${content.replace(/\s*$/, '')}\n\n${PLATFORM_CONTRACT_START}\n${block}\n${PLATFORM_CONTRACT_END}\n` : content
 }
 
 export async function patchAgentsMd(ctx) {
@@ -111,6 +149,7 @@ export async function patchAgentGuidance(backlogPlatform, repoPlatform, cwd = pr
     let content = await fse.readFile(agentsMdPath, 'utf-8')
     content = replaceBetween(content, PLATFORM_WORKFLOW_START, PLATFORM_WORKFLOW_END, mixedPlatformContent(backlogPlatform, repo, 'workflow'))
     content = replaceBetween(content, PLATFORM_SKILLS_GUIDE_START, PLATFORM_SKILLS_GUIDE_END, mixedPlatformContent(backlogPlatform, repo, 'skillsGuide'))
+    content = patchContractBlock(content, cwd)
     await fse.writeFile(agentsMdPath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
     const label = backlogPlatform === repo ? repo : `${backlogPlatform}→${repo}`
     success(`AGENTS.md patched for platform workflow: ${label}`)

package/cli/utils/paths.js

@@ -51,6 +51,7 @@ export const RETIRED_PATHS = [
   '.agents/skills/pc-make-evidence-scaffold',
   '.opencode/commands/ops-evidence.md',
   '.opencode/commands/make-evidence-scaffold.md',
+  '.opencode/scripts/platform-manifest.mjs',
 ]
 
 export function configPath(cwd = process.cwd()) {

package/harness/.opencode/plugins/pc-system-reminders.js

@@ -18,7 +18,7 @@ import { execFile } from "node:child_process"
 import fs from "node:fs/promises"
 import path from "node:path"
 import { promisify } from "node:util"
-import { isPlatformOwned, loadPlatform } from "../scripts/platform-manifest.mjs"
+import { ContractError, describeOwner, isOwned, loadContract } from "../scripts/platform-contract.mjs"
 
 const GUARDRAILS_SKILL = "pc-guardrails-generic"
 const TIER_SUFFIX = /\.(?:build|fast|plan)$/
@@ -179,15 +179,40 @@ function checkWritePath(event, target, root) {
   )
 }
 
-function checkPlatformPath(event, target, root, platform) {
-  if (typeof target !== "string" || !target) return
-  const relative = path.isAbsolute(target) ? path.relative(root, target) : target
-  if (relative.startsWith("..") || !isPlatformOwned(platform, relative)) return
-  return deny(
-    event,
-    `\`${target}\` is platform code delivered by the Kitchen-Sink template.`,
-    "Change it in Kitchen-Sink (open an issue there), or add a dated exception to `.platform/exceptions.yml`.",
-  )
+const repoRelative = (target, root) =>
+  (path.isAbsolute(target) ? path.relative(root, target) : target).replace(/\\/g, "/").replace(/^\.\//, "")
+
+function isOwnedTarget(target, root, contract) {
+  if (typeof target !== "string" || !target) return false
+  const relative = repoRelative(target, root)
+  return !relative.startsWith("..") && isOwned(contract, relative)
+}
+
+// A template sync in progress has changed its marker file, and resolving its conflicts edits owned files.
+async function syncInProgress(root, marker) {
+  if (!marker) return false
+  try {
+    const { stdout } = await run("git", ["status", "--porcelain", "--", marker], { cwd: root })
+    return stdout.trim() !== ""
+  } catch {
+    return false
+  }
+}
+
+async function checkPlatform(event, root) {
+  let contract
+  try {
+    contract = loadContract(root)
+  } catch (error) {
+    if (!(error instanceof ContractError)) throw error
+    // An unreadable contract must not pass every edit: only the files that fix it stay editable.
+    if (event.resources.every(target => repoRelative(String(target), root).startsWith(".platform/"))) return
+    return deny(event, error.message, "Fix that file before editing anything else: until it reads, nothing can tell which files the template owns.")
+  }
+  const owned = contract ? event.resources.filter(target => isOwnedTarget(target, root, contract)) : []
+  if (!owned.length || await syncInProgress(root, contract.sync.marker)) return
+  const { owner, fix } = describeOwner(contract)
+  return deny(event, `\`${owned[0]}\` is ${owner}.`, fix)
 }
 
 function checkHost(event, url) {
@@ -364,12 +389,7 @@ export default Plugin.define({
           for (const resource of event.resources) {
             if (checkWritePath(event, resource, root)) return
           }
-          const platform = loadPlatform(root)
-          if (platform) {
-            for (const resource of event.resources) {
-              if (checkPlatformPath(event, resource, root, platform)) return
-            }
-          }
+          if (event.effect !== "deny") await checkPlatform(event, root)
         }
 
         if (event.action === "webfetch") {

package/harness/.opencode/scripts/check-diff.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { commentBlocks, countLines, isGenerated, kindOf, lineKinds, slopFindings, testStats } from './code-rules.mjs'
-import { ANSWERS_FILE, commitOf, isPlatformOwned, loadPlatform } from './platform-manifest.mjs'
+import { ContractError, describeOwner, isOwned, loadContract, nameKey, reusableNames } from './platform-contract.mjs'
 
 export const DEFAULT_LIMITS = {
   commentRatio: 0.1,
@@ -38,7 +38,9 @@ const FIX = {
   'test-snapshot': 'Assert the values that matter instead of a snapshot.',
   'test-no-assertion': 'Assert something, or delete the test.',
   'test-mock-only': 'Assert on state or output, not only that a mock was called.',
-  'platform-file': 'This is platform code delivered by the Kitchen-Sink template. Change it in Kitchen-Sink (open an issue there), or add a dated exception to .platform/exceptions.yml.',
+  'platform-file': 'This file is owned by the template named in the platform contract. Ask for the change there, or add a dated exception.',
+  'platform-contract': 'Fix the contract: until it reads, no platform file can be checked.',
+  'reuse-shadow': 'The platform contract marks this name for reuse. Use the existing one, or rename the file if it is something else.',
 }
 
 const SUSPICIOUS = {
@@ -209,20 +211,41 @@ export function trackedFiles(root, baseline) {
   }
 }
 
-// A template sync moves `_commit` in .copier-answers.yml and is the one change allowed to rewrite platform files.
-export function platformViolations(root, base, paths) {
-  const platform = loadPlatform(root)
-  if (!platform) return []
-  const answers = fs.readFileSync(path.join(root, ANSWERS_FILE), 'utf8')
-  if (commitOf(tryGit(root, ['show', `${base}:${ANSWERS_FILE}`])) !== commitOf(answers)) return []
+// A diff that changes the sync marker is a template sync, the one change allowed to rewrite owned files.
+export function platformViolations(root, base, paths, contract) {
   const touched = new Set(untrackedFiles(root))
   for (const { status, from, to } of changes(root, base)) {
     touched.add(to)
     if (status.startsWith('R')) touched.add(from)
   }
+  if (contract.sync.marker && touched.has(contract.sync.marker)) return []
+  const { owner, fix } = describeOwner(contract)
   return scope([...touched].map(file => ({ path: file })), paths)
-    .filter(file => isPlatformOwned(platform, file.path))
-    .map(file => ({ rule: 'platform-file', file: file.path, fix: FIX['platform-file'] }))
+    .filter(file => isOwned(contract, file.path))
+    .map(file => ({ rule: 'platform-file', file: file.path, detail: owner, fix }))
+}
+
+export function reuseWarnings(root, base, paths, contract) {
+  if (!contract.reuse.packages.length && !contract.reuse.names.length) return []
+  const added = [...untrackedFiles(root), ...changes(root, base).filter(c => c.status === 'A').map(c => c.to)]
+  const files = scope(added.map(file => ({ path: file })), paths).filter(f => kindOf(f.path) === 'source' && !isOwned(contract, f.path))
+  if (!files.length) return []
+  const names = reusableNames(root, contract, files.map(f => f.path))
+  return files.flatMap(file => {
+    const match = names.get(nameKey(path.basename(file.path).replace(/\.[^.]+$/, '')))
+    return match ? [{ rule: 'reuse-shadow', file: file.path, detail: `${match.name} from ${match.origin}`, fix: FIX['reuse-shadow'] }] : []
+  })
+}
+
+function platformFindings(root, base, paths) {
+  try {
+    const contract = loadContract(root)
+    if (!contract) return { violations: [], warnings: [] }
+    return { violations: platformViolations(root, base, paths, contract), warnings: reuseWarnings(root, base, paths, contract) }
+  } catch (error) {
+    if (!(error instanceof ContractError)) throw error
+    return { violations: [{ rule: 'platform-contract', detail: error.message, fix: FIX['platform-contract'] }], warnings: [] }
+  }
 }
 
 function readLimits(root) {
@@ -241,9 +264,9 @@ function report(result, base) {
     `  code lines added ${totals.sourceCode}, comment lines ${totals.comments}/${budgets.comments}, test lines ${totals.testLines}/${budgets.testLines}, test cases ${totals.cases}/${budgets.cases}`,
   ]
   const byRule = new Map()
-  for (const v of violations) byRule.set(v.rule, [...(byRule.get(v.rule) ?? []), v])
+  for (const v of [...violations, ...(result.warnings ?? [])]) byRule.set(v.rule, [...(byRule.get(v.rule) ?? []), v])
   for (const [rule, list] of byRule) {
-    lines.push('', `${rule}: ${FIX[rule]}`)
+    lines.push('', `${rule}${violations.includes(list[0]) ? '' : ' (warning)'}: ${list[0].fix ?? FIX[rule]}`)
     for (const v of list.slice(0, 50)) {
       const where = v.file ? `${v.file}${v.line ? `:${v.line}` : ''}` : ''
       lines.push(`  ${[where, v.detail].filter(Boolean).join('  ')}`)
@@ -271,7 +294,9 @@ function main(argv) {
   const limits = readLimits(root)
   const paths = option('paths')?.split(',').map(p => p.trim()).filter(Boolean)
   const result = evaluate(scope(collect(root, base.base), paths), limits, trackedFiles(root, limits.complexityBaseline))
-  result.violations.push(...platformViolations(root, base.base, paths))
+  const platform = platformFindings(root, base.base, paths)
+  result.violations.push(...platform.violations)
+  if (platform.warnings.length) result.warnings = platform.warnings
   console.log(argv.includes('--json') ? JSON.stringify({ base, ...result }, null, 2) : report(result, base))
   return result.violations.length === 0 ? 0 : 1
 }

package/harness/.opencode/scripts/platform-contract.mjs

@@ -0,0 +1,287 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const CONTRACT_FILE = '.platform/contract.yml'
+const DEFAULT_EXCEPTIONS = '.platform/exceptions.yml'
+const LEGACY_ANSWERS = '.copier-answers.yml'
+const LEGACY_MANIFEST = '.platform/manifest'
+
+export class ContractError extends Error {}
+
+const escapeRegExp = text => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+
+export function globToRegExp(glob) {
+  const directory = glob.endsWith('/')
+  const body = glob.replace(/\/$/, '')
+  const anchored = body.includes('/')
+  const pattern = body.replace(/^\//, '')
+  let source = ''
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i]
+    if (c === '*' && pattern[i + 1] === '*' && (i === 0 || pattern[i - 1] === '/')) {
+      if (i + 2 === pattern.length) {
+        source += '.*'
+        i += 1
+        continue
+      }
+      if (pattern[i + 2] === '/') {
+        source += '(?:.*/)?'
+        i += 2
+        continue
+      }
+    }
+    if (c === '*') {
+      source += '[^/]*'
+      while (pattern[i + 1] === '*') i++
+    } else if (c === '?') source += '[^/]'
+    else if (c === '[' && pattern.indexOf(']', i + 2) !== -1) {
+      const end = pattern.indexOf(']', i + 2)
+      source += `[${pattern.slice(i + 1, end).replace(/^!/, '^')}]`
+      i = end
+    } else if (c === '\\' && i + 1 < pattern.length) source += escapeRegExp(pattern[++i])
+    else source += escapeRegExp(c)
+  }
+  return new RegExp(`^${anchored ? '' : '(?:.*/)?'}${source}${directory ? '/.*' : '(?:/.*)?'}$`)
+}
+
+const toRules = globs => globs.map(glob => {
+  const negated = glob.startsWith('!')
+  return { negated, regex: globToRegExp(negated ? glob.slice(1) : glob) }
+})
+
+function matchesRules(rules, file) {
+  let matched = false
+  for (const rule of rules) if (rule.regex.test(file)) matched = !rule.negated
+  return matched
+}
+
+function stripComment(line) {
+  let quote = null
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i]
+    if (quote) quote = c === quote ? null : quote
+    else if ((c === '"' || c === "'") && (i === 0 || /[\s[,]/.test(line[i - 1]))) quote = c
+    else if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i)
+  }
+  return line
+}
+
+function scalar(raw) {
+  const value = raw.trim()
+  const quoted = value.match(/^(["'])(.*)\1$/)
+  if (quoted) return quoted[2]
+  if (value.startsWith('[') && value.endsWith(']')) return value.slice(1, -1).split(',').map(scalar).filter(item => item !== '')
+  return /^-?\d+$/.test(value) ? Number(value) : value
+}
+
+const isItem = text => text === '-' || text.startsWith('- ')
+
+// The subset of YAML a contract and its exceptions use: nested mappings, block and flow lists, scalars.
+export function parseYaml(text, file) {
+  const lines = []
+  text.replace(/^\uFEFF/, '').split(/\r?\n/).forEach((raw, index) => {
+    const body = stripComment(raw).trimEnd()
+    if (body.trim()) lines.push({ indent: body.length - body.trimStart().length, text: body.trim(), number: index + 1 })
+  })
+  const fail = line => {
+    throw new ContractError(`${file}: line ${line.number} cannot be read: \`${line.text}\`.`)
+  }
+
+  function block(start, indent) {
+    const list = isItem(lines[start].text)
+    const value = list ? [] : {}
+    let i = start
+    while (i < lines.length && lines[i].indent === indent) {
+      const line = lines[i]
+      if (isItem(line.text) !== list) {
+        if (list) break
+        fail(line)
+      }
+      if (list) {
+        const rest = line.text.slice(1).trimStart()
+        if (/^[^"'[{][^:]*:(\s|$)/.test(rest)) {
+          lines[i] = { ...line, indent: indent + line.text.length - rest.length, text: rest }
+        } else {
+          i++
+          if (rest || !(i < lines.length && lines[i].indent > indent)) {
+            value.push(rest ? scalar(rest) : null)
+            continue
+          }
+        }
+        const [item, after] = block(i, lines[i].indent)
+        value.push(item)
+        i = after
+        continue
+      }
+      const pair = line.text.match(/^([^:]+?)\s*:(?:\s+(.*))?$/)
+      if (!pair) fail(line)
+      const key = scalar(pair[1])
+      i++
+      const next = lines[i]
+      if (pair[2]) value[key] = scalar(pair[2])
+      else if (next && (next.indent > indent || (next.indent === indent && isItem(next.text)))) [value[key], i] = block(i, next.indent)
+      else value[key] = null
+    }
+    if (i < lines.length && lines[i].indent > indent) fail(lines[i])
+    return [value, i]
+  }
+
+  if (!lines.length) return null
+  const [value, end] = block(0, lines[0].indent)
+  if (end < lines.length) fail(lines[end])
+  return value
+}
+
+const isText = value => typeof value === 'string' && value.trim() !== ''
+const isMapping = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const invalid = (file, field, problem) => new ContractError(`${file}: \`${field}\` ${problem}`)
+
+function mapping(value, file, field, required = false) {
+  if (value == null && !required) return {}
+  if (!isMapping(value)) throw invalid(file, field, required ? 'is required and must be a mapping.' : 'must be a mapping.')
+  return value
+}
+
+function text(value, file, field, fallback) {
+  if (value == null && fallback !== undefined) return fallback
+  if (!isText(value)) throw invalid(file, field, fallback === undefined ? 'is required and must be a non-empty string.' : 'must be a non-empty string.')
+  return value
+}
+
+function textList(value, file, field) {
+  if (value == null) return []
+  const list = Array.isArray(value) ? value : [value]
+  if (!list.every(isText)) throw invalid(file, field, 'must be a list of non-empty strings.')
+  return list
+}
+
+export function readContract(source, file = CONTRACT_FILE) {
+  const raw = parseYaml(source, file)
+  if (!isMapping(raw)) throw new ContractError(`${file}: expected a mapping with \`version\`, \`source\` and \`owned\`.`)
+  if (raw.version == null) throw invalid(file, 'version', 'is required.')
+  if (String(raw.version) !== '1') throw invalid(file, 'version', `is ${raw.version}; this harness reads version 1.`)
+  const origin = mapping(raw.source, file, 'source', true)
+  const url = text(origin.url, file, 'source.url')
+  const owned = textList(raw.owned, file, 'owned')
+  if (!owned.length) throw invalid(file, 'owned', 'is required and must list at least one path.')
+  const reuse = mapping(raw.reuse, file, 'reuse')
+  const sync = mapping(raw.sync, file, 'sync')
+  const version = sync.version == null ? null : mapping(sync.version, file, 'sync.version')
+  return {
+    file,
+    source: { name: text(origin.name, file, 'source.name'), url, changes: text(origin.changes, file, 'source.changes', url) },
+    owned,
+    reuse: { docs: textList(reuse.docs, file, 'reuse.docs'), packages: textList(reuse.packages, file, 'reuse.packages'), names: textList(reuse.names, file, 'reuse.names') },
+    exceptions: text(raw.exceptions, file, 'exceptions', DEFAULT_EXCEPTIONS),
+    sync: {
+      marker: text(sync.marker, file, 'sync.marker', null),
+      version: version && { file: text(version.file, file, 'sync.version.file'), key: text(version.key, file, 'sync.version.key') },
+      update: text(sync.update, file, 'sync.update', null),
+    },
+  }
+}
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+// What harness 3.7.0 read before contract.yml existed: Copier answers plus a manifest of owned globs.
+function legacyContract(root) {
+  const answers = readText(path.join(root, LEGACY_ANSWERS))
+  const manifest = answers == null ? null : readText(path.join(root, LEGACY_MANIFEST))
+  if (manifest == null) return null
+  const srcLine = answers.match(/^_src_path:(.*)$/m)
+  const url = srcLine ? scalar(stripComment(srcLine[1])) || null : null
+  const owned = manifest.split(/\r?\n/).map(line => line.replace(/(?<!\\)\s+$/, '')).filter(line => line && !line.startsWith('#'))
+  return {
+    file: LEGACY_MANIFEST,
+    source: { name: url ? url.replace(/\.git$/, '').split(/[\\/:]/).filter(Boolean).pop() : 'the upstream template', url, changes: url },
+    owned,
+    reuse: { docs: [], packages: [], names: [] },
+    exceptions: DEFAULT_EXCEPTIONS,
+    sync: { marker: LEGACY_ANSWERS, version: { file: LEGACY_ANSWERS, key: '_commit' }, update: 'copier update --trust --defaults --conflict inline' },
+  }
+}
+
+export function loadContract(root) {
+  const source = readText(path.join(root, CONTRACT_FILE))
+  const contract = source == null ? legacyContract(root) : readContract(source)
+  if (!contract) return null
+  const exceptions = readText(path.join(root, contract.exceptions))
+  const entries = exceptions == null ? null : parseYaml(exceptions, contract.exceptions)?.exceptions
+  return { ...contract, rules: toRules(contract.owned), exceptionList: Array.isArray(entries) ? entries.filter(isMapping) : [] }
+}
+
+const localDate = (now = new Date()) =>
+  `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+
+export function isOwned(contract, file, today = localDate()) {
+  const relative = file.replace(/\\/g, '/').replace(/^\.\//, '')
+  if (!matchesRules(contract.rules, relative)) return false
+  return !contract.exceptionList.some(e =>
+    isText(e.path) && /^\d{4}-\d{2}-\d{2}$/.test(String(e.expires ?? '')) && e.expires >= today && globToRegExp(e.path).test(relative))
+}
+
+export function describeOwner(contract) {
+  const { name, changes } = contract.source
+  return {
+    owner: `owned by ${name} (listed in ${contract.file})`,
+    fix: `Ask for the change ${changes ? `at ${changes}` : `in ${name}`}, or add a dated exception to ${contract.exceptions}.`,
+  }
+}
+
+export const nameKey = name => name.toLowerCase().replace(/[-_.\s]/g, '')
+
+export function declaredExports(declarations) {
+  const names = [...declarations.matchAll(/^export\s+(?:declare\s+)?(?:default\s+)?(?:abstract\s+)?(?:function\*?|const|let|var|class|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/gm)].map(m => m[1])
+  for (const list of declarations.matchAll(/^export\s+(?:type\s+)?\{([^}]*)\}/gm)) {
+    for (const item of list[1].split(',')) {
+      const name = item.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop()
+      if (name && name !== 'default') names.push(name)
+    }
+  }
+  return names
+}
+
+function packageNames(directory) {
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8'))
+  } catch {
+    return []
+  }
+  const exportsMap = isMapping(manifest.exports) ? manifest.exports : {}
+  const subpaths = Object.keys(exportsMap)
+    .filter(key => key.startsWith('./') && !key.includes('*') && !/\.[a-z]+$/i.test(key))
+    .map(key => path.posix.basename(key))
+  const root = exportsMap['.'] ?? exportsMap
+  const types = manifest.types ?? manifest.typings ?? (isText(root.types) ? root.types : null)
+  const declarations = isText(types) ? readText(path.join(directory, types)) : null
+  return [...subpaths, ...(declarations ? declaredExports(declarations) : [])]
+}
+
+// Packages resolve from the nearest node_modules, so a workspace app finds what its own package.json installs.
+export function reusableNames(root, contract, files = []) {
+  const names = new Map()
+  const add = (name, origin) => {
+    const key = nameKey(name)
+    if (key && !names.has(key)) names.set(key, { name, origin })
+  }
+  for (const name of contract.reuse.names) add(name, contract.file)
+  const base = path.resolve(root)
+  const directories = new Set([base])
+  for (const file of files) {
+    for (let dir = path.dirname(path.resolve(base, file)); dir.length > base.length && dir.startsWith(base); dir = path.dirname(dir)) directories.add(dir)
+  }
+  for (const pkg of contract.reuse.packages) {
+    for (const dir of directories) {
+      const installed = path.join(dir, 'node_modules', pkg)
+      if (fs.existsSync(path.join(installed, 'package.json'))) for (const name of packageNames(installed)) add(name, pkg)
+    }
+  }
+  return names
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "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-make-architecture/SKILL.md

@@ -12,7 +12,7 @@ Write `ARCHITECTURE.md` in the project root from what the codebase actually cont
 
 - Never regenerate over a file that carries a `<!-- Last updated:` footer. That footer is what makes the next run incremental, and a full rewrite silently drops whatever a human added by hand. Read the file first and pick the mode.
 - Never analyze outside `.opencode/source-roots.json` when it exists, plus this repo's own docs and config.
-- When `docs/platform/` exists, the Kitchen-Sink template owns the platform code it documents (session and auth, permissions, audit, feature flags, errors, security headers, API surfaces, web shell). For those topics link to the page in `docs/platform/` instead of describing them again: a second description drifts on the next template update.
+- When `.platform/contract.yml` lists paths under `reuse.docs` (`docs/platform/`, for example), the template named in its `source` owns the code those pages document. For those topics link to the page instead of describing them again: a second description drifts on the next template update.
 - The footer is the file's last line, and it is the run's own ISO timestamp: `<!-- Last updated: <ISO date> -->`.
 - Follow the writing rules and self-check defined in the [structure template](structure-template.md). After generating, re-read each section: if a section only describes what exists without stating what breaks when its constraints are violated, rewrite it as constraint-embedded prose or cut it. The file is not written until the self-check passes.
 

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

@@ -39,6 +39,8 @@ Core rule: push, don't pull. A worker is born with its work: every `task()` spaw
 
 **2. Load the plan and workers.** Parse `tasks.md`. Each task carries `<!-- agent, depends_on, touches -->` (from `pc-plan-propose`). Inspect `.opencode/agents/` for each base engineer and its generated `.<tier>.md` variants. The tier-suffixed name in an annotation (for example, `backend-engineer.build`) is the worker to spawn: `pc-subagent-tiers` resolves its model at startup and registers it as `mode: subagent`. Read `.opencode/harness.json` -> `agents.maxConcurrent` (the wave cap, 1 to 5, enforced by `pc-subagent-monitor`).
 
+When `.platform/contract.yml` declares `reuse` and the change's `proposal.md` has no `## What is reused` section, stop the APPLY stage and report it: the plan never checked what the template already ships. Otherwise every spawn prompt in step 7 carries that section.
+
 Before hydrating the Todo board, resolve every task's annotated worker. If any task has a blank agent annotation, its base template is missing, or its tier variant is unavailable, stop the APPLY stage and report the task ID, expected worker, and missing file. Do not replace the worker with `fullstack-engineer`, `general`, or the lead session.
 
 **3. Hydrate the Todo board.** `todowrite` one item per task: `pending`. The Todo pane is the visible subagent board (opencode plugins cannot draw a custom pane, so the native Todo widget is the live UI). While a task is in flight, its label must carry the worker: `<agent> · <model>`: so the pane shows which agent on which model is doing what. The Todo list is a projection only: never read it for recovery; rebuild it from `tasks.md` and git and `.opencode/harness-run.json`.

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

@@ -51,6 +51,8 @@ If a work item URL or issue key is provided (GitHub Issue, Azure DevOps work ite
 
 Load `@openspec-propose` skill and follow its instructions to generate proposal.md, specs, and tasks.md. Do not write them to disk yet. Build the complete proposal content in your context.
 
+When `.platform/contract.yml` declares `reuse`, read the paths in `reuse.docs` and the exports of the `reuse.packages` first, and give proposal.md a `## What is reused` section: for each part of the change, the doc page, package export or `reuse.names` entry it builds on, or why none fits. A proposal without it re-implements what the template already ships, and `pc-plan-apply` stops on it.
+
 ## Step 2: Enrich task assignments
 
 1. List every `*-engineer.md` file in `.opencode/agents/`. For each file read:

package/harness/.opencode/scripts/platform-manifest.mjs

@@ -1,112 +0,0 @@
-import fs from 'node:fs'
-import path from 'node:path'
-
-export const ANSWERS_FILE = '.copier-answers.yml'
-export const MANIFEST_FILE = '.platform/manifest'
-export const EXCEPTIONS_FILE = '.platform/exceptions.yml'
-
-const escapeRegExp = text => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
-
-export function globToRegExp(glob) {
-  const directory = glob.endsWith('/')
-  const body = glob.replace(/\/$/, '')
-  const anchored = body.includes('/')
-  const pattern = body.replace(/^\//, '')
-  let source = ''
-  for (let i = 0; i < pattern.length; i++) {
-    const c = pattern[i]
-    if (c === '*' && pattern[i + 1] === '*' && (i === 0 || pattern[i - 1] === '/')) {
-      if (i + 2 === pattern.length) {
-        source += '.*'
-        i += 1
-        continue
-      }
-      if (pattern[i + 2] === '/') {
-        source += '(?:.*/)?'
-        i += 2
-        continue
-      }
-    }
-    if (c === '*') {
-      source += '[^/]*'
-      while (pattern[i + 1] === '*') i++
-    } else if (c === '?') source += '[^/]'
-    else if (c === '[' && pattern.indexOf(']', i + 2) !== -1) {
-      const end = pattern.indexOf(']', i + 2)
-      source += `[${pattern.slice(i + 1, end).replace(/^!/, '^')}]`
-      i = end
-    } else if (c === '\\' && i + 1 < pattern.length) source += escapeRegExp(pattern[++i])
-    else source += escapeRegExp(c)
-  }
-  return new RegExp(`^${anchored ? '' : '(?:.*/)?'}${source}${directory ? '/.*' : '(?:/.*)?'}$`)
-}
-
-export function parseManifest(text) {
-  return text
-    .split(/\r?\n/)
-    .map(line => line.replace(/(?<!\\)\s+$/, ''))
-    .filter(line => line && !line.startsWith('#'))
-    .map(line => {
-      const negated = line.startsWith('!')
-      return { negated, regex: globToRegExp(negated ? line.slice(1) : line) }
-    })
-}
-
-export function matchesRules(rules, file) {
-  let matched = false
-  for (const rule of rules) if (rule.regex.test(file)) matched = !rule.negated
-  return matched
-}
-
-const scalar = raw => {
-  const value = raw.trim()
-  const quoted = value.match(/^(["'])(.*)\1$/)
-  return quoted ? quoted[2] : value.replace(/\s+#.*$/, '')
-}
-
-export function parseExceptions(text) {
-  const exceptions = []
-  let current
-  for (const line of text.split(/\r?\n/)) {
-    if (!line.trim() || line.trim().startsWith('#') || /^exceptions:/.test(line)) continue
-    const item = line.match(/^\s*-\s+(.*)$/)
-    if (item) exceptions.push((current = {}))
-    const pair = (item ? item[1] : line).match(/^\s*([A-Za-z_]+):\s*(.*)$/)
-    if (pair && current) current[pair[1]] = scalar(pair[2])
-  }
-  return exceptions
-}
-
-export function commitOf(answers) {
-  const match = answers?.match(/^_commit:\s*(.+)$/m)
-  return match ? scalar(match[1]) : null
-}
-
-const localDate = (now = new Date()) =>
-  `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
-
-function readText(file) {
-  try {
-    return fs.readFileSync(file, 'utf8')
-  } catch {
-    return null
-  }
-}
-
-// A repository opts in by carrying both files; without them every caller behaves exactly as before.
-export function loadPlatform(root) {
-  if (!fs.existsSync(path.join(root, ANSWERS_FILE))) return null
-  const manifest = readText(path.join(root, MANIFEST_FILE))
-  if (manifest == null) return null
-  return {
-    rules: parseManifest(manifest),
-    exceptions: parseExceptions(readText(path.join(root, EXCEPTIONS_FILE)) ?? ''),
-  }
-}
-
-export function isPlatformOwned(platform, file, today = localDate()) {
-  const relative = file.replace(/\\/g, '/').replace(/^\.\//, '')
-  if (!matchesRules(platform.rules, relative)) return false
-  return !platform.exceptions.some(e =>
-    typeof e.path === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(e.expires ?? '') && e.expires >= today && globToRegExp(e.path).test(relative))
-}