@opengsd/gsd-path 1.4.0 → 1.5.0

package/skills/gsd-path-docs-audit/scripts/build_recovery.py

@@ -1,5 +1,5 @@
 # gsd-path project runtime
-"""Guard a blocked build's return to Define or Plan using its committed base."""
+"""Guard return to Define or Plan using a committed recovery base."""
 
 from __future__ import annotations
 
@@ -17,7 +17,9 @@ EVENTS = {
     "define": "build intent corrections requested",
     "plan": "build plan repair requested",
 }
+PLAN_INTENT_EVENT = "plan intent corrections requested"
 MARKER = "build recovery: "
+RECOVERY_KEYS = frozenset({"base", "branch", "kind", "source"})
 
 
 def runtime():
@@ -36,9 +38,42 @@ def checkpoint_runtime():
     return state_checkpoint
 
 
+def _parse_recovery_record(value: object) -> dict:
+    if (
+        not isinstance(value, dict)
+        or not {"base", "branch", "kind"}.issubset(value)
+        or not set(value).issubset(RECOVERY_KEYS)
+        or not isinstance(value["base"], str)
+        or not re.fullmatch(r"[0-9a-f]{40}", value["base"])
+    ):
+        raise runtime().PipelineStateError("invalid build recovery record")
+    source = value.get("source", "build")
+    if source not in {"build", "plan"}:
+        raise runtime().PipelineStateError("invalid build recovery record")
+    if source == "plan":
+        if value["kind"] != "define":
+            raise runtime().PipelineStateError("invalid build recovery record")
+    elif value["kind"] not in EVENTS:
+        raise runtime().PipelineStateError("invalid build recovery record")
+    return {**value, "source": source}
+
+
+def _recovery_base_proves_milestone(before, current, source: str) -> bool:
+    if before.branch != current.branch or before.milestone != current.milestone:
+        return False
+    if source == "plan":
+        return (before.phase, before.status) in {("plan", "active"), ("plan", "blocked")}
+    return (before.phase, before.status) == ("build", "blocked")
+
+
 def context(repo: Path, text: str | None = None) -> dict | None:
     state = runtime()
-    current, loaded, _ = state.load_state(repo)
+    try:
+        current, loaded, _ = state.load_state(repo)
+    except state.PipelineStateError as error:
+        if "STATE.md must be a real file" not in str(error):
+            raise
+        return None
     text = loaded if text is None else text
     recovery = None
     for line in text.splitlines():
@@ -47,26 +82,24 @@ def context(repo: Path, text: str | None = None) -> dict | None:
         event = line.split(" — ", 2)[-1]
         if event.startswith(MARKER):
             try:
-                value = json.loads(event[len(MARKER):])
+                value = _parse_recovery_record(json.loads(event[len(MARKER):]))
             except ValueError as error:
                 raise state.PipelineStateError("invalid build recovery record") from error
-            if (not isinstance(value, dict) or set(value) != {"base", "branch", "kind"}
-                    or value["kind"] not in EVENTS
-                    or not isinstance(value["base"], str)
-                    or not re.fullmatch(r"[0-9a-f]{40}", value["base"])):
-                raise state.PipelineStateError("invalid build recovery record")
             recovery = {**value, "active": True} if value["branch"] == current.branch else None
-        elif event == "build started" and recovery:
-            recovery["active"] = False
+        elif recovery and recovery.get("active"):
+            source = recovery.get("source", "build")
+            if source == "build" and event == "build started":
+                recovery["active"] = False
+            elif source == "plan" and event == "plan approved":
+                recovery["active"] = False
     if recovery:
         if not state._is_ancestor(repo, recovery["base"], "HEAD"):
             raise state.PipelineStateError("build recovery base is not an ancestor of HEAD")
-        source = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/STATE.md")
-        if source is None:
+        base_text = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/STATE.md")
+        if base_text is None:
             raise state.PipelineStateError("build recovery base has no STATE.md")
-        before = state._state_from_text(source)
-        if ((before.phase, before.status) != ("build", "blocked")
-                or before.branch != current.branch or before.milestone != current.milestone):
+        before = state._state_from_text(base_text)
+        if not _recovery_base_proves_milestone(before, current, recovery.get("source", "build")):
             raise state.PipelineStateError("build recovery base does not prove this blocked milestone")
     return recovery
 
@@ -108,18 +141,20 @@ def settled_tasks(repo: Path) -> dict[str, tuple[str, dict]]:
     return tasks
 
 
-def begin(repo: Path, before, after, event: str) -> dict:
+def _begin_common(repo: Path, before, event: str) -> str:
     state = runtime()
-    if (before.phase, before.status) != ("build", "blocked") or after.phase not in EVENTS:
-        raise state.PipelineStateError("build recovery requires build/blocked")
-    if event != EVENTS[after.phase]:
-        raise state.PipelineStateError(f"state transition requires event: {EVENTS[after.phase]}")
     if before.archive is not None or before.branch != state._current_branch(repo):
         raise state.PipelineStateError("build recovery requires the active bound branch")
     if state._worktree_changes(repo):
         raise state.PipelineStateError("checkpoint the blocked build before recovery")
     if any(state.transaction_journals(repo).values()):
         raise state.PipelineStateError("finish pending transactions before build recovery")
+    state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md")
+    return state._run_git(repo, "rev-parse", "HEAD").stdout.strip()
+
+
+def _settle_build_dispatch(repo: Path) -> None:
+    state = runtime()
     records = records_root(repo)
     for directory in {path.parent.parent for path in records.rglob("attempt-*/state.json")}:
         latest = max(directory.glob("attempt-*/state.json"), key=lambda path: int(path.parent.name.split("-")[1]))
@@ -128,19 +163,49 @@ def begin(repo: Path, before, after, event: str) -> dict:
                 or (record.get("worktree") and record.get("branch") and not record.get("cleanup_complete"))
                 or record.get("outcome") not in {"landed", "collected", "blocked", "resolved", "redispatched"}):
             raise state.PipelineStateError(f"settle dispatch records before recovery: {latest}")
-    tasks = settled_tasks(repo)
-    state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
-    state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md")
-    base = state._run_git(repo, "rev-parse", "HEAD").stdout.strip()
+
+
+def _verify_done_tasks(repo: Path, tasks: dict[str, tuple[str, dict]], base: str) -> None:
+    state = runtime()
     done = [repo / ".project/tasks" / name for name, (_, fields) in tasks.items()
             if fields["status"] == "done"]
-    if done:
-        if __package__:
-            from scripts.isolation import verify_landed_task_files
-        else:
-            from isolation import verify_landed_task_files
-        verify_landed_task_files(repo, done, ".project/tasks", base)
-    return {"kind": after.phase, "base": base, "branch": before.branch}
+    if not done:
+        return
+    if __package__:
+        from scripts.isolation import verify_landed_task_files
+    else:
+        from isolation import verify_landed_task_files
+    verify_landed_task_files(repo, done, ".project/tasks", base)
+
+
+def begin(repo: Path, before, after, event: str) -> dict:
+    state = runtime()
+    if (before.phase, before.status) == ("build", "blocked") and after.phase in EVENTS:
+        if event != EVENTS[after.phase]:
+            raise state.PipelineStateError(f"state transition requires event: {EVENTS[after.phase]}")
+        _settle_build_dispatch(repo)
+        tasks = settled_tasks(repo)
+        state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
+        base = _begin_common(repo, before, event)
+        _verify_done_tasks(repo, tasks, base)
+        return {"kind": after.phase, "base": base, "branch": before.branch, "source": "build"}
+    if (
+        before.phase == "plan"
+        and before.status in {"active", "blocked"}
+        and (after.phase, after.status) == ("define", "active")
+    ):
+        if event != PLAN_INTENT_EVENT:
+            raise state.PipelineStateError(f"state transition requires event: {PLAN_INTENT_EVENT}")
+        state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
+        tasks_dir = repo / ".project/tasks"
+        tasks = settled_tasks(repo) if tasks_dir.is_dir() and any(
+            path.is_file() and not state._common.is_ignored_junk(path)
+            for path in tasks_dir.iterdir()
+        ) else {}
+        base = _begin_common(repo, before, event)
+        _verify_done_tasks(repo, tasks, base)
+        return {"kind": "define", "base": base, "branch": before.branch, "source": "plan"}
+    raise state.PipelineStateError("build recovery requires build/blocked")
 
 
 def records_root(repo: Path) -> Path:

package/skills/gsd-path-docs-audit/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.
@@ -96,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 (
@@ -247,6 +257,63 @@ 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,
@@ -354,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()
@@ -371,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(