@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-inspect/scripts/check_docs_audit.py

@@ -8,6 +8,10 @@ with testable claims where every claim row carries a valid type, a valid
 verdict, and real evidence, a `## Descriptive docs` list for claimless docs,
 the two sets disjoint and together equal to the frozen inventory, and a
 remediation queue with one classified row per non-verified claim.
+Queue numbers are unique, positive and strictly increasing, not necessarily
+contiguous. With `--prior-audit`, persisting rows keep their number and new
+rows use a number above every prior queue number and User rulings Queue #.
+Numbers stay bound to their original (doc, claim); never reuse a retired one.
 `## User rulings` is fixed-format durable memory. Pass the pre-rewrite audit
 with `--prior-audit FILE`; every prior row, including its Planned value, must
 remain an exact ordered prefix.
@@ -26,6 +30,10 @@ gate derives the inventory from tracked Markdown files, excluding `.git`,
 `*/skills/path` bundles,
 the audit itself, and — unless the
 audit declares `Alignment mode: yes` — everything else under `.project/`.
+
+`Repo root` names the primary repository. When the audit is gated inside a
+disposable sidecar, pass that sidecar as `--repo` and the primary as
+`--primary`; the header then stays valid after the sidecar is retired.
 """
 
 import argparse
@@ -92,6 +100,12 @@ def _table_rows(body: str, width: int, label: str) -> List[List[str]]:
     return rows
 
 
+def _remediation_queue_rows(body: str, label: str, required: bool = False) -> List[List[str]]:
+    if not required and "|" not in body:
+        return []
+    return _table_rows(body, 6, label)
+
+
 def _not_placeholder(value: str, label: str) -> None:
     normalized = value.strip().strip("`\"").strip()
     if (
@@ -243,12 +257,70 @@ def _check_carried(
             raise AuditError(f"{label}: doc or evidence changed since the prior audit: {', '.join(moved)}")
 
 
+def _queue_number(number: str, label: str) -> int:
+    if not re.fullmatch(r"[1-9][0-9]*", number):
+        raise AuditError(f"{label}: queue numbers must be positive integers")
+    return int(number)
+
+
+def _check_queue_number_history(
+    queue: Sequence[Sequence[str]],
+    prior_sections: Dict[str, str],
+) -> None:
+    if "Remediation queue" not in prior_sections:
+        raise AuditError("prior audit is missing section: ## Remediation queue")
+    if "User rulings" not in prior_sections:
+        raise AuditError("prior audit is missing section: ## User rulings")
+
+    prior_queue = _remediation_queue_rows(
+        prior_sections["Remediation queue"], "Prior remediation queue"
+    )
+    prior_items_by_number: Dict[int, tuple] = {}
+    prior_numbers_by_item: Dict[tuple, int] = {}
+    for number, doc, claim, *_ in prior_queue:
+        numeric_number = _queue_number(number, "Prior remediation queue")
+        identity = (doc, claim)
+        prior_items_by_number[numeric_number] = identity
+        prior_numbers_by_item[identity] = numeric_number
+
+    prior_rulings = _user_rulings(
+        prior_sections["User rulings"], "Prior user rulings"
+    )
+    prior_ruling_numbers = {int(row[0]) for row in prior_rulings}
+    prior_max = max(
+        [*prior_items_by_number, *prior_ruling_numbers],
+        default=0,
+    )
+
+    for number, doc, claim, *_ in queue:
+        numeric_number = _queue_number(number, "Remediation queue")
+        identity = (doc, claim)
+        prior_number = prior_numbers_by_item.get(identity)
+        if numeric_number in prior_ruling_numbers and prior_items_by_number.get(numeric_number) != identity:
+            raise AuditError(
+                f"Remediation queue #{number}: Queue # {number} is already retired by a prior "
+                "User rulings row for a different item; give new items a number above every "
+                "prior queue number and User rulings Queue #"
+            )
+        if prior_number is not None and numeric_number != prior_number:
+            raise AuditError(
+                f"Remediation queue #{number}: persisting item must keep its prior queue "
+                f"number #{prior_number}"
+            )
+        if prior_number is None and numeric_number <= prior_max:
+            raise AuditError(
+                f"Remediation queue #{number}: new items must use a number above every prior "
+                f"queue number and User rulings Queue # (maximum {prior_max})"
+            )
+
+
 def validate(
     repo: Path,
     audit_relative: str,
     inventory: Optional[Sequence[str]],
     prior_text: Optional[str] = None,
     changed: Optional[Sequence[str]] = None,
+    primary: Optional[Path] = None,
 ) -> Dict[str, object]:
     audit = repo / audit_relative
     if not audit.is_file() or audit.is_symlink():
@@ -263,8 +335,8 @@ def validate(
             raise AuditError(f"header must contain exactly one {key} line")
         header[key] = values[0]
     declared_root = Path(header["Repo root"])
-    if not declared_root.is_absolute() or declared_root.resolve() != repo.resolve():
-        raise AuditError("Repo root does not match --repo")
+    if not declared_root.is_absolute() or declared_root.resolve() != (primary or repo).resolve():
+        raise AuditError("Repo root does not match --primary (default --repo)")
     try:
         date.fromisoformat(header["Audited"])
     except ValueError as error:
@@ -349,7 +421,9 @@ def validate(
 
     queue_body = sections["Remediation queue"]
     non_verified = sum(tallies[verdict] for verdict in VERDICTS if verdict != "verified")
-    queue = _table_rows(queue_body, 6, "Remediation queue") if non_verified or "|" in queue_body else []
+    queue = _remediation_queue_rows(
+        queue_body, "Remediation queue", required=bool(non_verified)
+    )
     expected_queue = sorted(
         (doc, claim["claim"], claim["verdict"])
         for doc, claims in docs.items()
@@ -366,9 +440,13 @@ def validate(
         _not_placeholder(action, f"Remediation queue #{number}: action")
     if len(queue) != non_verified:
         raise AuditError(f"Remediation queue has {len(queue)} rows for {non_verified} non-verified claims")
-    numbers = [row[0] for row in queue]
-    if numbers != [str(number) for number in range(1, len(queue) + 1)]:
-        raise AuditError("Remediation queue numbers must be contiguous and ordered from 1")
+    numbers = [_queue_number(row[0], "Remediation queue") for row in queue]
+    if any(later <= earlier for earlier, later in zip(numbers, numbers[1:])):
+        raise AuditError(
+            "Remediation queue numbers must be unique and strictly increasing"
+        )
+    if prior_sections is not None:
+        _check_queue_number_history(queue, prior_sections)
     actual_queue = sorted((doc, claim, verdict) for _, doc, claim, verdict, _, _ in queue)
     if actual_queue != expected_queue:
         raise AuditError(
@@ -392,6 +470,11 @@ def parser() -> argparse.ArgumentParser:
     argument_parser.add_argument("--repo", type=Path, required=True)
     argument_parser.add_argument("--audit", default=DEFAULT_AUDIT, help="relative audit path (default: %(default)s)")
     argument_parser.add_argument("--inventory", help="file with one inventoried POSIX path per line, or - for stdin")
+    argument_parser.add_argument(
+        "--primary",
+        type=Path,
+        help="primary repository the Repo root header must name (default: --repo)",
+    )
     argument_parser.add_argument(
         "--prior-audit",
         type=Path,
@@ -454,7 +537,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
     changed = _path_lines(arguments.changed) if arguments.changed is not None else None
     try:
         result = validate(
-            arguments.repo.resolve(), arguments.audit, inventory, prior_text, changed
+            arguments.repo.resolve(), arguments.audit, inventory, prior_text, changed,
+            arguments.primary,
         )
     except AuditError as error:
         print(f"docs audit validation failed: {error}", file=sys.stderr)