npm - @opengsd/gsd-path - Versions diffs - 1.0.0 → 1.1.0 - Mend

@opengsd/gsd-path 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (395) hide show

package/scripts/task_context.py ADDED Viewed

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Render a read-only coder intent view from the approved task and intent."""
+import argparse
+import hashlib
+import re
+import sys
+from pathlib import Path
+try:
+    from scripts import check_handoffs as contracts
+except ImportError:
+    import check_handoffs as contracts
+def render(repo: Path, task: Path) -> str:
+    intent_path = repo.resolve() / '.project/intent/INTENT.md'
+    task = task.resolve()
+    intent = intent_path.read_bytes().decode('utf-8')
+    task_text = task.read_bytes().decode('utf-8')
+    owned = contracts._owned_criteria(task_text, task.stem)
+    criteria = contracts._success_criteria(intent)
+    unknown = set(owned) - set(criteria)
+    if unknown:
+        raise contracts.HandoffError('unknown owned criteria: ' + ', '.join(sorted(unknown)))
+    projected, mode = intent, 'full-intent'
+    sections = list(re.finditer(r'(?ms)^## Success criteria[ \t]*\n(?P<body>.*?)(?=^## |\Z)', intent))
+    if len(sections) == 1:
+        section = sections[0]
+        body = section['body']
+        items = list(re.finditer(r'(?m)^(\d+)\. .+\n?', body))
+        # Project only simple numbered prose. Preserve unfamiliar Markdown in full.
+        simple = (items and not body[:items[0].start()].strip()
+                  and '```' not in body and '~~~' not in body and '<!--' not in body
+                  and [f'SC{item[1]}' for item in items] == list(criteria))
+        chunks = [body[item.start():items[n + 1].start() if n + 1 < len(items) else len(body)]
+                  for n, item in enumerate(items)]
+        simple = simple and all(not line.strip() or line[:1].isspace()
+                                for chunk in chunks for line in chunk.splitlines()[1:])
+        if simple:
+            before, after = intent[:section.start('body')], intent[section.end('body'):]
+            # Corrections and task interfaces can explicitly refer to another SC.
+            required = set(owned) | set(re.findall(r'\bSC\d+\b', before + after + task_text))
+            selected = ''.join(chunk for item, chunk in zip(items, chunks) if f'SC{item[1]}' in required)
+            projected = before + '\n' + (selected or '- No criteria assigned.\n\n') + after
+            mode = 'owned-criteria'
+    return ('## Generated intent context\n\n'
+            f'Source: {intent_path}\n'
+            f'Intent SHA256: {hashlib.sha256(intent.encode()).hexdigest()}\n'
+            f'Task: {task}\n'
+            f'Task SHA256: {hashlib.sha256(task_text.encode()).hexdigest()}\n'
+            f'Mode: {mode}\n\n'
+            'Use this view for intent. All non-criterion text is verbatim; selected criteria retain '
+            'their original numbers. The source remains authoritative. Read it if a dependency '
+            'or ambiguity requires omitted criteria.\n\n' + projected)
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--repo', type=Path, required=True)
+    parser.add_argument('--task', type=Path, required=True)
+    args = parser.parse_args()
+    try:
+        output = render(args.repo, args.task)
+    except (OSError, contracts.HandoffError) as error:
+        print(str(error), file=sys.stderr)
+        return 1
+    print(output, end='')
+    return 0
+if __name__ == '__main__':
+    raise SystemExit(main())

package/scripts/token_budget.py CHANGED Viewed

@@ -69,6 +69,24 @@ def output_usage(path: Path) -> int:
     return sum(usages)
+def cumulative_counter(path: Path):
+    """One completed CLI invocation, with the thread identity needed for resume."""
+    identities, counters = set(), []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        event = json.loads(line)
+        if "raw" in event:
+            event = json.loads(event["raw"])
+        if event.get("type") == "thread.started":
+            identities.add(event["thread_id"])
+        if event.get("type") == "turn.completed":
+            counters.append(event["usage"]["output_tokens"])
+    if len(identities) != 1 or len(counters) != 1:
+        raise ValueError("cumulative usage requires one identified, completed CLI invocation")
+    if type(counters[0]) is not int or counters[0] < 0:
+        raise ValueError("invalid cumulative output counter")
+    return identities.pop(), counters[0]
 def operate(args):
     ledger = args.ledger.absolute()
     if ledger.is_symlink():
@@ -92,9 +110,28 @@ def operate(args):
         if args.action == "record":
             source = str(args.events.resolve())
             observation = {"task": args.task, "output_tokens": output_usage(args.events)}
+            prior_events = getattr(args, "previous_events", None)
+            if prior_events is not None:
+                prior_source = str(prior_events.resolve())
+                prior = data["observations"].get(prior_source)
+                identity, total = cumulative_counter(args.events)
+                prior_identity, prior_total = cumulative_counter(prior_events)
+                if source == prior_source or identity != prior_identity or total < prior_total:
+                    raise ValueError("cumulative resume has a different thread or a reset counter")
+                if prior is None or prior.get("reported_output_tokens", prior["output_tokens"]) != prior_total:
+                    raise ValueError("previous cumulative invocation must be recorded unchanged first")
+                if any(key != source and row.get("previous_events") == prior_source
+                       for key, row in data["observations"].items()):
+                    raise ValueError("previous cumulative invocation already has a recorded successor")
+                observation.update(output_tokens=total - prior_total, reported_output_tokens=total,
+                                   previous_events=prior_source, session_id=identity)
             previous = data["observations"].get(source)
+            if previous and previous != observation and any(
+                    row.get("previous_events") == source for row in data["observations"].values()):
+                raise ValueError("a cumulative predecessor cannot change after its successor is recorded")
             if previous and (previous["task"] != args.task or
-                             previous["output_tokens"] > observation["output_tokens"]):
+                             previous["output_tokens"] > observation["output_tokens"] or
+                             previous.get("previous_events") != observation.get("previous_events")):
                 raise ValueError("observation cannot change task or reduce recorded usage")
             data["observations"][source] = observation
             atomic_write(ledger, json.dumps(data, indent=2) + "\n")
@@ -131,6 +168,8 @@ def main(argv=None):
             command.add_argument("--task", required=True)
         if name == "record":
             command.add_argument("--events", type=Path, required=True)
+            command.add_argument("--previous-events", type=Path,
+                                 help="previous recorded invocation when this CLI reports cumulative resume counters")
         if name == "admit":
             command.add_argument("--require-hard-cap", action="store_true")
     try:

package/scripts/workflow_run.py CHANGED Viewed

@@ -2,9 +2,11 @@
 """Run canonical workflow helpers with fixed arguments and fail-stop receipts."""
 import argparse
+import hashlib
 import json
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 try:
@@ -16,13 +18,18 @@ except ImportError:  # bundled copy inside a skill's scripts directory
 class StepFailed(RuntimeError):
     pass
+INSPECTION_SPECS = (("inspect_codebase", "codebase-mapper", "codebase", "evidence-codebase.md"),
+                    ("inspect_docs", "docs-auditor", "docs-audit", "DOCS-AUDIT.md"))
 def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str = None,
-                 task_id: str = None, round_size: int = None) -> dict:
+                 task_id: str = None, round_size: int = None, inspection: Path = None,
+                 mapper_reviewed: bool = False) -> dict:
     steps = []
+    outputs = {}
     scripts = Path(__file__).resolve().parent
-    def step(script, *arguments):
+    def step(script, *arguments, raw=False):
         command = [sys.executable, "-B", str(scripts / script), *arguments]
         completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
         receipt = {"script": script, "command": command, "exit_code": completed.returncode,
@@ -32,6 +39,8 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             sys.stderr.write(completed.stderr)
         if completed.returncode:
             raise StepFailed(script)
+        if raw:
+            return completed.stdout
         try:
             receipt["result"] = json.loads(completed.stdout)
         except json.JSONDecodeError as error:
@@ -42,6 +51,103 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
     try:
         if action == "route":
             step("pipeline_state.py", "route", *common)
+        elif action == "prepare-inspect":
+            state = step("pipeline_state.py", "validate", *common)["state"]
+            if project_dir != ".project" or state["phase"] != "inspect" or state["status"] != "active":
+                raise StepFailed("initial inspection requires the active inspect track")
+            specs = INSPECTION_SPECS
+            if any((repo / project_dir / "research" / spec[3]).exists() or
+                   (repo / project_dir / "research" / spec[3]).is_symlink() for spec in specs):
+                raise StepFailed("prior inspection evidence requires the re-inspection contract")
+            branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
+                                    capture_output=True, text=True, check=True).stdout.strip()
+            if branch != state["branch"]:
+                raise StepFailed("current branch differs from the recorded inspection branch")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            inventory = step("check_docs_audit.py", "--repo", str(repo), "--emit-inventory", raw=True)
+            resources = scripts.parent
+            if not (resources / "references").is_dir():
+                resources = resources / "skills/gsd-path"
+            for _, role, template, _ in specs:
+                for path in (resources / "references" / f"{role}.md", resources / "templates" / f"{template}.md"):
+                    if not path.is_file():
+                        raise StepFailed(f"missing inspection resource: {path}")
+            staging = Path(tempfile.mkdtemp(prefix="gsd-path-inspect-"))
+            inventory_file = staging / "inventory.txt"
+            inventory_file.write_text(inventory, encoding="utf-8")
+            assignments = []
+            for task_name, role, template, filename in specs:
+                isolated = step("isolation.py", "isolate-verify", "--repo", str(repo),
+                                "--base", expected_head, "--name", task_name.replace("_", "-"))
+                role_path = resources / "references" / f"{role}.md"
+                template_path = resources / "templates" / f"{template}.md"
+                output = f"{project_dir}/research/{filename}"
+                brief_file = staging / f"{task_name}.md"
+                brief = (f"Logical task: {task_name}\nRead and follow role: {role_path}\n"
+                         f"Template: {template_path}\nRepository and command cwd: {isolated['worktree']}\n"
+                         f"Recorded baseline and Audited HEAD: {isolated['base']}\n"
+                         f"Write only: {Path(isolated['worktree']) / output}\n"
+                         "Use only this supplied sidecar for project commands; do not create worktrees.\n"
+                         "The parent owns gates, collection, retirement, and phase state.\n"
+                         "Exclude .git, node_modules, .project/archive, and installed GSD Path and path skill bundles.\n")
+                if task_name == "inspect_docs":
+                    brief += ("Alignment mode: false. No prior audit or changed set.\n"
+                              "Frozen inventory follows; use it exactly, without rediscovery:\n" + inventory)
+                brief_file.write_text(brief, encoding="utf-8")
+                assignments.append({**isolated, "task_name": task_name, "role": str(role_path),
+                                    "template": str(template_path), "output": output,
+                                    "brief_file": str(brief_file)})
+            receipt_file = staging / "inspection.json"
+            outputs["inspection"] = {"repo": str(repo), "base": expected_head,
+                                     "inventory_file": str(inventory_file),
+                                     "inventory_sha256": hashlib.sha256(inventory_file.read_bytes()).hexdigest(),
+                                     "assignments": assignments, "receipt_file": str(receipt_file)}
+            _common.atomic_write(receipt_file, json.dumps(outputs["inspection"], sort_keys=True) + "\n")
+        elif action == "finish-inspect":
+            if not mapper_reviewed or inspection is None or project_dir != ".project":
+                raise StepFailed("finish-inspect requires the prepared active track and mapper review")
+            prepared = json.loads(inspection.read_text(encoding="utf-8"))
+            if prepared["repo"] != str(repo) or prepared["base"] != expected_head:
+                raise StepFailed("inspection receipt does not match repository and expected HEAD")
+            assignments = {a["task_name"]: a for a in prepared["assignments"]}
+            if len(prepared["assignments"]) != len(INSPECTION_SPECS) or set(assignments) != {s[0] for s in INSPECTION_SPECS}:
+                raise StepFailed("inspection receipt must name both original assignments")
+            for task_name, _, _, filename in INSPECTION_SPECS:
+                assignment = assignments[task_name]
+                if assignment["base"] != expected_head or assignment["output"] != f".project/research/{filename}":
+                    raise StepFailed("inspection assignment changed its baseline or output")
+            inventory_file = Path(prepared["inventory_file"])
+            if hashlib.sha256(inventory_file.read_bytes()).hexdigest() != prepared["inventory_sha256"]:
+                raise StepFailed("frozen inspection inventory changed")
+            state = step("pipeline_state.py", "validate", *common)["state"]
+            if state["phase"] != "inspect" or state["status"] != "active":
+                raise StepFailed("inspection completion requires inspect/active")
+            branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
+                                    capture_output=True, text=True, check=True).stdout.strip()
+            if state["branch"] != branch:
+                raise StepFailed("current branch differs from the recorded inspection branch")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            docs = assignments["inspect_docs"]
+            step("check_docs_audit.py", "--repo", docs["worktree"], "--audit", docs["output"],
+                 "--inventory", str(inventory_file))
+            if f"Audited HEAD: {expected_head}" not in (Path(docs["worktree"]) / docs["output"]).read_text().splitlines():
+                raise StepFailed("audit does not name the supplied inspection baseline")
+            for task_name, _, _, _ in INSPECTION_SPECS:
+                assignment = assignments[task_name]
+                step("isolation.py", "collect-artifact", "--repo", str(repo),
+                     "--source", assignment["worktree"], "--base", expected_head,
+                     "--branch", assignment["branch"], "--source-path", assignment["output"],
+                     "--destination-path", assignment["output"])
+                step("isolation.py", "retire", "--repo", str(repo), "--worktree", assignment["worktree"],
+                     "--branch", assignment["branch"])
+            expected = [part for key, value in state.items()
+                        for part in (f"--expect-{key}", "null" if value is None else str(value))]
+            step("pipeline_state.py", "transition", *common, *expected,
+                 "--set-phase", "inspect", "--set-status", "done", "--event", "inspection artifacts passed")
         elif action == "lint-round":
             head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
                                   cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
@@ -87,28 +193,31 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             if action == "approve-plan":
                 step("pipeline_state.py", "approve", *common, "--kind", "plan",
                      "--expected-head", expected_head)
-    except (StepFailed, OSError, subprocess.CalledProcessError) as error:
+    except (StepFailed, OSError, subprocess.CalledProcessError, ValueError, KeyError, TypeError) as error:
         return {"status": "blocked", "reason": str(error), "steps": steps,
                 "next": "$gsd-path-forensics"}
-    return {"status": "complete", "steps": steps}
+    return {"status": "complete", "steps": steps, **outputs}
 def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final"))
+    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"))
     parser.add_argument("--repo", type=Path, required=True)
     parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
     parser.add_argument("--expected-head")
     parser.add_argument("--task-id")
     parser.add_argument("--round-size", type=int)
+    parser.add_argument("--inspection", type=Path)
+    parser.add_argument("--mapper-reviewed", action="store_true")
     arguments = parser.parse_args(argv)
-    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final"} and not arguments.expected_head:
+    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"} and not arguments.expected_head:
         parser.error(f"{arguments.action} requires --expected-head")
     if arguments.action == "prepare-task" and (not arguments.task_id or arguments.round_size is None):
         parser.error("prepare-task requires --task-id and --round-size")
     result = run_workflow(arguments.repo.resolve(), arguments.action,
                           arguments.project_dir, arguments.expected_head,
-                          arguments.task_id, arguments.round_size)
+                          arguments.task_id, arguments.round_size, arguments.inspection,
+                          arguments.mapper_reviewed)
     print(json.dumps(result, sort_keys=True))
     return 0 if result["status"] == "complete" else 1