@portll/cobolwork 0.0.1 → 0.2.75

package/rules/packs/broadcom.json

@@ -0,0 +1,124 @@
+{
+ "schemaVersion": 1,
+ "name": "broadcom",
+ "vendor": "Broadcom",
+ "product": "CA ACF2 and CA Top Secret",
+ "validation": {
+  "corpus": {
+   "date": "2026-09-21",
+   "repositories": 127,
+   "repositoriesWithJcl": 45,
+   "filesScanned": 558281,
+   "firedOn": 0,
+   "perRule": {},
+   "rulesThatFired": 0,
+   "rulesTotal": 8,
+   "note": "Measured 2026-09-21 over 127 public GitHub COBOL repositories, 558,281 files, with diag/measure-rules.mjs --packs. Read the denominator before the number: every rule in this pack is JCL-scoped, and only 45 of the 127 repositories contain any JCL at all. WHAT THIS DOES AND DOES NOT SHOW. It shows these rules are not broadly noisy - they do not fire on ordinary COBOL and JCL. It does not show they are quiet where they would actually run, because a public corpus of teaching material, vendor demos and tooling contains essentially no estate running this product. A rule that cannot fire for want of the product is not the same as a rule that sees the product and stays quiet, and this measurement cannot tell those apart. The practitioner review is still the half that would."
+  },
+  "practitioner": null,
+  "_note": "Two different questions. A corpus measurement over public COBOL repositories tells you how often these rules fire, which is their noise. It cannot tell you whether the risk statements are true: if the claim about GSO records is wrong, a thousand repositories will report it quietly and wrongly. Fill corpus with {repositories, firedOn, perRule} from diag/measure-rules.mjs; fill practitioner with {by, date, note} when someone who has administered the product has read it."
+ },
+ "retrieved": "2026-09-20",
+ "source": "CA ACF2 and CA Top Secret command references. Some are behind a Broadcom support login; a customer who runs the product can supply theirs.",
+ "coverage": "Logonid and ACID administration, resource rule maintenance, and global option changes. Not covered: reporting utilities, database maintenance, or anything whose risk depends on the installation's own rule set.",
+ "rules": [
+  {
+   "id": "acf2-logonid-insert",
+   "verb": "INSERT",
+   "pattern": "^\\s*INSERT\\s+[A-Z0-9$#@]{1,8}\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "high",
+   "risk": "creates a logonid",
+   "rationale": "An INSERT while the session is in logonid maintenance mode creates a logonid. The mode matters: without it this matches SQL INSERT INTO, which a corpus measurement over 125 repositories found 322 times. A logonid created from a job in a repository is a credential whose existence is decided by whoever can commit.",
+   "requiresContext": "acf2-lid-mode"
+  },
+  {
+   "id": "acf2-logonid-change",
+   "verb": "CHANGE",
+   "pattern": "^\\s*CHANGE\\s+[A-Z0-9$#@]{1,8}\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "high",
+   "risk": "alters a logonid, including its privileges",
+   "rationale": "CHANGE against a logonid alters its attributes. The privileged attributes here are the ones that matter, and the same statement carries both ordinary and privileged changes.",
+   "requiresContext": "acf2-lid-mode"
+  },
+  {
+   "id": "acf2-rule-maintenance",
+   "verb": "ACFNRULE",
+   "pattern": "\\bACFNRULE\\b|^\\s*SET\\s+RESOURCE\\b|^\\s*RECKEY\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "high",
+   "risk": "changes an access rule set",
+   "rationale": "Access rule maintenance decides who may reach which dataset or resource. Changing it from a job means the access model is edited by whoever can edit the repository.",
+   "setsContext": "acf2-lid-mode",
+   "setsContextPattern": "^\\s*SET\\s+(?:LID|RULE|PROFILE|RESOURCE)\\b"
+  },
+  {
+   "id": "acf2-global-options",
+   "verb": "SET CONTROL",
+   "pattern": "^\\s*SET\\s+CONTROL\\s*\\(?\\s*GSO",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "crit",
+   "risk": "changes a global system option",
+   "rationale": "GSO records are installation-wide security options. A change here affects every user and every resource at once, which makes it the highest-value single statement in the product."
+  },
+  {
+   "id": "topsecret-acid-create",
+   "verb": "TSS CREATE",
+   "pattern": "^\\s*TSS\\s+CREATE\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "high",
+   "risk": "creates an ACID",
+   "rationale": "TSS CREATE defines a new accessor identity. As with an ACF2 logonid, an identity created from a committed job is decided by whoever can commit."
+  },
+  {
+   "id": "topsecret-permit",
+   "verb": "TSS PERMIT",
+   "pattern": "^\\s*TSS\\s+PERMIT\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "high",
+   "risk": "grants access to a resource",
+   "rationale": "TSS PERMIT grants an ACID access to a resource. It is the statement that turns an identity into an authorisation, and it is the one an attacker most wants to be able to issue."
+  },
+  {
+   "id": "topsecret-addto-privilege",
+   "verb": "TSS ADDTO",
+   "pattern": "^\\s*TSS\\s+ADD(?:TO)?\\b[\\s\\S]{0,120}\\b(MASTFAC|NOSUSPEND|BYPASS|ACID\\s*\\(\\s*MASTER)",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "crit",
+   "risk": "grants a bypassing or master-level attribute",
+   "rationale": "The attributes matched here remove or bypass normal validation. An ACID carrying one of them is outside the controls every other identity is subject to, which is a different class of finding from an ordinary grant."
+  },
+  {
+   "id": "topsecret-revoke",
+   "verb": "TSS REVOKE",
+   "pattern": "^\\s*TSS\\s+(?:REVOKE|REMOVE|DELETE)\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "med",
+   "risk": "removes an identity or an authorisation",
+   "rationale": "Removing access from a job is less immediately dangerous than granting it, and it is still the security model being edited from a repository. It is listed so the route is visible, at a severity that says which way round it is."
+  }
+ ],
+ "programs": [
+  "ACFBATCH",
+  "ACFRPTXR",
+  "TSSUTIL",
+  "TSSCFILE"
+ ]
+}

package/rules/packs/connectdirect.json

@@ -0,0 +1,116 @@
+{
+ "schemaVersion": 1,
+ "name": "connectdirect",
+ "vendor": "IBM",
+ "product": "Connect:Direct for z/OS",
+ "validation": {
+  "corpus": {
+   "date": "2026-09-21",
+   "repositories": 127,
+   "repositoriesWithJcl": 45,
+   "filesScanned": 558281,
+   "firedOn": 1,
+   "perRule": {
+    "cd-batch-interface": {
+     "findings": 2,
+     "repositories": 1
+    }
+   },
+   "rulesThatFired": 1,
+   "rulesTotal": 7,
+   "note": "Measured 2026-09-21 over 127 public GitHub COBOL repositories, 558,281 files, with diag/measure-rules.mjs --packs. Read the denominator before the number: every rule in this pack is JCL-scoped, and only 45 of the 127 repositories contain any JCL at all. WHAT THIS DOES AND DOES NOT SHOW. It shows these rules are not broadly noisy - they do not fire on ordinary COBOL and JCL. It does not show they are quiet where they would actually run, because a public corpus of teaching material, vendor demos and tooling contains essentially no estate running this product. A rule that cannot fire for want of the product is not the same as a rule that sees the product and stays quiet, and this measurement cannot tell those apart. The practitioner review is still the half that would."
+  },
+  "practitioner": null,
+  "_note": "Two different questions. A corpus measurement over public COBOL repositories tells you how often these rules fire, which is their noise. It cannot tell you whether the risk statements are true. Fill corpus with {repositories, firedOn, perRule} from diag/measure-rules.mjs --packs connectdirect; fill practitioner with {by, date, note} when someone who has run Connect:Direct has read it."
+ },
+ "retrieved": "2026-09-20",
+ "source": "IBM Connect:Direct for z/OS User Guide and Process Language Reference. Process statements are submitted through DMBATCH, so they appear in JCL in-stream data rather than in any COBOL source.",
+ "coverage": "Process language statements submitted through the batch interface: SIGNON, RUN TASK, RUN JOB, SUBMIT and COPY. Not covered: the Secure+ configuration, the network map, initialisation parameters, or anything whose risk depends on the node's own authorisation settings. Those live outside the repository.",
+ "why": "Connect:Direct exists to move data off the platform, which makes every one of its processes an egress path by design. Two of its statements do more than move data: RUN TASK and RUN JOB execute code on the partner node. A repository that carries them carries remote execution.",
+ "rules": [
+  {
+   "id": "cd-run-task",
+   "verb": "RUN TASK",
+   "pattern": "^\\s*(?:[A-Z0-9$#@]+\\s+)?RUN\\s+TASK\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "crit",
+   "risk": "executes a program on the partner node",
+   "rationale": "RUN TASK runs a program on the node at the other end of the transfer. It is remote execution written into a repository, and the machine it runs on is by definition one this repository does not control."
+  },
+  {
+   "id": "cd-run-job",
+   "verb": "RUN JOB",
+   "pattern": "^\\s*(?:[A-Z0-9$#@]+\\s+)?RUN\\s+JOB\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "crit",
+   "risk": "submits a job on the partner node",
+   "rationale": "RUN JOB submits JCL for execution on the partner node. Everything true of RUN TASK is true here, with the submitted job's own authority added to it."
+  },
+  {
+   "id": "cd-signon-password",
+   "verb": "SIGNON",
+   "pattern": "^\\s*(?:[A-Z0-9$#@]+\\s+)?SIGNON\\b[\\s\\S]{0,200}?\\bUSERID\\s*=\\s*\\([^,)]{0,256},[^)]{1,256}\\)",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "crit",
+   "risk": "carries a userid and password in the process",
+   "rationale": "A SIGNON whose USERID operand carries a second positional value is supplying a password in the process text. The credential is then in the repository, readable by everyone who can read it."
+  },
+  {
+   "id": "cd-snode-credentials",
+   "verb": "SNODEID",
+   "pattern": "\\bSNODEID\\s*=\\s*\\([^,)]{0,256},[^)]{1,256}\\)",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "crit",
+   "risk": "carries the partner node's credentials",
+   "rationale": "SNODEID supplies the security credentials used on the partner node. Like SIGNON with a password, a second positional value is a secret, and it is a secret for a system this repository does not own."
+  },
+  {
+   "id": "cd-copy-outbound",
+   "verb": "COPY",
+   "pattern": "^\\s*(?:[A-Z0-9$#@]+\\s+)?COPY\\b[\\s\\S]{0,300}?\\bSNODE\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "med",
+   "risk": "transfers a dataset to another node",
+   "rationale": "A COPY naming a secondary node moves data off this system. It is the ordinary purpose of the product rather than a defect, and it is listed at a severity that says so, because an egress path is worth seeing even when it is intended."
+  },
+  {
+   "id": "cd-submit",
+   "verb": "SUBMIT",
+   "pattern": "^\\s*(?:[A-Z0-9$#@]+\\s+)?SUBMIT\\b[\\s\\S]{0,200}?\\b(PROC|DSN)\\s*=",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "high",
+   "risk": "submits a further process from a dataset",
+   "rationale": "SUBMIT runs another Connect:Direct process named by a dataset. What that process does is decided elsewhere, so the reachable behaviour of this job is not visible in this job."
+  },
+  {
+   "id": "cd-batch-interface",
+   "verb": "DMBATCH",
+   "pattern": "^DMBATCH$",
+   "appliesTo": [
+    "jcl-step"
+   ],
+   "severity": "info",
+   "risk": "invokes the batch interface",
+   "rationale": "DMBATCH is how a job talks to Connect:Direct at all, and it is named on the EXEC statement rather than in the process text below it. It is not itself a finding; it is listed so a reader can see which jobs reach the product, which is the inventory question that precedes every other rule in this pack."
+  }
+ ],
+ "programs": [
+  "DMBATCH",
+  "DMCHLAPI",
+  "DMNOTFY",
+  "DMRTSUB",
+  "NDMCMD"
+ ]
+}

package/rules/packs/controlm.json

@@ -0,0 +1,114 @@
+{
+ "schemaVersion": 1,
+ "name": "controlm",
+ "vendor": "BMC",
+ "product": "Control-M for z/OS",
+ "validation": {
+  "corpus": {
+   "date": "2026-09-21",
+   "repositories": 127,
+   "repositoriesWithJcl": 45,
+   "filesScanned": 558281,
+   "firedOn": 0,
+   "perRule": {},
+   "rulesThatFired": 0,
+   "rulesTotal": 7,
+   "note": "Measured 2026-09-21 over 127 public GitHub COBOL repositories, 558,281 files, with diag/measure-rules.mjs --packs. Read the denominator before the number: every rule in this pack is JCL-scoped, and only 45 of the 127 repositories contain any JCL at all. WHAT THIS DOES AND DOES NOT SHOW. It shows these rules are not broadly noisy - they do not fire on ordinary COBOL and JCL. It does not show they are quiet where they would actually run, because a public corpus of teaching material, vendor demos and tooling contains essentially no estate running this product. A rule that cannot fire for want of the product is not the same as a rule that sees the product and stays quiet, and this measurement cannot tell those apart. The practitioner review is still the half that would."
+  },
+  "practitioner": null,
+  "_note": "Two different questions. A corpus measurement over public COBOL repositories tells you how often these rules fire, which is their noise. It cannot tell you whether the risk statements are true. Fill corpus with {repositories, firedOn, perRule} from diag/measure-rules.mjs --packs controlm; fill practitioner with {by, date, note} when someone who has administered Control-M has read it."
+ },
+ "retrieved": "2026-09-20",
+ "source": "BMC Control-M for z/OS utility and AutoEdit references. Control-M utilities are invoked as job steps, and their control statements arrive in in-stream data.",
+ "coverage": "Utilities invoked from JCL and the AutoEdit substitution that reaches them. NOT covered: the scheduling definitions themselves, which live in the Control-M database rather than in a repository, and which is where most of a scheduler's real authority sits. A repository sees the jobs, not the schedule.",
+ "why": "A scheduler decides what runs, when, and under whose authority. Most of that is held outside any repository, which is itself the finding worth stating: this pack reads the part that is committed and is explicit that the larger part is not.",
+ "rules": [
+  {
+   "id": "ctm-order-force",
+   "verb": "CTMAPI ORDER/FORCE",
+   "pattern": "^\\s*(?:ORDER|FORCE)\\s+(?:JOB|TABLE)\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "high",
+   "risk": "orders or forces a job into the active schedule",
+   "rationale": "ORDER places a job into the active environment and FORCE does so regardless of its scheduling criteria. A job that can force another job has escaped the schedule that was reviewed, and what it forces is named here rather than in the scheduler."
+  },
+  {
+   "id": "ctm-autoedit-variable-in-command",
+   "verb": "%%AUTOEDIT",
+   "pattern": "%%[A-Z0-9_$#@.]{2,}",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "med",
+   "risk": "substitutes a scheduler variable into the statement at run time",
+   "rationale": "An AutoEdit variable is replaced by the scheduler before the statement runs, so what the committed text says is not what executes. The value comes from the scheduler's own tables, which are outside this repository and outside this review."
+  },
+  {
+   "id": "ctm-runas-owner",
+   "verb": "OWNER / RUNAS",
+   "pattern": "^\\s*(?:OWNER|RUN_AS|RUNAS)\\s*=\\s*[A-Z0-9$#@]{1,8}",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "high",
+   "risk": "runs work under a named identity other than the submitter's",
+   "rationale": "Naming an owner runs the work with that identity's authority rather than the submitter's. Whether that is a privilege escalation depends on the identity, which is why this is reported rather than judged."
+  },
+  {
+   "id": "ctm-security-utility",
+   "verb": "CTMSEC",
+   "pattern": "\\bCTMSEC\\b|^\\s*(?:DEFINE|UPDATE)\\s+USER\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "crit",
+   "risk": "changes Control-M security definitions",
+   "rationale": "The scheduler's own security definitions decide who may order, force or delete work across the estate. Editing them from a job puts the scheduler's access model in the hands of whoever can commit."
+  },
+  {
+   "id": "ctm-delete-condition",
+   "verb": "DELCOND",
+   "pattern": "^\\s*(?:DELCOND|DELETE\\s+COND(?:ITION)?)\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "med",
+   "risk": "deletes a scheduling condition other work waits on",
+   "rationale": "Conditions are how one job tells another it may start. Deleting one releases whatever was waiting, so the effect of this statement is on jobs it does not name and whose definitions are not in this repository."
+  },
+  {
+   "id": "ctm-file-watcher-command",
+   "verb": "CTMFW",
+   "pattern": "\\bCTMFW\\b",
+   "appliesTo": [
+    "jcl-instream"
+   ],
+   "severity": "low",
+   "risk": "waits on a file and triggers work when it appears",
+   "rationale": "A file watcher turns the arrival of a dataset into the start of work. It is an entry point driven by something outside the job, and it is listed at low severity so the route is visible rather than because arrival is itself suspicious."
+  },
+  {
+   "id": "ctm-utility-step",
+   "verb": "CTMAPI / CTMJSA",
+   "pattern": "^CTM(API|JSA|CSU|LDNRS|BLT)$",
+   "appliesTo": [
+    "jcl-step"
+   ],
+   "severity": "info",
+   "risk": "reaches the scheduler from a job",
+   "rationale": "A Control-M utility invoked as a step is where a job stops being scheduled work and starts being work that changes the schedule. It is listed so a reader can see which jobs reach the scheduler, which is the question that precedes every other rule in this pack."
+  }
+ ],
+ "programs": [
+  "CTMAPI",
+  "CTMJSA",
+  "CTMCSU",
+  "CTMLDNRS",
+  "CTMBLT",
+  "CTMFW",
+  "CTMSEC",
+  "CONTROLM"
+ ]
+}

package/rules/system-layouts.json

@@ -0,0 +1,28 @@
+{
+ "_comment": "The byte layout of system copybooks a repository copy can shadow, as elementary fields [name, offset, size, occurs]. A repository copy whose elementary fields match is the system's own layout; one that differs compiles its programs against something else. Offsets follow from the documented order and lengths, and each total matches the length the documentation states. Group names are not compared: IBM's own copies group SQLWARN8-A under SQLEXT, which vendored copies often fold into SQLWARN.",
+ "SQLCA": {
+  "source": { "title": "Db2 13 for z/OS, Description of SQLCA fields", "url": "https://www.ibm.com/docs/en/db2-for-zos/13?topic=sqlca-description-fields", "retrieved": "2026-09-27" },
+  "length": 136,
+  "fields": [
+   ["SQLCAID", 0, 8, 1],
+   ["SQLCABC", 8, 4, 1],
+   ["SQLCODE", 12, 4, 1],
+   ["SQLERRML", 16, 2, 1],
+   ["SQLERRMC", 18, 70, 1],
+   ["SQLERRP", 88, 8, 1],
+   ["SQLERRD", 96, 4, 6],
+   ["SQLWARN0", 120, 1, 1],
+   ["SQLWARN1", 121, 1, 1],
+   ["SQLWARN2", 122, 1, 1],
+   ["SQLWARN3", 123, 1, 1],
+   ["SQLWARN4", 124, 1, 1],
+   ["SQLWARN5", 125, 1, 1],
+   ["SQLWARN6", 126, 1, 1],
+   ["SQLWARN7", 127, 1, 1],
+   ["SQLWARN8", 128, 1, 1],
+   ["SQLWARN9", 129, 1, 1],
+   ["SQLWARNA", 130, 1, 1],
+   ["SQLSTATE", 131, 5, 1]
+  ]
+ }
+}

package/schema/cobolwork-coverage.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Portll/cobolwork/schema/cobolwork-coverage.schema.json",
+  "title": "cobolwork/coverage",
+  "description": "A SARIF property-bag convention for analyser coverage: what a run read, what it did not, and why it stopped. SARIF 2.1.0 can say that files could not be read, through invocations[].toolExecutionNotifications, but it has no standard way to state coverage as a ratio with a denominator. This is that denominator. It lives under invocations[].properties['cobolwork/coverage'], namespaced so it cannot be mistaken for a standard field, and it is an addition to the standard notifications rather than a replacement for them: a conforming consumer that ignores this key still learns which files were not read. It is published with one implementation, which is not enough to make it a standard. If a second analyser adopts it, the right venue is a proposed invocation.coverage object at the OASIS SARIF Technical Committee, where the bar is prior use rather than a good argument.",
+  "type": "object",
+  "required": ["coverageIncomplete"],
+  "properties": {
+    "coverageIncomplete": {
+      "type": "boolean",
+      "description": "True when the run did not read everything it selected. The verdict, and the reason this convention exists: a finding count over source nobody read is not a clean result. It is duplicated in invocations[].properties.coverageIncomplete and reflected in executionSuccessful, so a consumer cannot miss it by not knowing about this key."
+    },
+    "filesScanned": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "description": "Artifacts whose bytes were read by at least one analysis."
+    },
+    "bySet": {
+      "type": "object",
+      "description": "Per analysis component, keyed by the component's own name. A run whose components read different slices of the tree cannot state one number, and a single total hides which analysis fell short.",
+      "additionalProperties": { "$ref": "#/$defs/componentCoverage" }
+    },
+    "setsIncomplete": {
+      "type": "array",
+      "description": "Components that did not fully run, each with the reason. Two distinct causes share this list and `kind` distinguishes them: a component that could not run for want of configuration, and one that ran and did not reach everything. Only `coverage` bears on whether the scan read what it was given.",
+      "items": {
+        "type": "object",
+        "required": ["set", "kind", "why"],
+        "properties": {
+          "set": { "type": "string" },
+          "kind": { "enum": ["coverage", "configuration"], "description": "coverage: the component ran and did not read everything. configuration: it could not run in full because it was not told enough, such as a missing cobolwork.site.json." },
+          "why": { "type": "string", "description": "Written for a person deciding what to do about it, from the reasons for that kind." }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "componentCoverage": {
+      "type": "object",
+      "description": "filesScanned + filesNotRead + filesUnreadable + filesUnparsed accounts for every artifact the component selected.",
+      "properties": {
+        "filesScanned": { "type": "integer", "minimum": 0, "description": "Read, and contributed." },
+        "filesUnreadable": { "type": "integer", "minimum": 0, "description": "Selected, and the bytes never arrived." },
+        "filesUnparsed": { "type": "integer", "minimum": 0, "description": "Read, and could not be parsed. Distinct from unreadable: counting these as unreadable understates what the run managed to look at." },
+        "filesNotRead": { "type": "integer", "minimum": 0, "description": "Selected and never opened, because the run stopped before reaching them." },
+        "filesBinary": { "type": "integer", "minimum": 0 },
+        "stoppedBy": {
+          "type": "string",
+          "description": "What ended the reading early, in the words of the limit that was hit.",
+          "examples": ["memory reserve", "memory exhausted", "byte budget"]
+        },
+        "unreadable": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "'path: reason', one per artifact. A count names nothing anyone can go and look at, and it cannot tell a permission denied from the analyser being wrong."
+        },
+        "unparsed": { "type": "array", "items": { "type": "string" }, "description": "'path: reason', one per artifact." },
+        "notRead": { "type": "string", "description": "One sentence a report can print verbatim, saying how much was missed and that the result is not a claim about the whole input." }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/cobolwork.policy.schema.json

@@ -0,0 +1,54 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://github.com/Portll/cobolwork/schema/cobolwork.policy.schema.json",
+ "title": "cobolwork build policy",
+ "description": "Which findings stop a build, which run-time checks the compiler must generate, and what an incomplete scan means. docs/spec/build-gate.md section 4. lib/policy.mjs validates the same shape and also refuses a rule id cobolwork does not declare.",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["policyVersion"],
+ "properties": {
+  "_comment": { "type": "string" },
+  "policyVersion": { "const": 1 },
+  "block": { "$ref": "#/$defs/tier", "description": "A finding at or above this tier blocks. Default high." },
+  "always": { "$ref": "#/$defs/tier", "description": "In ratchet mode, a finding at or above this tier blocks whether or not the change introduced it. Default crit." },
+  "classes": {
+   "type": "array",
+   "items": { "enum": ["privilege-escalation", "data-mutation"] },
+   "uniqueItems": true,
+   "description": "A finding in one of these consequence classes blocks at any tier. Default both."
+  },
+  "rules": {
+   "type": "object",
+   "additionalProperties": { "enum": ["block", "warn"] },
+   "description": "Per rule id: block whatever its tier, or warn whatever its tier or class."
+  },
+  "coverage": { "enum": ["block", "warn"], "description": "Incomplete coverage makes the build undecided (block) or is reported (warn). Default block." },
+  "options": { "enum": ["block", "warn"], "description": "A build without a required run-time check fails, and options nothing declares make it undecided (block); or both are reported and the build passes relaxed (warn). An option forbid names, and a check the change removes, fail either way. Default warn." },
+  "waivers": {
+   "type": "object",
+   "additionalProperties": false,
+   "required": ["maxDays"],
+   "properties": { "maxDays": { "type": "integer", "minimum": 1 } },
+   "description": "A waiver written with an expiry further off than maxDays covers nothing. Default 180."
+  },
+  "checks": {
+   "type": "array",
+   "items": { "enum": ["subscript", "reference-modification", "numeric-data", "argument-length"] },
+   "uniqueItems": true,
+   "description": "The run-time checks every program must be compiled with. Default subscript and reference-modification."
+  },
+  "forbid": {
+   "type": "object",
+   "additionalProperties": false,
+   "properties": {
+    "enterprise": { "$ref": "#/$defs/options" },
+    "gnucobol": { "$ref": "#/$defs/options" }
+   },
+   "description": "Options a build must not pass, beyond those that turn a required check off."
+  }
+ },
+ "$defs": {
+  "tier": { "enum": ["info", "low", "med", "high", "crit", "known-exploitable"] },
+  "options": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+ }
+}