@arjunkhera/atlas 0.3.46 → 0.3.48

package/door/lib/pull-request.mjs

@@ -21,8 +21,9 @@ export const PROVENANCE_SOURCES = Object.freeze(['owner words', 'repo read', 'ta
 // The one label every tooling pull request carries. A person filters on it.
 export const TOOLING_LABEL = 'atlas-helper';
 
-// The only two files the tooling writer may write.
-export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH]);
+// The only files the tooling writer may write: the check, its workflow, and
+// the pull request template when the repo has none.
+export const TOOLING_PATHS = Object.freeze([CHECK_PATH, WORKFLOW_PATH, '.github/pull_request_template.md']);
 
 export class ChangeError extends Error {}
 

package/door/lib/tooling.mjs

@@ -20,8 +20,19 @@ import { dirname, join } from 'node:path';
 import { CHECK_PATH, WORKFLOW_PATH, WORKFLOW_TEMPLATE, CHECK_VERSION, sha256, parseYaml } from '../../shape/check.mjs';
 import { packagedCheck, packagePackageVersion, PACKAGE_CHECK_SOURCE } from './releases.mjs';
 import { status } from './status.mjs';
+import { PR_TEMPLATE_PATH } from './upkeep.mjs';
 
-export { CHECK_PATH, WORKFLOW_PATH, PACKAGE_CHECK_SOURCE };
+export { CHECK_PATH, WORKFLOW_PATH, PACKAGE_CHECK_SOURCE, PR_TEMPLATE_PATH };
+
+// The pull request template (roadmap R8). The writer puts it into a repo that
+// has none, and never replaces a template the repo keeps.
+export const PACKAGE_TEMPLATE_SOURCE = 'door/templates/pull_request_template.md';
+// A package with no template file writes none.
+const packagedTemplate = (packageRoot) => {
+  const full = join(packageRoot, PACKAGE_TEMPLATE_SOURCE);
+  return existsSync(full) ? readFileSync(full, 'utf8') : null;
+};
+const templateMissing = (root, packageRoot) => packagedTemplate(packageRoot) !== null && !existsSync(join(root, PR_TEMPLATE_PATH));
 
 export class ToolingRefusal extends Error {
   constructor(message, { current = false } = {}) { super(message); this.current = current; }
@@ -64,7 +75,7 @@ export function mayWrite(root, packageRoot, { replaceUnknown = false, workflowOn
     throw new ToolingRefusal(`this package's ${PACKAGE_CHECK_SOURCE} is ${pkg.row ? 'not the newest release' : 'in no release'} of the check, so it is not written into another repo. Use a released Atlas.`);
   }
   const now = status({ root, packageRoot });
-  if (now.state === 'current' && !workflowOnly) {
+  if (now.state === 'current' && !workflowOnly && !templateMissing(root, packageRoot)) {
     throw new ToolingRefusal(`this repo's check is already current. ${readWorkflow(root) === WORKFLOW_TEMPLATE ? 'Both files match the package, so there is nothing to write.' : 'Its workflow file differs from the package; pass --workflow to rewrite only that file.'}`, { current: true });
   }
   if (now.state === 'unknown' && !replaceUnknown && !own) {
@@ -90,22 +101,33 @@ export function write(root, packageRoot, { dryRun = false, replaceUnknown = fals
     }
     rows.push({ path, state, sha256: sha256(contents), was: was === null ? null : sha256(was) });
   }
-  if (!dryRun && rows.every((row) => row.state === 'unchanged')) {
-    throw new ToolingRefusal('this repo is already current: both files match the package, so there is nothing to write.', { current: true });
+  const template = workflowOnly ? null : packagedTemplate(packageRoot);
+  if (template !== null) {
+    const contents = template;
+    const full = join(root, PR_TEMPLATE_PATH);
+    const kept = existsSync(full);
+    if (!kept && !dryRun) {
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, contents);
+    }
+    rows.push({ path: PR_TEMPLATE_PATH, state: kept ? 'kept' : 'written', sha256: sha256(kept ? readFileSync(full, 'utf8') : contents), was: kept ? sha256(readFileSync(full, 'utf8')) : null });
+  }
+  if (!dryRun && rows.every((row) => row.state === 'unchanged' || row.state === 'kept')) {
+    throw new ToolingRefusal('this repo is already current: its Atlas files match the package, so there is nothing to write.', { current: true });
   }
-  return { rows, version: packagePackageVersion(packageRoot), check_version: CHECK_VERSION, status: before?.state ?? null, changed: rows.some((row) => row.state !== 'unchanged') };
+  return { rows, version: packagePackageVersion(packageRoot), check_version: CHECK_VERSION, status: before?.state ?? null, changed: rows.some((row) => row.state !== 'unchanged' && row.state !== 'kept') };
 }
 
 // The change set the pull request machinery takes, for the two files above.
 export function changes(root, packageRoot, { replaceUnknown = false, workflowOnly = false } = {}) {
   mayWrite(root, packageRoot, { replaceUnknown, workflowOnly });
   const { rows, version } = write(root, packageRoot, { dryRun: true, workflowOnly });
-  if (rows.every((row) => row.state === 'unchanged')) {
-    throw new ToolingRefusal('this repo is already current: both files match the package, so there is nothing to open.', { current: true });
+  if (rows.every((row) => row.state === 'unchanged' || row.state === 'kept')) {
+    throw new ToolingRefusal('this repo is already current: its Atlas files match the package, so there is nothing to open.', { current: true });
   }
-  const wanted = packagedFiles(packageRoot);
+  const wanted = { ...packagedFiles(packageRoot), [PR_TEMPLATE_PATH]: packagedTemplate(packageRoot) };
   return rows
-    .filter((row) => row.state !== 'unchanged')
+    .filter((row) => row.state !== 'unchanged' && row.state !== 'kept')
     .map((row) => ({
       path: row.path,
       contents: wanted[row.path],
@@ -113,7 +135,9 @@ export function changes(root, packageRoot, { replaceUnknown = false, workflowOnl
         source: 'repo read',
         detail: row.path === CHECK_PATH
           ? `copied byte for byte from ${PACKAGE_CHECK_SOURCE}, check version ${CHECK_VERSION}, in Atlas ${version}`
-          : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
+          : row.path === PR_TEMPLATE_PATH
+            ? `copied from ${PACKAGE_TEMPLATE_SOURCE}, Atlas ${version}; the repo had no pull request template`
+            : `written from the WORKFLOW_TEMPLATE constant in ${PACKAGE_CHECK_SOURCE}, Atlas ${version}`,
       },
     }));
 }

package/door/lib/upkeep.mjs

@@ -119,21 +119,57 @@ const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i
 const SHORT = /\bitems?\b[\s:#`(_-]*(?:id[\s:#`_-]*)?([0-9a-f]{8})\b/i;
 const NO_ITEM = /\bno item:\s*(\S[^\n]*)/i;
 
+// The six headings of the pull request text (roadmap R8, design
+// docs/design-docs/pr-template/). The template in door/templates/ holds them,
+// and a test keeps the two equal. A later job reads the text under each one.
+export const PR_HEADINGS = Object.freeze(['Definition of done', 'Kind of change', 'Undo', 'Behaviour change', 'Changed tests', 'Proof']);
+export const PR_TEMPLATE_PATH = '.github/pull_request_template.md';
+
+// A pull request text without its HTML comments. The template's own comment
+// says "no item:", so the item rule and the heading rule never read a comment.
+const withoutComments = (text) => String(text ?? '').replace(/<!--[\s\S]*?(?:-->|$)/g, '');
+
+// The sections of a pull request text: each `## ` heading and the text under it.
+export function prSections(body) {
+  const sections = new Map();
+  let current = null;
+  for (const line of withoutComments(body).split('\n')) {
+    const heading = /^##\s+(.+?)\s*#*\s*$/.exec(line);
+    if (heading) { current = heading[1].toLowerCase(); sections.set(current, []); continue; }
+    if (current) sections.get(current).push(line);
+  }
+  return new Map([...sections].map(([name, lines]) => [name, lines.join('\n').trim()]));
+}
+
+// The findings of the text of a pull request that names an item.
+export function prTextFindings(body) {
+  const sections = prSections(body);
+  const findings = [];
+  for (const heading of PR_HEADINGS) {
+    if (!sections.has(heading.toLowerCase())) findings.push(`pr text: missing heading "${heading}"`);
+  }
+  const done = sections.get('definition of done');
+  if (done !== undefined && !/^[ \t]*\d+[.)][ \t]+\S/m.test(done)) findings.push('pr text: "Definition of done" has no numbered line');
+  const behaviour = sections.get('behaviour change');
+  if (behaviour !== undefined && !/\b(yes|no)\b/i.test(behaviour)) findings.push('pr text: "Behaviour change" says neither yes nor no');
+  return findings;
+}
+
 // Does the pull request name its tracker item? Read from a GitHub event file.
 export function itemNamed(event) {
   const pr = event?.pull_request;
   if (!pr) return { checked: false };
-  if (pr.user?.type === 'Bot') return { checked: true, ok: true, how: `opened by a bot (${pr.user.login})` };
-  const texts = [pr.title, pr.body, pr.head?.ref].map((one) => String(one ?? ''));
+  if (pr.user?.type === 'Bot') return { checked: true, ok: true, how: `opened by a bot (${pr.user.login})`, named: false };
+  const texts = [pr.title, withoutComments(pr.body), pr.head?.ref].map((one) => String(one ?? ''));
   for (const text of texts) {
     const full = text.match(UUID);
-    if (full) return { checked: true, ok: true, how: `names item ${full[0]}` };
+    if (full) return { checked: true, ok: true, how: `names item ${full[0]}`, named: true };
     const short = text.match(SHORT);
-    if (short) return { checked: true, ok: true, how: `names item ${short[1]}` };
+    if (short) return { checked: true, ok: true, how: `names item ${short[1]}`, named: true };
   }
   for (const text of texts) {
     const none = text.match(NO_ITEM);
-    if (none) return { checked: true, ok: true, how: `no item: ${none[1].trim()}` };
+    if (none) return { checked: true, ok: true, how: `no item: ${none[1].trim()}`, named: false };
   }
   return { checked: true, ok: false };
 }
@@ -149,7 +185,11 @@ export function upkeepCheck(root, { event = null } = {}) {
   for (const one of dead.slice(0, MAX_LISTED)) findings.push(`dead link: ${one.file}:${one.line} -> ${one.target}`);
   if (dead.length > MAX_LISTED) findings.push(`dead link: ${dead.length - MAX_LISTED} more`);
   if (item.checked && !item.ok) findings.push('item: the pull request names no tracker item. Put the item id in the title, the body or the branch, or write "no item:" and a reason');
-  return { green: findings.length === 0, findings, index, dead, item };
+  // The heading check holds a pull request that names an item, in a repo that
+  // keeps the Atlas template. A repo without the template is not held yet.
+  const text = { checked: Boolean(item.named) && existsSync(join(root, PR_TEMPLATE_PATH)) };
+  if (text.checked) findings.push(...prTextFindings(event.pull_request.body));
+  return { green: findings.length === 0, findings, index, dead, item, text };
 }
 
 export function upkeepCommand({ what, event: eventFile, json = false }, root, line) {
@@ -163,6 +203,7 @@ export function upkeepCommand({ what, event: eventFile, json = false }, root, li
   line(`docs index: ${result.index.checked ? `${result.index.unlisted.length} not listed, ${result.index.gone.length} gone` : 'no docs/ folder'}`);
   line(`dead links: ${result.dead.length}`);
   line(`item: ${!result.item.checked ? 'not a pull request' : result.item.ok ? result.item.how : 'none named'}`);
+  line(`pr text: ${result.text.checked ? 'the six headings were read' : 'not checked'}`);
   for (const finding of result.findings) line(`  - ${finding}`);
   line(`upkeep check: ${result.green ? 'GREEN' : 'RED'}`);
   return result.green ? 0 : 1;

package/door/templates/pull_request_template.md

@@ -0,0 +1,25 @@
+<!-- The Atlas pull request text. Name the tracker item in the title, this text or the branch, or write "no item:" and a reason. When the text names an item, `atlas upkeep check` needs each heading below. -->
+
+## Definition of done
+
+1. 
+
+## Kind of change
+
+
+
+## Undo
+
+
+
+## Behaviour change
+
+No.
+
+## Changed tests
+
+None.
+
+## Proof
+
+

package/owner-only.yaml

@@ -0,0 +1,238 @@
+# The owner-only list: the kinds of change that always come to the owner.
+#
+# The owner picked these eight classes on 24 October 2026 (decision 1c2f0d53,
+# item 94b2e2ff). Design: docs/design-docs/owner-only-list/ in the Atlas repo.
+#
+# Each class has two examples and its net. `code` means the reader in
+# door/lib/owner-only.mjs matches it on a diff. `review` means the review job
+# reads for it. A code class lists its signs: exact things that the reader
+# matches.
+#
+# The floor below holds in every repo, whatever the repo's own `owner_only:`
+# list says. The reader takes the floor from this package and the repo list
+# from the base commit, so a pull request cannot take itself off either one.
+#
+# Sign types:
+#   path          a changed path that matches one of `paths`
+#   added_line    an added line, in a file of `paths`, that matches `pattern`
+#   secret        an added line that matches a secret pattern of shape/check.mjs
+#   json_keys     a change to one of `keys` of a JSON file of `paths`
+#   surface       a line that `line` matches, keyed by its first group, is gone
+#                 at the head, or lost a part that `part` matches
+#   schema        a JSON file of `paths` lost a key, lost an enum value, or
+#                 gained a required field; versioned files compare newest to newest
+#   any_change    any change to a file of `paths`
+#
+# A code class with no signs says where its code net comes from instead:
+# `signs_from: repo` (each repo's `owner_only:` list) or `signs_from: floor`.
+#
+# Paths match on whole folder names and with no case. `**/` matches any depth.
+# A path that ends in `/` is a folder.
+
+classes:
+  - id: money
+    name: Money
+    examples:
+      - A new paid plan, or a change to a price.
+      - A cloud resource that bills by the hour.
+    net:
+      - review
+
+  - id: credentials
+    name: Credentials and keys
+    examples:
+      - A new API key, or a key written into a file.
+      - A change to the list of credentials that a repo names.
+    net:
+      - code
+      - review
+    signs:
+      - id: secret-value
+        type: secret
+      - id: credential-files
+        type: path
+        paths:
+          - "atlas/credentials.yaml"
+          - "**/.env"
+          - "**/.env.*"
+          - "**/*.pem"
+          - "**/*.key"
+
+  - id: outside-visibility
+    name: Outside visibility
+    examples:
+      - A public repo, or a public post.
+      - A release that removes a command that other people use.
+    net:
+      - code
+      - review
+    signs:
+      - id: release-surface
+        type: json_keys
+        paths:
+          - "**/package.json"
+        keys:
+          - name
+          - private
+          - publishConfig
+          - files
+          - bin
+          - main
+          - exports
+          - scripts
+      - id: removed-command-or-switch
+        type: surface
+        paths:
+          - "packages/atlas/door/cli.mjs"
+        line: "^  '?([a-z][a-z-]*)'?: \\{.*\\},?\\s*$"
+        part: "'?([a-z][a-z-]*)'?: '(?:switch|value|optional)'"
+      - id: removed-mcp-tool
+        type: surface
+        paths:
+          - "packages/atlas/work/mcp.mjs"
+        line: "^\\s*\\{ name: '([a-z_]+)'"
+      - id: kit-manifest
+        type: any_change
+        # A release moves only the "atlas" version line. That is not a sign.
+        version_key: atlas
+        paths:
+          - "**/test/atlas/manifest.json"
+          - "packages/atlas/tests/link-check.mjs"
+      - id: narrowed-schema
+        type: schema
+        paths:
+          - "packages/atlas/work/manifest-*.json"
+
+  - id: lost-data
+    name: Data that cannot be undone
+    examples:
+      - A migration that drops a table.
+      - A script that deletes rows from a live store.
+    net:
+      - code
+      - review
+    signs:
+      - id: drop-or-delete-in-migration
+        type: added_line
+        paths:
+          - "**/migrations/**"
+          - "**/migrate/**"
+          - "**/*.sql"
+        pattern: "(?i)\\b(drop|delete|truncate)\\b|\\b(drop|truncate)[A-Z_]"
+
+  - id: security
+    name: Security code
+    examples:
+      - The code that checks who may sign in.
+      - The code that keeps one tenant's rows from another.
+    net:
+      - code
+      - review
+    # No path holds sign-in code in every repo, so each repo lists its own
+    # security paths under `owner_only:` in atlas.yaml.
+    signs_from: repo
+
+  - id: new-service
+    name: A new outside service or a new repo
+    examples:
+      - A call to a new outside API.
+      - A new repo, or a new GitHub App.
+    net:
+      - review
+
+  - id: rule-book
+    name: The rule book
+    examples:
+      - An entry file, a path rule or a hook.
+      - The owner-only list itself.
+    net:
+      - code
+      - review
+    # The floor below is the code net of this class, with each repo's own list.
+    signs_from: floor
+
+  - id: direction
+    name: Direction
+    examples:
+      - What to build next.
+      - A goal of a product, or a change to a locked design.
+    net:
+      - review
+
+# The floor: rule-book paths in every repo. Each entry is class rule-book.
+# `follow` means the reader also reads the file for names: each file that it
+# names with an @ import, a Markdown link or a path in backticks joins the
+# floor, and the reader follows names out of that file in turn. A plugin
+# root's skills, agents, hooks and commands are followed the same way.
+# `version_only_exempt` lets a change to the version alone pass, because the
+# owner took Atlas's own releases off the list.
+floor:
+  - path: "**/CLAUDE.md"
+    rule: entry file
+    follow: true
+  - path: "**/CLAUDE.local.md"
+    rule: entry file
+    follow: true
+  - path: "**/AGENTS.md"
+    rule: entry file
+    follow: true
+  - path: "**/.claude/"
+    rule: .claude at any depth
+    follow: true
+  - path: "**/.claude-plugin/"
+    rule: .claude-plugin at any depth
+  - path: ".mcp.json"
+    rule: root MCP servers
+  - path: ".github/actions/"
+    rule: CI actions
+  - path: ".github/workflows/"
+    rule: CI workflows
+  - path: ".github/atlas/"
+    rule: the Atlas check copy
+  - path: "atlas.yaml"
+    rule: atlas.yaml keys
+  - path: "atlas/"
+    rule: repo facts
+  - path: "**/.gitattributes"
+    rule: git attributes
+  - path: ".gitmodules"
+    rule: submodules
+  - path: "**/.github/CODEOWNERS"
+    rule: code owners
+  - path: "docs/intake/"
+    rule: the owner's words
+  - path: "archive/"
+    rule: archive
+  - path: "packages/atlas/owner-only.yaml"
+    rule: the owner-only list
+  - path: "packages/atlas/door/lib/owner-only.mjs"
+    rule: the owner-only reader
+  - path: "packages/atlas/package.json"
+    rule: the package manifest
+    version_only_exempt: true
+  - path: "packages/atlas/.claude-plugin/plugin.json"
+    rule: the plugin manifest
+    version_only_exempt: true
+
+# The entry map. A doc that only it names is not on the floor, and the reader
+# does not follow names out of it (shape/check.mjs, the exemption).
+entry_map: docs/index.md
+
+# The keys of atlas.yaml whose change is always owner-only. A change to any
+# other key is owner-only too, until roadmap R62 lists the safe ones. The one
+# change that passes is an addition under `parts:`.
+atlas_yaml:
+  add_only:
+    - parts
+  fixed:
+    - owner_only
+    - areas
+    - required_checks
+    - product
+    - product_paths
+    - repo
+    - kind
+    - kinds
+    - up_to_date
+    - brake
+    - spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",
@@ -26,7 +26,8 @@
     "agents/",
     "hooks/",
     ".claude-plugin/",
-    ".mcp.json"
+    ".mcp.json",
+    "owner-only.yaml"
   ],
   "peerDependencies": {
     "playwright": ">=1.40.0"

package/shape/check.mjs

@@ -34,7 +34,7 @@ export const sha256 = (text) => createHash('sha256').update(String(text ?? ''),
 // Whether a copy is current or behind is not decided here. CI has no package
 // and no network. The session verb decides it, from the release list that
 // ships beside this file in the package, shape/releases.json.
-export const CHECK_VERSION = 4;
+export const CHECK_VERSION = 5;
 
 // ---------------------------------------------------------------------------
 // The spec. One object per version. The check reads a version it has here and
@@ -774,7 +774,11 @@ function indentOf(line) {
   return line.length - line.trimStart().length;
 }
 
-export function parseYaml(source) {
+// `strict` is for atlas.yaml. It refuses a key that appears twice, an anchor,
+// an alias and a merge key. Each one lets two readers see two different maps
+// in one file, and the owner-only reader and this check must see the same one
+// (security review of the owner-only list, 24 October 2026).
+export function parseYaml(source, { strict = false } = {}) {
   const raw = String(source ?? '').replace(/\r\n?/g, '\n').split('\n');
   const lines = [];
   for (let index = 0; index < raw.length; index += 1) {
@@ -825,6 +829,7 @@ export function parseYaml(source) {
       const body = line.text.trimStart();
       if (!body.startsWith('- ') && body !== '-') break;
       const rest = body === '-' ? '' : body.slice(2);
+      if (strict && /^[&*]/.test(rest.trim())) throw new YamlError('an anchor or an alias is not read in strict mode', line.number, line.indent);
       state.at += 1;
       if (!rest.trim()) { out.push(value(indent + 1)); continue; }
       const match = KEY.exec(rest);
@@ -851,6 +856,11 @@ export function parseYaml(source) {
       if (!match) throw new YamlError('this line is neither a key nor a list entry', line.number, line.indent);
       const key = match[1] !== undefined ? match[1] : match[2] !== undefined ? match[2].replaceAll("''", "'") : match[3].trim();
       const rest = (match[4] ?? '').trim();
+      if (strict) {
+        if (Object.hasOwn(out, key)) throw new YamlError(`the key "${key}" appears twice`, line.number, line.indent);
+        if (key === '<<' || /^[&*]/.test(key)) throw new YamlError('a merge key, an anchor or an alias is not read in strict mode', line.number, line.indent);
+        if (/^[&*]/.test(rest)) throw new YamlError('an anchor or an alias is not read in strict mode', line.number, line.indent);
+      }
       state.at += 1;
       if (/^[|>][-+]?\d*$/.test(rest)) { out[key] = blockScalar(rest, indent); continue; }
       if (rest && !rest.startsWith('#')) { out[key] = scalar(rest, line.number); continue; }
@@ -1428,11 +1438,41 @@ function byReference(context, spec) {
   return applyExemption([...found.values()].sort((a, b) => a.path.localeCompare(b.path)));
 }
 
+// The eight classes of the owner-only list. The authority is the package's
+// owner-only.yaml, and a test keeps the two equal. This copy exists because the
+// check runs alone in each repo's CI, where the package is not there.
+export const OWNER_ONLY_CLASSES = Object.freeze(['money', 'credentials', 'outside-visibility', 'lost-data', 'security', 'new-service', 'rule-book', 'direction']);
+
+const stringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.trim() !== '');
+
+// The three keys of the owner-only list in atlas.yaml. Each is optional. When
+// one is there, its shape is checked, and an unknown class is an error.
+export function ownerOnlyErrors(facts) {
+  const errors = [];
+  if (!facts || typeof facts !== 'object') return errors;
+  if (Object.hasOwn(facts, 'owner_only')) {
+    const list = facts.owner_only;
+    if (!Array.isArray(list)) errors.push('atlas.yaml: owner_only is not a list');
+    else list.forEach((entry, index) => {
+      const at = `atlas.yaml: owner_only[${index}]`;
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) { errors.push(`${at} is not a map with a path and a class`); return; }
+      for (const key of Object.keys(entry)) if (!['path', 'class', 'why', 'except'].includes(key)) errors.push(`${at} has the key "${key}"; the keys are path, class, why and except`);
+      if (typeof entry.path !== 'string' || !entry.path.trim()) errors.push(`${at} has no path`);
+      if (!OWNER_ONLY_CLASSES.includes(entry.class)) errors.push(`${at}.class "${entry.class}" is not a class of owner-only.yaml; the classes are ${OWNER_ONLY_CLASSES.join(', ')}`);
+      if (entry.except !== undefined && !stringList(entry.except)) errors.push(`${at}.except is not a list of paths`);
+    });
+  }
+  for (const key of ['required_checks', 'product_paths']) {
+    if (Object.hasOwn(facts, key) && !stringList(facts[key])) errors.push(`atlas.yaml: ${key} is not a list of names`);
+  }
+  return errors;
+}
+
 export function readFacts(root) {
   const text = readText(root, 'atlas.yaml');
   if (text === null || !text.trim()) return { facts: null, error: null };
   try {
-    const data = parseYaml(text);
+    const data = parseYaml(text, { strict: true });
     if (!data || typeof data !== 'object' || Array.isArray(data)) return { facts: null, error: 'atlas.yaml is not a map of keys' };
     return { facts: data, error: null };
   } catch (error) { return { facts: null, error: `atlas.yaml cannot be read: ${error.message}` }; }
@@ -1460,6 +1500,7 @@ export function scan({ root, repoId = null, extractors = [], secretPatterns: pat
   if (missed.length) errors.push(`${missed.length} secret pattern(s) no longer catch their own canary: ${missed.join(', ')}; this check cannot be trusted`);
   if (!facts && !factsError) errors.push('atlas.yaml does not exist, so the check cannot learn the spec version or the repo kind');
   if (factsError) errors.push(factsError);
+  errors.push(...ownerOnlyErrors(facts));
   const kind = scoreAs ? scoreAs.kind ?? null : facts?.kind ?? null;
   const wantedSpec = scoreAs ? scoreAs.spec : facts?.spec;
   let spec = null;

package/shape/releases.json

@@ -20,6 +20,11 @@
       "check_version": 4,
       "sha256": "3357ea247694634c3535998368683eceffaf863221dee5fec9e43a03042afb95",
       "first_package": "0.3.36"
+    },
+    {
+      "check_version": 5,
+      "sha256": "8f36633fe693ebf7a7cc0f7237d49eb4720f67d371d4758d556bab51965ec334",
+      "first_package": "0.3.48"
     }
   ]
 }