@plainconceptsplatform/agent-harness 3.6.0 → 3.7.0

package/README.md

@@ -295,7 +295,8 @@ your-project/
 │   │   └── pc-system-reminders.js   ← server plugin: gates work on the agent's abilities, denies the never-rules
 │   └── 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
+│       ├── 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)
 └── .agents/
     └── skills/
         ├── pc-guardrails-generic/  ← foundation for user guardrails
@@ -317,7 +318,8 @@ Platform skills ship as suffixed variants (`pc-userstory-gh`, `pc-userstory-az`,
 - adds more comment lines than 10% of the code lines it adds (2 are always allowed);
 - 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.
+- 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)).
 
 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.
 
@@ -327,6 +329,20 @@ 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
+
+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`:
+
+```yaml
+exceptions:
+  - path: apps/api/src/Platform/Audit/**
+    reason: Local audit sink until the template supports it
+    issue: https://github.com/PlainConceptsPlatform/Kitchen-Sink/issues/1
+    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.
+
 ## The bootstrap sequence
 
 The first time you type `init` in OpenCode after onboarding, the agent asks whether this is a **greenfield** or **brownfield** project:

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

@@ -18,6 +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"
 
 const GUARDRAILS_SKILL = "pc-guardrails-generic"
 const TIER_SUFFIX = /\.(?:build|fast|plan)$/
@@ -178,6 +179,17 @@ 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`.",
+  )
+}
+
 function checkHost(event, url) {
   if (typeof url !== "string" || !url) return
   let host = ""
@@ -352,6 +364,12 @@ 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.action === "webfetch") {

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

@@ -3,6 +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'
 
 export const DEFAULT_LIMITS = {
   commentRatio: 0.1,
@@ -37,6 +38,7 @@ 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.',
 }
 
 const SUSPICIOUS = {
@@ -156,15 +158,23 @@ function resolveBase(root, requested) {
 
 const normalize = text => text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n')
 
-export function collect(root, base) {
-  const files = []
+function changes(root, base) {
+  const list = []
   const entries = git(root, ['diff', '--name-status', '-M', '-z', base]).split('\0').filter(Boolean)
   for (let i = 0; i < entries.length; ) {
     const status = entries[i]
     const renamed = status.startsWith('R') || status.startsWith('C')
-    const from = entries[i + 1]
-    const to = renamed ? entries[i + 2] : from
+    list.push({ status, from: entries[i + 1], to: renamed ? entries[i + 2] : entries[i + 1] })
     i += renamed ? 3 : 2
+  }
+  return list
+}
+
+const untrackedFiles = root => git(root, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean)
+
+export function collect(root, base) {
+  const files = []
+  for (const { status, from, to } of changes(root, base)) {
     if (status === 'D' || !kindOf(to)) continue
     const full = path.join(root, to)
     if (!fs.existsSync(full)) continue
@@ -173,7 +183,7 @@ export function collect(root, base) {
     const diff = git(root, ['diff', '-U0', '--no-color', '--no-ext-diff', '-M', base, '--', ...new Set([from, to])])
     files.push({ path: to, before, after, added: addedLines(diff) })
   }
-  for (const untracked of git(root, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean)) {
+  for (const untracked of untrackedFiles(root)) {
     if (!kindOf(untracked)) continue
     const after = normalize(fs.readFileSync(path.join(root, untracked), 'utf8'))
     const count = after.split('\n').length - (after.endsWith('\n') ? 1 : 0)
@@ -199,6 +209,22 @@ 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 []
+  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)
+  }
+  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'] }))
+}
+
 function readLimits(root) {
   try {
     const config = JSON.parse(fs.readFileSync(path.join(root, '.opencode', 'harness.json'), 'utf8'))
@@ -245,6 +271,7 @@ 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))
   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-manifest.mjs

@@ -0,0 +1,112 @@
+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))
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.6.0",
+  "version": "3.7.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,6 +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.
 - 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.