agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/next_turn_slot.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+
+FIXED_SLOT_YAML = Path(".agentic/commands/inbox/next-turn.yaml")
+FIXED_SLOT_SCRIPT = Path(".agentic/commands/inbox/next-turn.py")
+
+@dataclass(frozen=True)
+class FixedSlotStatus:
+    state: str
+    yaml_exists: bool
+    script_exists: bool
+    overwrite_allowed: bool
+    reason: str
+    yaml_path: str
+    script_path: str
+
+def fixed_slot_status(root: Path | str = ".") -> FixedSlotStatus:
+    root_path = Path(root)
+    yaml_path = root_path / FIXED_SLOT_YAML
+    script_path = root_path / FIXED_SLOT_SCRIPT
+    yaml_exists = yaml_path.exists()
+    script_exists = script_path.exists()
+    if yaml_exists and script_exists:
+        return FixedSlotStatus("ready", True, True, False, "fixed-slot work order exists", str(FIXED_SLOT_YAML), str(FIXED_SLOT_SCRIPT))
+    if yaml_exists or script_exists:
+        return FixedSlotStatus("partial", yaml_exists, script_exists, False, "fixed-slot work order is incomplete; use --force only after inspection", str(FIXED_SLOT_YAML), str(FIXED_SLOT_SCRIPT))
+    return FixedSlotStatus("empty", False, False, True, "no fixed-slot work order exists", str(FIXED_SLOT_YAML), str(FIXED_SLOT_SCRIPT))
+
+def render_status(status: FixedSlotStatus) -> str:
+    return "\n".join([
+        "NEXT_TURN_FIXED_SLOT_STATUS",
+        f"state={status.state}",
+        f"yaml_exists={str(status.yaml_exists).lower()}",
+        f"script_exists={str(status.script_exists).lower()}",
+        f"overwrite_allowed={str(status.overwrite_allowed).lower()}",
+        f"yaml_path={status.yaml_path}",
+        f"script_path={status.script_path}",
+        f"reason={status.reason}",
+        "### RESULT: PASS ###",
+    ])
+
+def default_yaml(command_id: str = "next-turn") -> str:
+    return "\n".join([
+        "schema_version: 1",
+        f"command_id: {command_id}",
+        "kind: fixed-slot-work-order",
+        "slot: next-turn",
+        "entrypoint: .agentic/commands/inbox/next-turn.py",
+        "safety_class: bounded",
+        "status: pending",
+        "evidence:",
+        "  local_terminal_log: ${AGENTIC_KIT_NEXT_TURN_LOG:-tmp/next-turn-latest.log}",
+        "  remote_terminal_log: docs/reports/terminal/next-turn-latest.log",
+        "  command_report: docs/reports/command_runs/next-turn-latest.json",
+        "",
+    ])
+
+def default_script() -> str:
+    return "\n".join([
+        "#!/usr/bin/env python3",
+        "from __future__ import annotations",
+        "",
+        "def main() -> int:",
+        "    print(\"NEXT_TURN_FIXED_SLOT_PLACEHOLDER\")",
+        "    print(\"status=pending_runner\")",
+        "    print(\"### RESULT: PASS ###\")",
+        "    return 0",
+        "",
+        "if __name__ == \"__main__\":",
+        "    raise SystemExit(main())",
+        "",
+    ])
+
+def write_fixed_slot(root: Path | str = ".", *, force: bool = False, command_id: str = "next-turn") -> FixedSlotStatus:
+    root_path = Path(root)
+    status = fixed_slot_status(root_path)
+    if status.state != "empty" and not force:
+        raise RuntimeError(f"fixed slot is not empty: {status.state}")
+    yaml_path = root_path / FIXED_SLOT_YAML
+    script_path = root_path / FIXED_SLOT_SCRIPT
+    yaml_path.parent.mkdir(parents=True, exist_ok=True)
+    yaml_path.write_text(default_yaml(command_id), encoding="utf-8")
+    script_path.write_text(default_script(), encoding="utf-8")
+    script_path.chmod(0o755)
+    return fixed_slot_status(root_path)
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="next-turn-slot")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("status")
+    write_parser = sub.add_parser("write")
+    write_parser.add_argument("--force", action="store_true")
+    write_parser.add_argument("--command-id", default="next-turn")
+    args = parser.parse_args()
+    if args.command == "status":
+        print(render_status(fixed_slot_status()))
+        return 0
+    if args.command == "write":
+        print(render_status(write_fixed_slot(force=args.force, command_id=args.command_id)))
+        return 0
+    raise AssertionError(args.command)
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_project_kit/next_turn_status.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+from agentic_project_kit.evidence_inspector import EvidenceVerdict
+from agentic_project_kit.evidence_inspector import inspect_evidence
+from agentic_project_kit.next_turn_slot import FIXED_SLOT_SCRIPT
+from agentic_project_kit.next_turn_slot import FIXED_SLOT_YAML
+
+VALID_STATES = {"empty", "prepared", "running", "completed", "failed", "blocked", "recovery_needed"}
+
+EVIDENCE_LOOKUP_ORDER = (
+    "docs/reports/command_runs/next-turn-latest.json",
+    "docs/reports/command_runs/next-turn-latest.md",
+    "docs/reports/terminal/next-turn-latest.log",
+    ".agentic/commands/executed.jsonl",
+)
+
+@dataclass(frozen=True)
+class NextTurnStatus:
+    state: str
+    yaml_exists: bool
+    script_exists: bool
+    overwrite_allowed: bool
+    reason: str
+
+def _extract_state(yaml_text: str) -> str | None:
+    match = re.search(r"(?m)^state:\s*([A-Za-z0-9_-]+)\s*$", yaml_text)
+    return match.group(1) if match else None
+
+def detect_next_turn_status(root: Path | str = ".") -> NextTurnStatus:
+    root_path = Path(root)
+    yaml_path = root_path / FIXED_SLOT_YAML
+    script_path = root_path / FIXED_SLOT_SCRIPT
+    yaml_exists = yaml_path.exists()
+    script_exists = script_path.exists()
+    if not yaml_exists and not script_exists:
+        return NextTurnStatus("empty", False, False, True, "no fixed-slot files exist")
+    if yaml_exists != script_exists:
+        return NextTurnStatus("blocked", yaml_exists, script_exists, False, "partial fixed-slot state")
+    try:
+        declared = _extract_state(yaml_path.read_text(encoding="utf-8"))
+    except UnicodeDecodeError:
+        return NextTurnStatus("blocked", True, True, False, "next-turn yaml is not valid utf-8")
+    if declared is None:
+        return NextTurnStatus("blocked", True, True, False, "next-turn yaml has no state field")
+    if declared not in VALID_STATES:
+        return NextTurnStatus("blocked", True, True, False, f"unknown state: {declared}")
+    overwrite_allowed = declared in {"completed", "failed"}
+    reason = "completed or failed slot may be replaced" if overwrite_allowed else f"{declared} slot must not be overwritten"
+    return NextTurnStatus(declared, True, True, overwrite_allowed, reason)
+
+def _bool(value: bool) -> str:
+    return "true" if value else "false"
+
+def render_status(status: NextTurnStatus) -> str:
+    lines = [
+        "NEXT_TURN_STATUS",
+        f"state={status.state}",
+        f"yaml_exists={_bool(status.yaml_exists)}",
+        f"script_exists={_bool(status.script_exists)}",
+        f"overwrite_allowed={_bool(status.overwrite_allowed)}",
+        f"reason={status.reason}",
+        "evidence_lookup_order:",
+    ]
+    lines.extend(f"- {path}" for path in EVIDENCE_LOOKUP_ORDER)
+    lines.append("### RESULT: PASS ###")
+    return "\n".join(lines)
+
+def _read_preview(path: Path) -> str:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if path.suffix == ".json":
+        try:
+            return json.dumps(json.loads(text), indent=2, sort_keys=True)
+        except json.JSONDecodeError:
+            return text[:4000]
+    if path.name == "executed.jsonl":
+        lines = [line for line in text.splitlines() if line.strip()]
+        return lines[-1] if lines else ""
+    return text[:4000]
+
+
+def _classify_executed_jsonl(preview: str) -> tuple[str, str, str, str]:
+    if not preview:
+        return (
+            "FOUND_UNUSABLE",
+            "MISSING_EVIDENCE_UPLOAD_FIRST",
+            "paste-output",
+            "executed ledger exists but contains no usable entry; inspect terminal evidence before requesting pasted output",
+        )
+    try:
+        payload = json.loads(preview)
+    except json.JSONDecodeError:
+        return (
+            "FOUND_UNUSABLE",
+            "AMBIGUOUS_SUMMARY_REVIEW_REQUIRED",
+            "paste-output",
+            "executed ledger latest entry is unreadable; inspect terminal evidence before requesting pasted output",
+        )
+
+    outcome = str(payload.get("outcome") or "")
+    exit_code = payload.get("exit_code")
+
+    if outcome == "PASS_EXECUTED" or exit_code == 0:
+        return (
+            "FOUND_PASS",
+            "PASS_CONTINUE",
+            "d",
+            "continue from executed command ledger",
+        )
+    if outcome.startswith("FAIL") or isinstance(exit_code, int) and exit_code != 0:
+        return (
+            "FOUND_FAIL",
+            "FAIL_DIAGNOSE",
+            "f",
+            "diagnose from executed command ledger and inspect terminal evidence if needed",
+        )
+    return (
+        "FOUND_AMBIGUOUS",
+        "AMBIGUOUS_SUMMARY_REVIEW_REQUIRED",
+        "paste-output",
+        "executed ledger latest entry is ambiguous; inspect terminal evidence before requesting pasted output",
+    )
+
+@dataclass(frozen=True)
+class LastResult:
+    path: Path | None
+    checked_paths: tuple[str, ...]
+    preview: str
+    status: str
+    evidence_verdict: str
+    recommended_chat_reply: str
+    recovery: str
+
+
+def _classify_json_result(path: Path, preview: str) -> tuple[str, str, str, str]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return (
+            "FOUND_UNUSABLE",
+            "AMBIGUOUS_SUMMARY_REVIEW_REQUIRED",
+            "paste-output",
+            "JSON result is unreadable; inspect terminal log before requesting pasted output.",
+        )
+
+    overall = str(payload.get("overall_result") or payload.get("work_result") or payload.get("outcome") or "")
+    remote = str(payload.get("remote_evidence") or "")
+    reply = str(payload.get("next_chat_reply") or "")
+
+    if reply:
+        recommended = reply
+    elif overall in {"PASS", "PASS_ALREADY_DONE", "NOOP", "PASS_EXECUTED"}:
+        recommended = "d"
+    elif remote in {"PASS", "PARTIAL"}:
+        recommended = "f"
+    else:
+        recommended = "paste-output"
+
+    if overall in {"PASS", "PASS_ALREADY_DONE", "NOOP", "PASS_EXECUTED"}:
+        verdict = "PASS_CONTINUE"
+        status = "FOUND_PASS"
+        recovery = "continue from structured command result"
+    elif overall in {"FAIL", "HARD_FAIL", "FAIL_EXECUTED", "FAIL_NO_FIXED_SLOT"}:
+        verdict = "FAIL_DIAGNOSE"
+        status = "FOUND_FAIL"
+        recovery = "diagnose from structured command result and then inspect terminal evidence if needed"
+    else:
+        verdict = "AMBIGUOUS_SUMMARY_REVIEW_REQUIRED"
+        status = "FOUND_AMBIGUOUS"
+        recovery = "inspect terminal evidence before requesting pasted output"
+
+    if recommended == "paste-output" and "docs/reports/terminal/next-turn-latest.log" in preview:
+        recovery = "inspect the referenced terminal log before requesting pasted output"
+
+    return status, verdict, recommended, recovery
+
+
+def _classify_terminal_result(path: Path, root: Path) -> tuple[str, str, str, str]:
+    inspection = inspect_evidence(path, root=root, require_summary=False)
+    verdict = inspection.verdict.value
+    if inspection.verdict == EvidenceVerdict.PASS_CONTINUE:
+        return "FOUND_PASS", verdict, "d", "continue from inspected terminal evidence"
+    if inspection.verdict == EvidenceVerdict.FAIL_DIAGNOSE:
+        return "FOUND_FAIL", verdict, "f", "diagnose from inspected terminal evidence"
+    if inspection.verdict == EvidenceVerdict.MISSING_EVIDENCE_UPLOAD_FIRST:
+        return "FOUND_UNUSABLE", verdict, "paste-output", "upload or locate evidence before requesting pasted output"
+    return "FOUND_AMBIGUOUS", verdict, "paste-output", "review ambiguous terminal evidence before requesting pasted output"
+
+
+def find_last_result(root: Path | str = ".") -> LastResult:
+    root_path = Path(root)
+    checked: list[str] = []
+    for relative in EVIDENCE_LOOKUP_ORDER:
+        checked.append(relative)
+        candidate = root_path / relative
+        if not candidate.exists():
+            continue
+        preview = _read_preview(candidate)
+        if candidate.suffix == ".json":
+            status, verdict, reply, recovery = _classify_json_result(candidate, preview)
+        elif candidate.name == "executed.jsonl":
+            status, verdict, reply, recovery = _classify_executed_jsonl(preview)
+        elif candidate.suffix in {".log", ".md"}:
+            status, verdict, reply, recovery = _classify_terminal_result(candidate, root_path)
+        else:
+            status, verdict, reply, recovery = (
+                "FOUND_AMBIGUOUS",
+                "AMBIGUOUS_SUMMARY_REVIEW_REQUIRED",
+                "paste-output",
+                "review result source before requesting pasted output",
+            )
+        return LastResult(candidate, tuple(checked), preview, status, verdict, reply, recovery)
+    return LastResult(
+        None,
+        tuple(checked),
+        "",
+        "NO_RESULT_FOUND",
+        "MISSING_EVIDENCE_UPLOAD_FIRST",
+        "paste-output",
+        "run ./ns next-turn --status before requesting pasted terminal output",
+    )
+
+
+def render_last_result(root: Path | str = ".") -> str:
+    result = find_last_result(root)
+    lines: list[str] = ["NEXT_TURN_LAST_RESULT"]
+    if result.path is None:
+        lines.append(f"status={result.status}")
+        lines.append(f"evidence_verdict={result.evidence_verdict}")
+        lines.append(f"recommended_chat_reply={result.recommended_chat_reply}")
+        lines.append("checked_paths:")
+        lines.extend(f"- {path}" for path in result.checked_paths)
+        lines.append(f"recovery={result.recovery}")
+        lines.append("### RESULT: PASS ###")
+        return "\n".join(lines)
+    try:
+        relative = result.path.relative_to(Path(root))
+    except ValueError:
+        relative = result.path
+    lines.append(f"status={result.status}")
+    lines.append(f"path={relative}")
+    lines.append(f"evidence_verdict={result.evidence_verdict}")
+    lines.append(f"recommended_chat_reply={result.recommended_chat_reply}")
+    lines.append(f"recovery={result.recovery}")
+    lines.append("checked_paths:")
+    lines.extend(f"- {path}" for path in result.checked_paths)
+    lines.append("preview:")
+    lines.append(result.preview)
+    lines.append("### RESULT: PASS ###")
+    return "\n".join(lines)
+
+def main(argv: Iterable[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="next-turn-status")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    next_turn = subparsers.add_parser("next-turn")
+    next_turn.add_argument("--status", action="store_true")
+    subparsers.add_parser("last-result")
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    if args.command == "next-turn":
+        print(render_status(detect_next_turn_status()))
+        return 0
+    if args.command == "last-result":
+        print(render_last_result())
+        return 0
+    raise AssertionError(args.command)
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_project_kit/ns_legacy_reference_audit.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+from typing import Iterable
+
+
+LEGACY_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"\./ns\b"),
+    re.compile(r"\bns-menu\b"),
+    re.compile(r"\bns_release_[A-Za-z0-9_]*"),
+    re.compile(r"\btools/ns_[A-Za-z0-9_./-]*"),
+    re.compile(r"\bNS RELEASE\b"),
+)
+
+TEXT_SUFFIXES = {
+    ".md",
+    ".rst",
+    ".txt",
+    ".py",
+    ".toml",
+    ".yaml",
+    ".yml",
+    ".json",
+    ".cff",
+}
+
+SKIP_DIR_PARTS = {
+    ".git",
+    ".venv",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+    "node_modules",
+    "tmp",
+}
+
+SKIP_PATH_PREFIXES = (
+    "docs/reports/",
+    ".agentic/transfer/outbox/",
+)
+
+CURRENT_INSTRUCTION_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"\b(run|execute|use|start|call|invoke|rerun|copy|paste|command|befehl|ausführen|starte)\b", re.I),
+    re.compile(r"^\s*(?:[-*]\s*)?(?:cd\s+\S+\s*&&\s*)?\./ns\b", re.I),
+    re.compile(r"^\s*(?:[-*]\s*)?tools/ns_", re.I),
+)
+
+HISTORICAL_MARKERS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"\b(historical|legacy|obsolete|removed|deprecated|archiv|archived|historisch|veraltet|entfernt)\b", re.I),
+    re.compile(r"\b(before|formerly|previously|früher|ehemalig)\b", re.I),
+)
+
+SAFE_CONTEXT_PATH_PARTS = (
+    "tests",
+    "docs/reports",
+    "docs/releases",
+    "docs/archive",
+    "CHANGELOG.md",
+)
+
+
+@dataclass(frozen=True)
+class LegacyReference:
+    path: str
+    line: int
+    text: str
+    classification: str
+    reason: str
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "path": self.path,
+            "line": self.line,
+            "text": self.text,
+            "classification": self.classification,
+            "reason": self.reason,
+        }
+
+
+@dataclass(frozen=True)
+class NsLegacyReferenceAuditResult:
+    status: str
+    returncode: int
+    references: tuple[LegacyReference, ...]
+    blockers: tuple[LegacyReference, ...]
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "status": self.status,
+            "returncode": self.returncode,
+            "references": [reference.as_dict() for reference in self.references],
+            "blockers": [reference.as_dict() for reference in self.blockers],
+            "ok": self.ok,
+        }
+
+
+def _is_text_file(path: Path) -> bool:
+    if path.suffix in TEXT_SUFFIXES:
+        return True
+    if path.name in {"CHANGELOG", "README", "LICENSE"}:
+        return True
+    return False
+
+
+def iter_candidate_files(project_root: Path) -> Iterable[Path]:
+    for path in sorted(project_root.rglob("*")):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(project_root).as_posix()
+        relative_parts = path.relative_to(project_root).parts
+        if any(part in SKIP_DIR_PARTS for part in relative_parts):
+            continue
+        if any(relative.startswith(prefix) for prefix in SKIP_PATH_PREFIXES):
+            continue
+        if not _is_text_file(path):
+            continue
+        yield path
+
+
+def _has_legacy_reference(line: str) -> bool:
+    return any(pattern.search(line) for pattern in LEGACY_PATTERNS)
+
+
+def _safe_context_by_path(relative: str) -> bool:
+    return relative.startswith(SAFE_CONTEXT_PATH_PARTS) or any(
+        part and relative.startswith(part + "/") for part in SAFE_CONTEXT_PATH_PARTS
+    )
+
+
+def _legacy_documentation_context(relative_path: str) -> bool:
+    return (
+        relative_path.startswith("docs/workflow/")
+        or relative_path.startswith("docs/governance/")
+        or relative_path.startswith("docs/strategy/")
+        or relative_path.startswith("docs/architecture/")
+        or relative_path.startswith("docs/planning/")
+        or relative_path == "docs/DOCUMENTATION_COVERAGE.yaml"
+        or relative_path == "docs/TEST_GATES.md"
+        or relative_path == "docs/WORKFLOW_OUTPUT_CYCLE.md"
+    )
+
+
+def _compatibility_implementation_context(relative_path: str) -> bool:
+    return relative_path in {
+        "src/agentic_project_kit/ns_legacy_reference_audit.py",
+        "src/agentic_project_kit/planning_docs_consolidation_audit.py",
+        "src/agentic_project_kit/release_gate_core.py",
+        "src/agentic_project_kit/release_verify_core.py",
+        "src/agentic_project_kit/removed_ns_commands.py",
+        "src/agentic_project_kit/work_order_validator.py",
+        "src/agentic_project_kit/gui_dry_run.py",
+        "src/agentic_project_kit/chat_bootloader.py",
+        "src/agentic_project_kit/doc_currency_audit.py",
+        "src/agentic_project_kit/entrypoint_slice_runner.py",
+        "src/agentic_project_kit/handoff_prompt.py",
+        "src/agentic_project_kit/release_prepare.py",
+        "src/agentic_project_kit/run_summary_renderer.py",
+        "src/agentic_project_kit/terminal_block_guard.py",
+        "tools/NEXT_TRANSFER_TASK.py",
+    }
+
+
+def classify_legacy_reference(relative_path: str, line: str) -> tuple[str, str]:
+    stripped = line.strip()
+    if _compatibility_implementation_context(relative_path):
+        return "compatibility_implementation", "legacy tokens are implementation/classifier compatibility patterns"
+    if relative_path.startswith("tests/"):
+        return "test_fixture", "test fixture/reference"
+    if _legacy_documentation_context(relative_path):
+        return "legacy_documentation_context", (
+            "planning/workflow/governance documentation; use follow-up documentation cleanup "
+            "rather than treating as current supported command surface"
+        )
+    if any(pattern.search(stripped) for pattern in HISTORICAL_MARKERS):
+        return "historical", "line contains explicit historical/legacy marker"
+    if relative_path.startswith("docs/reports/"):
+        return "generated_report_or_evidence", "report/evidence context"
+    if relative_path.startswith("docs/releases/") or relative_path == "CHANGELOG.md":
+        return "release_history", "release history context"
+    if _safe_context_by_path(relative_path) and not any(
+        pattern.search(stripped) for pattern in CURRENT_INSTRUCTION_PATTERNS
+    ):
+        return "historical", "safe documentation context without imperative wording"
+    if any(pattern.search(stripped) for pattern in CURRENT_INSTRUCTION_PATTERNS):
+        return "current_instruction_blocker", "looks like a current instruction or executable route"
+    return "needs_review", "legacy reference is not explicitly historical or a test fixture"
+
+
+def audit_ns_legacy_references(project_root: Path | str = ".") -> NsLegacyReferenceAuditResult:
+    root = Path(project_root).resolve()
+    references: list[LegacyReference] = []
+
+    for path in iter_candidate_files(root):
+        relative = path.relative_to(root).as_posix()
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            continue
+        for index, line in enumerate(lines, start=1):
+            if not _has_legacy_reference(line):
+                continue
+            classification, reason = classify_legacy_reference(relative, line)
+            references.append(
+                LegacyReference(
+                    path=relative,
+                    line=index,
+                    text=line.strip(),
+                    classification=classification,
+                    reason=reason,
+                )
+            )
+
+    blockers = tuple(
+        reference
+        for reference in references
+        if reference.classification in {"current_instruction_blocker", "needs_review"}
+    )
+    return NsLegacyReferenceAuditResult(
+        status="PASS" if not blockers else "BLOCK",
+        returncode=0 if not blockers else 1,
+        references=tuple(references),
+        blockers=blockers,
+    )
+
+
+def render_ns_legacy_reference_audit(result: NsLegacyReferenceAuditResult) -> str:
+    lines = [
+        "NS_LEGACY_REFERENCE_AUDIT",
+        f"STATUS={result.status}",
+        f"RETURNCODE={result.returncode}",
+        f"REFERENCE_COUNT={len(result.references)}",
+        f"BLOCKER_COUNT={len(result.blockers)}",
+    ]
+    for reference in result.references:
+        lines.append(
+            "REFERENCE="
+            f"{reference.classification}|{reference.path}:{reference.line}|{reference.text}"
+        )
+    for blocker in result.blockers:
+        lines.append(f"BLOCKER={blocker.path}:{blocker.line}|{blocker.reason}|{blocker.text}")
+    lines.append("FINAL_SIGNAL=d" if result.ok else "FINAL_SIGNAL=f")
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    result = audit_ns_legacy_references(Path("."))
+    print(render_ns_legacy_reference_audit(result), end="")
+    return result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_project_kit/ns_slice_runner.py

@@ -0,0 +1,16 @@
+"""Backward-compatible import shim for the neutral entrypoint slice runner.
+
+The supported implementation lives in
+:mod:`agentic_project_kit.entrypoint_slice_runner`.
+
+This shim remains temporarily to keep historical imports stable while active
+runtime paths move away from the ns-named module.
+"""
+
+from __future__ import annotations
+
+from agentic_project_kit.entrypoint_slice_runner import *  # noqa: F403
+from agentic_project_kit.entrypoint_slice_runner import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())