@plainconceptsplatform/workflows 1.11.0 → 1.12.0

package/README.md

@@ -81,7 +81,7 @@ npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci
 
 ## Templates
 
-Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-error-report`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, `bug-report`, `feature-request`, `github-release`, `opencode.ci.json`, `platform-template` and `quality-gates`. CI templates are stack-specific copies, not a combined template. `quality-gates` and `platform-template` are bundles for the platform family: they stay package-managed and `update` refreshes them where they are installed; see `docs/family-templates.md` in the repository. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
+Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-error-report`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, `bug-report`, `feature-request`, `github-release`, `opencode.ci.json`, `platform-template` and `quality-gates`. CI templates are stack-specific copies, not a combined template. `quality-gates` and `platform-template` are bundles: they stay package-managed and `update` refreshes them where they are installed. `platform-template` reads the platform contract, `.platform/contract.yml`; see `docs/platform-contracts.md` and `docs/family-templates.md` in the repository. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
 
 `agentics-error-report` is worth installing everywhere. Once a day it classifies how *this package's* workflows behaved in the repository and files what broke upstream, so the package gets fixed instead of every repository working around the same bug. It is deterministic no model runs, because a model asked to summarise a failure paraphrases whatever the log held and it sends only the names this package gives its own workflows, jobs and steps, a conclusion, a bucketed runner label, a count and a classification id. No log line, branch, title, path or issue number leaves the repository, the repository's own workflows are counted and never inspected, and a leak scanner withholds any report mentioning the repository or its owner and fails the run rather than filing it. Clear `UPSTREAM_NAME` in its `env:` to compute the report into the job summary and file nothing.
 

package/dist/workflow-catalog.js

@@ -74,7 +74,7 @@ export const catalogTemplates = [
     { name: "feature-request", file: "feature_request.yml", description: "Feature request issue template scoped to small, well-scoped improvements (Small/Medium only; large work belongs in a planning issue).", target: ".github/ISSUE_TEMPLATE/feature_request.yml" },
     { name: "github-release", file: "github-release.yml", description: "Publishes or updates a GitHub Release with generated notes whenever a v* tag is pushed." },
     { name: "opencode.ci.json", file: "opencode.ci.json", description: "Standalone OpenCode CI config: plainconcepts provider, GLM model registration, ci-workflow-agent, and LSP defaults for consumer repositories." },
-    { name: "platform-template", file: "scripts/check-platform-conformance.mjs", directory: "platform-template", bundle: true, description: "Platform family template sync: a weekly workflow that runs copier update against the Kitchen-Sink template and opens a pull request per new tag, and a CI guard that keeps .platform/manifest paths unchanged outside a sync. Does nothing without .copier-answers.yml." },
+    { name: "platform-template", file: "scripts/check-platform-conformance.mjs", directory: "platform-template", bundle: true, description: "Template sync driven by the platform contract (.platform/contract.yml): a weekly workflow that runs its sync.update command and opens or updates one pull request, and a CI guard that keeps its owned paths equal to the template outside a sync. Does nothing without a contract." },
     { name: "quality-gates", file: "scripts/check-coverage.mjs", directory: "quality-gates", bundle: true, description: "Platform family quality gates: coverage, complexity, duplication and mutation gates, the Engineering Excellence facets, the Semgrep hygiene rules, jscpd and ZAP triage. Floors come from the app's quality.config.json; baselines stay app files." },
 ];
 /** Bundle templates: several package-managed files, refreshed by `update` where installed. */

package/loops/templates/ci/app-ci-dotnet-next.yml

@@ -9,7 +9,7 @@
 # engineering-excellence-{coverage,complexity,security,sbom,hygiene} facets Project-Health
 # collects. The facets upload from main only, which this workflow reaches through `App: Deploy` on
 # every push and through its own weekly schedule. The platform-conformance job runs the
-# platform-template guard where the app has adopted the template.
+# platform-template guard where the app declares a platform contract.
 #
 # Everything that differs between apps is a top-level `env:` value below or a floor in
 # quality.config.json. Job names are required status checks on main: do not rename them.
@@ -546,8 +546,10 @@ jobs:
         if: env.REPO_CHECK_COMMANDS != ''
         run: bash -euo pipefail -c "$REPO_CHECK_COMMANDS"
 
-  # Platform files (.platform/manifest) change only through a template sync. The guard comes with the
-  # platform-template template; a repository without .copier-answers.yml has not adopted it and passes.
+  # Paths a platform contract (.platform/contract.yml) marks as owned change only through a template
+  # sync. The guard comes with the platform-template template; a repository with no contract (nor
+  # .copier-answers.yml with .platform/manifest, read as one) has not adopted it and passes. The
+  # owned files are also compared with the template at the recorded version wherever git can read it.
   platform-conformance:
     name: Platform conformance
     runs-on: ${{ vars.CI_RUNNER || 'agents-arc' }}
@@ -559,25 +561,25 @@ jobs:
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: ${{ env.NODE_VERSION }}
-      - name: Platform files change only through a template sync
+      - name: Owned files change only through a template sync
         env:
           EVENT: ${{ github.event_name }}
           BASE_REF: ${{ github.base_ref }}
         run: |
           set -euo pipefail
-          if [ ! -f .copier-answers.yml ]; then
-            echo "No .copier-answers.yml: this repository has not adopted the platform template."
+          if [ ! -f .platform/contract.yml ] && { [ ! -f .copier-answers.yml ] || [ ! -f .platform/manifest ]; }; then
+            echo "No .platform/contract.yml: this repository declares no platform contract."
             exit 0
           fi
           if [ ! -f scripts/check-platform-conformance.mjs ]; then
-            echo "::error::.copier-answers.yml is here but scripts/check-platform-conformance.mjs is not. Install it with: npx @plainconceptsplatform/workflows add --template platform-template"
+            echo "::error::This repository has a platform contract but no scripts/check-platform-conformance.mjs. Install it with: npx @plainconceptsplatform/workflows add --template platform-template"
             exit 1
           fi
           if [ "$EVENT" = pull_request ]; then
             git fetch origin "$BASE_REF"
-            node scripts/check-platform-conformance.mjs --base "origin/$BASE_REF" | tee -a "$GITHUB_STEP_SUMMARY"
+            node scripts/check-platform-conformance.mjs --compare --base "origin/$BASE_REF" | tee -a "$GITHUB_STEP_SUMMARY"
           else
-            node scripts/check-platform-conformance.mjs | tee -a "$GITHUB_STEP_SUMMARY"
+            node scripts/check-platform-conformance.mjs --compare | tee -a "$GITHUB_STEP_SUMMARY"
           fi
 
   mutation-web:

package/loops/templates/platform-template/.github/workflows/platform-template-sync.yml

@@ -1,19 +1,15 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/templates/platform-template/.github/workflows/platform-template-sync.yml. Update with `workflows update --force`; consumer edits may be overwritten.
 name: "Platform: Template sync"
 
-# Brings the platform code of a family app up to the newest Kitchen-Sink template tag. Plain YAML,
-# no model: copier does the merge, and a person or the merge gate takes it from the pull request.
+# Pulls the newest version of the upstream template named in .platform/contract.yml (see
+# docs/platform-contracts.md in agentic-workflows). Plain YAML, no model. Without a contract it does
+# nothing. With one it runs `sync.update` and opens or updates one pull request from
+# `platform/template-sync`. copier is installed when the command starts with `copier`; any other
+# command is the repository's to provide. Conflict markers left in an owned file fail the
+# conformance guard, so the merge gate repairs the pull request like any red one.
 #
-# Does nothing without .copier-answers.yml, the marker a repository gets when it adopts the
-# template. With it, `copier update` runs against the newest `v*` tag of the template named in
-# `_src_path`. No change means the app is current and the run ends there. Otherwise the result is
-# committed to `platform/sync-<tag>` and opened as a pull request titled with the tag. A file the
-# app had edited gets copier's inline conflict markers; scripts/check-platform-conformance.mjs
-# fails CI on them, so the merge gate repairs the pull request (`remediated`) like any red one.
-#
-# Kitchen-Sink is private, so the Platform App token (BOT_APP_ID / BOT_PRIVATE_KEY) reads it. The
-# same token pushes the branch and opens the pull request, because a push made with GITHUB_TOKEN
-# starts no workflow and CI would never run on the sync.
+# The Platform App token (BOT_APP_ID / BOT_PRIVATE_KEY) reads a private template and pushes, because
+# a push made with GITHUB_TOKEN starts no workflow and CI would never run on the sync.
 on:
   schedule:
     - cron: "17 5 * * 1"
@@ -29,6 +25,8 @@ concurrency:
 env:
   # copier 9.19.1 needs Python 3.10 or newer on the runner.
   COPIER_VERSION: "9.19.1"
+  NODE_VERSION: "22"
+  SYNC_BRANCH: platform/template-sync
 
 jobs:
   sync:
@@ -41,19 +39,40 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      - name: Has this repository adopted the template?
-        id: marker
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      # An invalid contract fails here, with the file and the field in the error.
+      - name: Read the platform contract
+        id: contract
+        run: |
+          set -euo pipefail
+          node scripts/check-platform-conformance.mjs --contract | tee -a "$GITHUB_OUTPUT"
+
+      - name: Decide whether to sync
+        id: decide
+        env:
+          CONTRACT: ${{ steps.contract.outputs.contract }}
+          SELF: ${{ steps.contract.outputs.self }}
+          UPDATE: ${{ steps.contract.outputs.update }}
         run: |
-          if [ -f .copier-answers.yml ]; then
-            echo "adopted=true" >> "$GITHUB_OUTPUT"
+          set -euo pipefail
+          run=false
+          if [ "$CONTRACT" != present ]; then
+            echo "No .platform/contract.yml (nor .copier-answers.yml with .platform/manifest): nothing to sync."
+          elif [ "$SELF" = true ]; then
+            echo "This repository is the template source.url names: nothing to sync."
+          elif [ -z "$UPDATE" ]; then
+            echo "The platform contract declares no sync.update: nothing to sync."
           else
-            echo "adopted=false" >> "$GITHUB_OUTPUT"
-            echo "No .copier-answers.yml: this repository has not adopted the platform template. Nothing to do."
+            run=true
           fi
+          echo "run=$run" >> "$GITHUB_OUTPUT"
 
       - name: Generate App token
         id: app-token
-        if: steps.marker.outputs.adopted == 'true'
+        if: steps.decide.outputs.run == 'true'
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         with:
           app-id: ${{ secrets.BOT_APP_ID }}
@@ -62,7 +81,7 @@ jobs:
 
       # uvx where uv is installed, then pipx, then a virtual environment from the runner's Python.
       - name: Install copier
-        if: steps.marker.outputs.adopted == 'true'
+        if: steps.decide.outputs.run == 'true' && startsWith(steps.contract.outputs.update, 'copier ')
         run: |
           set -euo pipefail
           bin="$RUNNER_TEMP/copier-bin"
@@ -87,8 +106,10 @@ jobs:
       # The token reaches git through process-scoped config only, never a file on the runner.
       - name: Update from the template
         id: update
-        if: steps.marker.outputs.adopted == 'true'
+        if: steps.decide.outputs.run == 'true'
         env:
+          UPDATE: ${{ steps.contract.outputs.update }}
+          BEFORE: ${{ steps.contract.outputs.version }}
           GIT_CONFIG_COUNT: "1"
           GIT_CONFIG_KEY_0: url.https://x-access-token:${{ steps.app-token.outputs.token }}@github.com/.insteadOf
           GIT_CONFIG_VALUE_0: https://github.com/
@@ -98,21 +119,19 @@ jobs:
           GIT_COMMITTER_EMAIL: ${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com
         run: |
           set -euo pipefail
-          commit_of() { sed -n 's/^_commit:[[:space:]]*//p' .copier-answers.yml | tr -d "\"'" | head -n 1; }
-          before=$(commit_of)
-          copier update --trust --defaults --conflict inline
-          after=$(commit_of)
+          echo "sync.update: $UPDATE"
+          bash -euo pipefail -c "$UPDATE"
           if [ -z "$(git status --porcelain)" ]; then
-            echo "Already on the newest template ($before). Nothing to do."
+            echo "Already on the newest template (${BEFORE:-no version recorded}). Nothing to do."
             echo "changed=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+          after=$(node scripts/check-platform-conformance.mjs --contract | sed -n 's/^version=//p')
           git add --all
           conflicts=$(git grep --cached -l -E '^(<<<<<<<|>>>>>>>)( |$)' -- . || true)
           {
             echo "changed=true"
-            echo "before=$before"
-            echo "tag=$after"
+            echo "tag=${after:-$(git rev-parse --short HEAD)}"
             echo "files<<EOF"
             git diff --cached --name-status
             echo "EOF"
@@ -121,14 +140,19 @@ jobs:
             echo "EOF"
           } >> "$GITHUB_OUTPUT"
 
-      - name: Open the sync pull request
+      # One sync pull request at a time. An open one for the same version is left alone, so the
+      # conflict resolutions pushed to it survive; a newer version replaces its branch and its text.
+      - name: Open or update the sync pull request
         if: steps.update.outputs.changed == 'true'
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           REPO: ${{ github.repository }}
           BASE: ${{ github.event.repository.default_branch }}
-          BEFORE: ${{ steps.update.outputs.before }}
+          SOURCE_NAME: ${{ steps.contract.outputs.source_name }}
+          SOURCE_WEB: ${{ steps.contract.outputs.source_web }}
+          BEFORE: ${{ steps.contract.outputs.version }}
           TAG: ${{ steps.update.outputs.tag }}
+          UPDATE: ${{ steps.contract.outputs.update }}
           FILES: ${{ steps.update.outputs.files }}
           CONFLICTS: ${{ steps.update.outputs.conflicts }}
           GIT_CONFIG_COUNT: "1"
@@ -140,25 +164,29 @@ jobs:
           GIT_COMMITTER_EMAIL: ${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com
         run: |
           set -euo pipefail
-          branch="platform/sync-$TAG"
-          if [ -n "$(gh pr list --repo "$REPO" --head "$branch" --state open --json number --jq '.[].number')" ]; then
-            echo "A pull request for $TAG is already open on $branch. Nothing to do."
+          marker="<!-- platform-template-sync: $TAG -->"
+          open=$(gh pr list --repo "$REPO" --head "$SYNC_BRANCH" --state open --json number --jq '.[0].number // empty')
+          if [ -n "$open" ] && gh pr view "$open" --repo "$REPO" --json body --jq .body | grep -qF -- "$marker"; then
+            echo "Pull request #$open already syncs $TAG. Nothing to do."
             exit 0
           fi
-          src=$(sed -n 's/^_src_path:[[:space:]]*//p' .copier-answers.yml | tr -d "\"'" | head -n 1)
-          web="${src#git+}"
-          web="${web%.git}"
-          git switch --create "$branch"
-          git commit --quiet --message "chore(platform): sync the platform template to $TAG"
-          git push --force "https://github.com/$REPO.git" "HEAD:refs/heads/$branch"
+          title="chore(platform): sync $SOURCE_NAME to $TAG"
+          git switch --create "$SYNC_BRANCH"
+          git commit --quiet --message "$title"
+          git push --force "https://github.com/$REPO.git" "HEAD:refs/heads/$SYNC_BRANCH"
+          case "$SOURCE_WEB" in
+            https://github.com/*) target="[\`$TAG\`]($SOURCE_WEB/releases/tag/$TAG)" ;;
+            *) target="\`$TAG\`" ;;
+          esac
           body="$RUNNER_TEMP/sync-body.md"
           {
-            echo "Platform template sync from \`$BEFORE\` to [\`$TAG\`]($web/releases/tag/$TAG), made by \`copier update\`."
+            echo "$marker"
+            echo "Sync of the code owned by $SOURCE_NAME from \`${BEFORE:-no recorded version}\` to $target, made by \`$UPDATE\`."
             echo
             if [ -n "$CONFLICTS" ]; then
               echo "### Conflicts"
               echo
-              echo "These files carry inline conflict markers where the app had edited platform code. CI fails on them until they are resolved."
+              echo "These files carry inline conflict markers where this repository had edited owned code. CI fails on them until they are resolved."
               echo
               printf '%s\n' "$CONFLICTS" | awk '{ printf "- `%s`\n", $0 }'
               echo
@@ -167,5 +195,8 @@ jobs:
             echo
             printf '%s\n' "$FILES" | awk -F '\t' '{ printf "- `%s` %s\n", $NF, $1 }'
           } > "$body"
-          gh pr create --repo "$REPO" --base "$BASE" --head "$branch" \
-            --title "chore(platform): sync the platform template to $TAG" --body-file "$body"
+          if [ -n "$open" ]; then
+            gh pr edit "$open" --repo "$REPO" --title "$title" --body-file "$body"
+          else
+            gh pr create --repo "$REPO" --base "$BASE" --head "$SYNC_BRANCH" --title "$title" --body-file "$body"
+          fi

package/loops/templates/platform-template/scripts/check-platform-conformance.mjs

@@ -1,21 +1,28 @@
 #!/usr/bin/env node
 // Managed by @plainconceptsplatform/workflows. Source: loops/templates/platform-template/scripts/check-platform-conformance.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
-// The .platform/manifest paths change only in a template sync (a pull request that moves `_commit` in
-// .copier-answers.yml) or under an unexpired .platform/exceptions.yml entry. Conflict markers in a
-// manifest file and expired exceptions fail too. Offline; without .copier-answers.yml it passes silently.
+// Keeps the paths a platform contract (.platform/contract.yml) marks as `owned` equal to the template
+// they come from. A pull request may change them only in a template sync (it changes `sync.marker` or
+// moves `sync.version`) or under an unexpired exception; conflict markers and expired exceptions fail.
+// With --compare, owned files are also compared with `source.url` at the recorded version.
+// Without a contract it passes silently. .copier-answers.yml + .platform/manifest is read as one.
 //
-// Usage: node scripts/check-platform-conformance.mjs [--base <git ref>]   (no --base: markers and exceptions only)
+// Usage: node scripts/check-platform-conformance.mjs [--base <git ref>] [--compare]
+//        node scripts/check-platform-conformance.mjs --contract   (key=value lines for $GITHUB_OUTPUT)
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-const ANSWERS = '.copier-answers.yml';
-const MANIFEST = '.platform/manifest';
-const EXCEPTIONS = '.platform/exceptions.yml';
+export const CONTRACT = '.platform/contract.yml';
+const LEGACY_ANSWERS = '.copier-answers.yml';
+const LEGACY_MANIFEST = '.platform/manifest';
+const DEFAULT_EXCEPTIONS = '.platform/exceptions.yml';
 const CONFLICT_MARKER = /^(?:<{7}|>{7})(?: |$)/m;
 
+export class ContractError extends Error {}
+
 // gitwildmatch, the .gitignore syntax: a pattern with no inner slash matches at any depth, `**`
 // crosses directories, and a match on a directory covers everything below it.
 export function globToRegExp(glob) {
@@ -40,13 +47,12 @@ export function globToRegExp(glob) {
       }
     } else re += c.replace(/[.+^${}()|\\]/g, '\\$&');
   }
-  // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp — the glob comes from the committed manifest and every metacharacter outside a class is escaped
+  // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp — the glob comes from the committed contract and every metacharacter outside a class is escaped
   return new RegExp(`^${anchored ? '' : '(?:.*/)?'}${re}(?:/.*)?$`);
 }
 
-export function parseManifest(text) {
-  return text
-    .split(/\r?\n/)
+export function parsePatterns(globs) {
+  return globs
     .map((line) => line.trim())
     .filter((line) => line !== '' && !line.startsWith('#'))
     .map((line) => {
@@ -56,8 +62,10 @@ export function parseManifest(text) {
     });
 }
 
+export const parseManifest = (text) => parsePatterns(text.split(/\r?\n/));
+
 // The last pattern that matches decides, as in .gitignore.
-export function inManifest(patterns, path) {
+export function isOwned(patterns, path) {
   let matched = false;
   for (const { negate, regex } of patterns) if (regex.test(path)) matched = !negate;
   return matched;
@@ -70,15 +78,179 @@ const unquote = (value) => {
   return v.replace(/\s+#.*$/, '');
 };
 
-// The subset of YAML .platform/exceptions.yml uses: one `exceptions:` list of flat mappings.
-export function parseExceptions(text) {
+function stripComment(line) {
+  let quote = '';
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = '';
+    } else if (c === '"' || c === "'") quote = c;
+    else if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i);
+  }
+  return line;
+}
+
+function scalar(raw, at) {
+  const text = raw.trim();
+  if (/^[|>][+-]?$/.test(text) || /^[&*!{]/.test(text)) throw new ContractError(`${at}: "${text}" is not supported; write the value on one line`);
+  if (text.startsWith('[')) {
+    if (!text.endsWith(']')) throw new ContractError(`${at}: unclosed "["`);
+    const inner = text.slice(1, -1).trim();
+    return inner === '' ? [] : (inner.match(/"[^"]*"|'[^']*'|[^,]+/g) ?? []).map((item) => scalar(item, at));
+  }
+  if (/^["']/.test(text)) return unquote(text);
+  if (/^-?\d+$/.test(text)) return Number(text);
+  if (text === 'true' || text === 'false') return text === 'true';
+  if (text === '' || text === '~' || text === 'null') return null;
+  return text;
+}
+
+// The YAML a contract needs: nested mappings, block and flow lists of scalars, quotes and comments.
+export function parseYamlSubset(text, file) {
+  const lines = [];
+  text.split(/\r?\n/).forEach((raw, index) => {
+    const content = stripComment(raw).replace(/\s+$/, '');
+    if (content.trim() === '' || /^---\s*$/.test(content)) return;
+    if (/^\s*\t/.test(raw)) throw new ContractError(`${file}:${index + 1}: indent with spaces, not tabs`);
+    lines.push({ indent: content.length - content.trimStart().length, text: content.trim(), at: `${file}:${index + 1}` });
+  });
+  let next = 0;
+  const isItem = (line) => line.text === '-' || line.text.startsWith('- ');
+  const block = (indent) => {
+    if (isItem(lines[next])) {
+      const list = [];
+      while (next < lines.length && lines[next].indent === indent && isItem(lines[next])) {
+        const { text, at } = lines[next++];
+        if (text === '-') throw new ContractError(`${at}: a list item must be a value on the same line`);
+        list.push(scalar(text.slice(2), at));
+      }
+      return list;
+    }
+    const map = {};
+    while (next < lines.length && lines[next].indent === indent && !isItem(lines[next])) {
+      const { text, at } = lines[next++];
+      const pair = text.match(/^([A-Za-z_][\w-]*):(?:\s+(.*))?$/);
+      if (!pair) throw new ContractError(`${at}: cannot read "${text}"; expected "key: value"`);
+      const following = lines[next];
+      const nested = following && (following.indent > indent || (following.indent === indent && isItem(following)));
+      if (pair[2] !== undefined) map[pair[1]] = scalar(pair[2], at);
+      else map[pair[1]] = nested ? block(following.indent) : null;
+    }
+    return map;
+  };
+  if (lines.length === 0) return {};
+  if (lines[0].indent !== 0 || isItem(lines[0])) throw new ContractError(`${lines[0].at}: the file must be a mapping of top-level keys`);
+  const root = block(0);
+  if (next < lines.length) throw new ContractError(`${lines[next].at}: unexpected indentation`);
+  return root;
+}
+
+const isText = (value) => typeof value === 'string' && value.trim() !== '';
+const isMapping = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const repositoryName = (url) => basename(url.replace(/\.git$/, '').replace(/\/+$/, '')) || url;
+
+export function validateContract(data, file = CONTRACT) {
+  const fail = (field, problem) => {
+    throw new ContractError(`${file}: ${field} ${problem}`);
+  };
+  if (!isMapping(data)) fail('the file', 'must be a YAML mapping');
+  if (data.version === undefined || data.version === null) fail('version', 'is required (version: 1)');
+  if (data.version !== 1) fail('version', `${JSON.stringify(data.version)} is not supported; this guard reads version 1`);
+  if (!isMapping(data.source)) fail('source', 'is required: a mapping with at least url');
+  if (!isText(data.source.url)) fail('source.url', 'is required: where the shared code lives');
+  for (const key of ['name', 'changes']) {
+    if (data.source[key] != null && !isText(data.source[key])) fail(`source.${key}`, 'must be text');
+  }
+  if (!Array.isArray(data.owned) || data.owned.length === 0) fail('owned', 'is required: a list of repository-relative globs');
+  data.owned.forEach((glob, index) => isText(glob) || fail(`owned[${index}]`, 'must be a glob'));
+  if (data.exceptions != null && !isText(data.exceptions)) fail('exceptions', 'must be a repository-relative path');
+  const sync = data.sync ?? {};
+  if (!isMapping(sync)) fail('sync', 'must be a mapping');
+  for (const key of ['marker', 'update']) if (sync[key] != null && !isText(sync[key])) fail(`sync.${key}`, 'must be text');
+  if (sync.version != null) {
+    if (!isMapping(sync.version)) fail('sync.version', 'must be a mapping with file and key');
+    for (const key of ['file', 'key']) if (!isText(sync.version[key])) fail(`sync.version.${key}`, 'is required');
+  }
+  return {
+    version: 1,
+    source: { name: data.source.name ?? repositoryName(data.source.url), url: data.source.url, changes: data.source.changes ?? data.source.url },
+    owned: data.owned,
+    exceptions: data.exceptions ?? DEFAULT_EXCEPTIONS,
+    sync: { marker: sync.marker ?? undefined, version: sync.version ?? undefined, update: sync.update ?? undefined },
+    file,
+  };
+}
+
+// What harness 3.7.0 and workflows 1.11.0 read before the contract existed.
+export function legacyContract(answers, manifest) {
+  const source = topLevelValue(answers, '_src_path');
+  if (!source) throw new ContractError(`${LEGACY_ANSWERS}: _src_path is required to read it as a platform contract`);
+  const url = source.replace(/^git\+/, '').replace(/^gh:/, 'https://github.com/').replace(/^gl:/, 'https://gitlab.com/');
+  return {
+    version: 1,
+    source: { name: repositoryName(url), url, changes: url },
+    owned: manifest.split(/\r?\n/),
+    exceptions: DEFAULT_EXCEPTIONS,
+    sync: {
+      marker: LEGACY_ANSWERS,
+      version: { file: LEGACY_ANSWERS, key: '_commit' },
+      update: 'copier update --trust --defaults --conflict inline',
+    },
+    file: `${LEGACY_ANSWERS} + ${LEGACY_MANIFEST}`,
+  };
+}
+
+export function topLevelValue(text, key) {
+  if (text === undefined) return undefined;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp — the key is escaped
+  const value = text.match(new RegExp(`^${escaped}:[ \\t]*(.*?)[ \\t]*$`, 'm'))?.[1];
+  return value === undefined ? undefined : unquote(stripComment(value)) || undefined;
+}
+
+// undefined when the repository declares no contract, explicit or legacy.
+export function readContract(root) {
+  const read = (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined);
+  const text = read(CONTRACT);
+  if (text !== undefined) return validateContract(parseYamlSubset(text, CONTRACT));
+  const answers = read(LEGACY_ANSWERS);
+  const manifest = read(LEGACY_MANIFEST);
+  return answers !== undefined && manifest !== undefined ? legacyContract(answers, manifest) : undefined;
+}
+
+export const recordedVersion = (contract, readFile) =>
+  contract.sync.version ? topLevelValue(readFile(contract.sync.version.file), contract.sync.version.key) : undefined;
+
+export function normalizeUrl(url) {
+  return url
+    .trim()
+    .replace(/^git\+/, '')
+    .replace(/^gh:/, 'https://github.com/')
+    .replace(/^git@([^:]+):/, 'https://$1/')
+    .replace(/^(https?:\/\/)[^@/]+@/, '$1')
+    .replace(/\.git$/, '')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+}
+
+// The template repository carries the contract too; its owned paths are its own.
+function isSourceRepository(root, contract) {
+  try {
+    return normalizeUrl(git(root, ['remote', 'get-url', 'origin'])) === normalizeUrl(contract.source.url);
+  } catch {
+    return false;
+  }
+}
+
+// The subset of YAML the exceptions file uses: one `exceptions:` list of flat mappings.
+export function parseExceptions(text, file = DEFAULT_EXCEPTIONS) {
   const entries = [];
   const problems = [];
   let inList = false;
   text.split(/\r?\n/).forEach((raw, index) => {
     const line = raw.replace(/\s+$/, '');
     if (line.trim() === '' || line.trim().startsWith('#')) return;
-    const at = `${EXCEPTIONS}:${index + 1}`;
+    const at = `${file}:${index + 1}`;
     const top = line.match(/^exceptions:\s*(\[\s*\])?\s*(?:#.*)?$/);
     if (top) {
       inList = !top[1];
@@ -91,7 +263,7 @@ export function parseExceptions(text) {
     else problems.push(`${at}: cannot read "${line.trim()}"; expected exceptions: [{ path, reason, issue, expires }]`);
   });
   for (const entry of entries) {
-    const at = `${EXCEPTIONS}:${entry.line}`;
+    const at = `${file}:${entry.line}`;
     const missing = ['path', 'reason', 'issue', 'expires'].filter((key) => !entry[key]);
     if (missing.length > 0) problems.push(`${at}: exception without ${missing.join(', ')}`);
     else if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.expires) || Number.isNaN(Date.parse(entry.expires))) {
@@ -102,10 +274,14 @@ export function parseExceptions(text) {
   return { exceptions: valid.map((entry) => ({ ...entry, regex: globToRegExp(entry.path) })), problems };
 }
 
-const templateCommit = (answers) => answers?.match(/^_commit:\s*(.+?)\s*$/m)?.[1]?.replace(/^["']|["']$/g, '');
-
 function git(root, args) {
-  return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    maxBuffer: 64 * 1024 * 1024,
+  });
 }
 
 function gitShow(root, ref, path) {
@@ -116,63 +292,162 @@ function gitShow(root, ref, path) {
   }
 }
 
-export function checkConformance(root, { base, today = new Date().toISOString().slice(0, 10) } = {}) {
-  const read = (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined);
-  const answers = read(ANSWERS);
-  if (answers === undefined) return { adopted: false, failures: [], notes: [] };
+// `git ls-tree -r` and `git ls-files -s` lines, as path -> blob id; submodules are skipped.
+function blobIds(listing, idField) {
+  const ids = new Map();
+  for (const entry of listing.split('\0').filter(Boolean)) {
+    const [meta, path] = entry.split('\t');
+    const fields = meta.split(' ');
+    if (fields[0] !== '160000') ids.set(path, fields[idField]);
+  }
+  return ids;
+}
 
+// Blob ids of the source's files at the version: a tag or commit, or `git describe` output.
+function sourceBlobs(url, version) {
+  const scratch = mkdtempSync(join(tmpdir(), 'platform-source-'));
+  try {
+    git(scratch, ['init', '--quiet', '--bare']);
+    let ref = 'FETCH_HEAD';
+    try {
+      git(scratch, ['fetch', '--quiet', '--depth', '1', url, version]);
+    } catch {
+      git(scratch, ['fetch', '--quiet', url, '+refs/tags/*:refs/tags/*', '+refs/heads/*:refs/heads/*']);
+      ref = version.match(/-\d+-g([0-9a-f]{4,})$/)?.[1] ?? version;
+    }
+    return blobIds(git(scratch, ['ls-tree', '-r', '-z', `${ref}^{commit}`]), 2);
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+function compareWithSource(root, contract, patterns, live, version) {
   const failures = [];
   const notes = [];
-  const manifestText = read(MANIFEST);
-  if (manifestText === undefined) return { adopted: true, failures: [`${ANSWERS} exists but ${MANIFEST} does not`], notes };
-  const patterns = parseManifest(manifestText);
+  const { name, url, changes } = contract.source;
+  if (!version) return { failures: [`cannot compare with ${name}: ${contract.sync.version?.file ?? 'the contract'} records no template version (sync.version)`], notes };
+  let source;
+  try {
+    source = sourceBlobs(url, version);
+  } catch (error) {
+    const reason = String(error.stderr ?? error.message).trim().split('\n').at(-1);
+    return { failures, notes: [`cannot read ${url} at ${version} (${reason}); owned files were not compared with the source`] };
+  }
+  const local = blobIds(git(root, ['ls-files', '-s', '-z']), 1);
+  for (const [path, id] of source) {
+    if (!isOwned(patterns, path) || local.get(path) === id) continue;
+    const problem = local.has(path) ? `differs from ${name} at ${version}` : `is missing; ${name} at ${version} has it`;
+    const covered = live.find((entry) => entry.regex.test(path));
+    if (covered) notes.push(`${path}: ${problem}, allowed by the exception until ${covered.expires} (${covered.issue})`);
+    else failures.push(`${path}: ${problem}; change it in ${name} (${changes}) or add an exception to ${contract.exceptions}`);
+  }
+  const onlyHere = [...local.keys()].filter((path) => isOwned(patterns, path) && !source.has(path));
+  if (onlyHere.length > 0) notes.push(`${onlyHere.length} owned file(s) are not in ${name} at ${version} under the same path; not compared`);
+  return { failures, notes };
+}
+
+export function checkConformance(root, { base, compare = false, today = new Date().toISOString().slice(0, 10) } = {}) {
+  const read = (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined);
+  let contract;
+  try {
+    contract = readContract(root);
+  } catch (error) {
+    if (error instanceof ContractError) return { adopted: true, failures: [error.message], notes: [] };
+    throw error;
+  }
+  if (contract === undefined) return { adopted: false, failures: [], notes: [] };
+  if (isSourceRepository(root, contract)) {
+    return { adopted: true, failures: [], notes: [`this repository is ${contract.source.name}, the source of its own owned paths`] };
+  }
 
-  const { exceptions, problems } = parseExceptions(read(EXCEPTIONS) ?? '');
+  const failures = [];
+  const notes = [];
+  const patterns = parsePatterns(contract.owned);
+  const { exceptions, problems } = parseExceptions(read(contract.exceptions) ?? '', contract.exceptions);
   failures.push(...problems);
   const live = exceptions.filter((entry) => entry.expires >= today);
   for (const entry of exceptions.filter((e) => e.expires < today)) {
-    failures.push(`${EXCEPTIONS}:${entry.line}: the exception for ${entry.path} expired on ${entry.expires} (${entry.issue}); converge the code or renew it`);
+    failures.push(`${contract.exceptions}:${entry.line}: the exception for ${entry.path} expired on ${entry.expires} (${entry.issue}); converge the code or renew it`);
   }
 
   const tracked = git(root, ['ls-files', '-z']).split('\0').filter(Boolean);
-  for (const file of tracked.filter((path) => inManifest(patterns, path))) {
+  for (const file of tracked.filter((path) => isOwned(patterns, path))) {
     const text = read(file);
     if (text !== undefined && !text.includes('\0') && CONFLICT_MARKER.test(text)) {
       failures.push(`${file}: unresolved template-sync conflict markers`);
     }
   }
 
+  const version = recordedVersion(contract, read);
   if (base !== undefined) {
     const changed = git(root, ['diff', '--name-only', '--no-renames', `${base}...HEAD`]).split('\n').filter(Boolean);
-    const platform = changed.filter((path) => inManifest(patterns, path));
-    const before = templateCommit(gitShow(root, base, ANSWERS));
-    const after = templateCommit(answers);
-    if (before !== after) {
-      notes.push(`template sync ${before ?? '(adoption)'} -> ${after}: ${platform.length} platform file(s) may change`);
+    const owned = changed.filter((path) => isOwned(patterns, path));
+    const before = contract.sync.version ? topLevelValue(gitShow(root, base, contract.sync.version.file), contract.sync.version.key) : undefined;
+    const moved = contract.sync.version !== undefined && before !== version;
+    if (moved || (contract.sync.marker && changed.includes(contract.sync.marker))) {
+      const step = moved ? `${before ?? '(adoption)'} -> ${version}` : `(${contract.sync.marker} changed)`;
+      notes.push(`template sync ${step}: ${owned.length} owned file(s) may change`);
     } else {
-      for (const path of platform) {
+      for (const path of owned) {
         const covered = live.find((entry) => entry.regex.test(path));
         if (covered) notes.push(`${path}: allowed by the exception until ${covered.expires} (${covered.issue})`);
-        else failures.push(`${path}: platform file changed outside a template sync; change it in Kitchen-Sink, or add an exception to ${EXCEPTIONS}`);
+        else failures.push(`${path}: owned by ${contract.source.name} and changed outside a template sync; change it in ${contract.source.name} (${contract.source.changes}), or add an exception to ${contract.exceptions}`);
       }
     }
   }
+  if (compare) {
+    const result = compareWithSource(root, contract, patterns, live, version);
+    failures.push(...result.failures);
+    notes.push(...result.notes);
+  }
   return { adopted: true, failures, notes };
 }
 
+// One key=value line per field, for $GITHUB_OUTPUT; contract=absent when there is none.
+export function contractOutputs(root) {
+  const contract = readContract(root);
+  if (contract === undefined) return 'contract=absent\n';
+  const read = (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined);
+  const web = contract.source.url.replace(/^git\+/, '').replace(/\.git$/, '');
+  const fields = {
+    contract: 'present',
+    self: String(isSourceRepository(root, contract)),
+    source_name: contract.source.name,
+    source_url: contract.source.url,
+    source_web: /^https?:\/\//.test(web) ? web : '',
+    version: recordedVersion(contract, read) ?? '',
+    update: contract.sync.update ?? '',
+  };
+  for (const [key, value] of Object.entries(fields)) {
+    if (/[\r\n]/.test(value)) throw new ContractError(`${contract.file}: ${key} must be a single line`);
+  }
+  return Object.entries(fields).map(([key, value]) => `${key}=${value}\n`).join('');
+}
+
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = process.argv.slice(2);
   const baseIndex = args.indexOf('--base');
   const base = baseIndex === -1 ? undefined : args[baseIndex + 1];
-  if (baseIndex !== -1 && !base) {
-    console.error('usage: node scripts/check-platform-conformance.mjs [--base <git ref>]');
+  const unknown = args.filter((arg, i) => i !== baseIndex + 1 || baseIndex === -1).filter((arg) => !['--base', '--compare', '--contract'].includes(arg));
+  if ((baseIndex !== -1 && !base) || unknown.length > 0) {
+    console.error('usage: node scripts/check-platform-conformance.mjs [--base <git ref>] [--compare] | --contract');
     process.exit(2);
   }
   const root = fileURLToPath(new URL('..', import.meta.url));
-  const { adopted, failures, notes } = checkConformance(root, { base });
+  if (args.includes('--contract')) {
+    try {
+      process.stdout.write(contractOutputs(root));
+      process.exit(0);
+    } catch (error) {
+      if (!(error instanceof ContractError)) throw error;
+      console.error(`✗ ${error.message}`);
+      process.exit(1);
+    }
+  }
+  const { adopted, failures, notes } = checkConformance(root, { base, compare: args.includes('--compare') });
   if (!adopted) process.exit(0);
   for (const note of notes) console.log(`· ${note}`);
   for (const failure of failures) console.error(`✗ ${failure}`);
-  if (failures.length === 0) console.log('✓ platform files match the template');
+  if (failures.length === 0) console.log('✓ owned files match the template');
   process.exit(failures.length === 0 ? 0 : 1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",