@static-var/keystone 0.1.0

package/scripts/validate-keystone.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Validate Keystone canonical source and packaging invariants."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SKILL_DIR = ROOT / "skills" / "keystone"
+SKILL = SKILL_DIR / "SKILL.md"
+MODULE_DIR = SKILL_DIR / "modules"
+PI_EXTENSION = ROOT / ".pi" / "extensions" / "keystone.ts"
+ALLOWLIST = ROOT / "packaging.allowlist"
+SUBAGENT_HELPER = MODULE_DIR / "helpers" / "subagents.md"
+TARGET_HARNESSES = ("Pi", "Claude", "Codex", "T3", "OpenCode", "Copilot")
+COMMON_PLAYBOOK_HEADINGS = (
+    "## Core principle",
+    "## Load when",
+    "## Not for",
+    "## Outcome contract",
+    "## Subagents and reasoning",
+    "## Hard rules",
+    "## Failure modes",
+    "## Output format",
+)
+MODULE_PLAYBOOK_HEADINGS = {
+    "build": ("## Modes", "## Process", "## Architecture taste checklist"),
+    "review": ("## Review passes", "## Severity rubric", "## Impact tracing", "## Security and regression checklist"),
+    "breakdown": ("## Modes", "## Process", "## Requirements inventory", "## Iteration layering", "## Task quality bar"),
+}
+DEFAULT_PLAYBOOK_HEADINGS = ("## Modes", "## Process")
+FORBIDDEN_TRACKED = {
+    "docs",
+    "plans",
+    "index.html",
+    "styles.css",
+}
+
+
+def fail(message: str) -> None:
+    print(f"validate-keystone: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def tracked_files() -> list[str]:
+    try:
+        result = subprocess.run(
+            ["git", "ls-files"], cwd=ROOT, text=True, check=True, capture_output=True
+        )
+    except Exception:
+        return []
+    return [line for line in result.stdout.splitlines() if line]
+
+
+def parse_frontmatter(text: str) -> dict[str, object]:
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+    data: dict[str, object] = {}
+    current_key = None
+    for raw in text[4:end].splitlines():
+        line = raw.rstrip()
+        if not line or line.lstrip().startswith("#"):
+            continue
+        if line.startswith("  - ") and current_key:
+            data.setdefault(current_key, []).append(line[4:].strip().strip('"\''))
+            continue
+        if ":" in line:
+            key, value = line.split(":", 1)
+            current_key = key.strip()
+            value = value.strip()
+            data[current_key] = [] if value == "" else value.strip('"\'')
+    return data
+
+
+def check_skill() -> str:
+    if not SKILL_DIR.is_dir():
+        fail("missing canonical skill directory skills/keystone/")
+    if not SKILL.is_file():
+        fail("missing canonical skill file skills/keystone/SKILL.md")
+    text = SKILL.read_text()
+    metadata = parse_frontmatter(text)
+    name = metadata.get("name")
+    if name is None:
+        heading = re.search(r"^#\s+(.+)$", text, re.M)
+        name = heading.group(1).strip().lower() if heading else None
+    if str(name).lower() != "keystone":
+        fail("skill name must be keystone")
+    return text
+
+
+def check_language(text: str) -> None:
+    public_plan = re.compile(r"(?<![\w/.-])/(?:plan)(?![\w/.-])|\bplanner\s+name\s+is\s+plan\b", re.I)
+    if public_plan.search(text):
+        fail("public /plan mention found; Keystone uses breakdown")
+    if not re.search(r"\bbreakdown\b", text, re.I):
+        fail("missing required breakdown terminology")
+
+
+def check_references(text: str) -> None:
+    refs = sorted(set(re.findall(r"\(([^)]+\.(?:md|json|yaml|yml|txt|sh|py))\)", text)))
+    refs += sorted(set(re.findall(r"(?:^|\s)([A-Za-z0-9_./-]+\.(?:md|json|yaml|yml|txt|sh|py))", text)))
+    missing = []
+    for ref in refs:
+        if ref.startswith(("http://", "https://", "mailto:")) or ref.startswith("/"):
+            continue
+        candidate = (SKILL_DIR / ref).resolve()
+        try:
+            candidate.relative_to(ROOT)
+        except ValueError:
+            continue
+        if not candidate.exists():
+            missing.append(ref)
+    if missing:
+        fail("missing referenced module/gate files: " + ", ".join(sorted(set(missing))))
+
+
+def routing_modules(text: str) -> set[str]:
+    return {
+        match.group(1)
+        for match in re.finditer(r"`modules/([a-z-]+)\.md`", text)
+    }
+
+
+def check_product_modules(skill_text: str) -> None:
+    primary_modules = routing_modules(skill_text)
+    root_modules = {path.stem for path in MODULE_DIR.glob("*.md")}
+    extra = sorted(root_modules - primary_modules)
+    missing = sorted(primary_modules - root_modules)
+    if extra:
+        fail("module files not present in routing table: " + ", ".join(extra))
+    if missing:
+        fail("routing table modules missing files: " + ", ".join(missing))
+
+
+def check_module_playbooks(skill_text: str) -> None:
+    primary_modules = routing_modules(skill_text)
+    pseudo_modules = {"tests", "package", "plan"}
+    allowed_terms = {"plan"}  # allowed only as a concept; public /plan remains forbidden elsewhere.
+    for path in MODULE_DIR.glob("*.md"):
+        text = path.read_text()
+        invalid = sorted(
+            token for token in re.findall(r"`([a-z][a-z-]+)`", text)
+            if token in pseudo_modules and token not in primary_modules and token not in allowed_terms
+        )
+        if invalid:
+            fail(f"module {path.stem} references non-shipped pseudo-modules: " + ", ".join(invalid))
+    for name in sorted(primary_modules - {"router"}):
+        module = MODULE_DIR / f"{name}.md"
+        text = module.read_text()
+        required = COMMON_PLAYBOOK_HEADINGS + MODULE_PLAYBOOK_HEADINGS.get(
+            name,
+            DEFAULT_PLAYBOOK_HEADINGS,
+        )
+        missing = [
+            heading for heading in required
+            if re.search(rf"^{re.escape(heading)}\s*$", text, re.M) is None
+        ]
+        if missing:
+            fail(f"module {name} missing playbook headings: " + ", ".join(missing))
+
+
+def check_subagent_helper(skill_text: str) -> None:
+    if not SUBAGENT_HELPER.is_file():
+        fail("missing subagent reasoning helper modules/helpers/subagents.md")
+    helper_text = SUBAGENT_HELPER.read_text()
+    missing_harnesses = [name for name in TARGET_HARNESSES if name not in helper_text]
+    if missing_harnesses:
+        fail("subagent helper missing target harnesses: " + ", ".join(missing_harnesses))
+    primary_modules = routing_modules(skill_text)
+    if not primary_modules:
+        fail("no primary modules found in Keystone routing table")
+    missing_modules = [
+        name for name in sorted(primary_modules)
+        if f"modules/{name}.md" not in helper_text
+    ]
+    if missing_modules:
+        fail("subagent helper missing module reasoning rows: " + ", ".join(missing_modules))
+    for name in sorted(primary_modules):
+        module = MODULE_DIR / f"{name}.md"
+        if not module.is_file():
+            fail(f"missing primary module file: modules/{name}.md")
+        if "## Subagents and reasoning" not in module.read_text():
+            fail(f"module missing subagent reasoning section: modules/{name}.md")
+
+
+def check_ignored_not_tracked() -> None:
+    bad = []
+    for path in tracked_files():
+        first = path.split("/", 1)[0]
+        if path in FORBIDDEN_TRACKED or first in FORBIDDEN_TRACKED:
+            bad.append(path)
+    if bad:
+        fail("ignored artifacts are tracked: " + ", ".join(bad))
+
+
+def allowlist_entries() -> set[str]:
+    if not ALLOWLIST.is_file():
+        fail("missing packaging.allowlist")
+    return {
+        line.strip()
+        for line in ALLOWLIST.read_text().splitlines()
+        if line.strip() and not line.lstrip().startswith("#")
+    }
+
+
+def check_package_json() -> None:
+    package_path = ROOT / "package.json"
+    if not package_path.is_file():
+        fail("missing package.json")
+    package = json.loads(package_path.read_text())
+    for key in ("name", "version", "description", "license", "keywords"):
+        if key not in package:
+            fail(f"package.json missing {key}")
+    if package.get("name") != "@static-var/keystone":
+        fail('package.json name must be "@static-var/keystone" for npm/pi.dev publishing')
+    keywords = package.get("keywords", [])
+    if not isinstance(keywords, list) or "pi-package" not in keywords:
+        fail('package.json keywords must include "pi-package"')
+    files = package.get("files")
+    expected_files = allowlist_entries()
+    if set(files or []) != expected_files:
+        fail("package.json files must exactly match packaging.allowlist entries")
+    pi = package.get("pi", {})
+    if pi.get("skills") != ["./skills"]:
+        fail('package.json must set pi.skills to ["./skills"]')
+    if pi.get("extensions") != ["./.pi/extensions/keystone.ts"]:
+        fail('package.json must set pi.extensions to ["./.pi/extensions/keystone.ts"]')
+    if not PI_EXTENSION.is_file():
+        fail("missing Pi extension .pi/extensions/keystone.ts")
+    extension = PI_EXTENSION.read_text()
+    if 'registerCommand("keystone"' not in extension:
+        fail("Pi extension must register public /keystone command")
+    leaked = sorted(
+        name for name in routing_modules(check_skill())
+        if name != "keystone" and f'registerCommand("{name}"' in extension
+    )
+    if leaked:
+        fail("Pi extension exposes internal modules as slash commands: " + ", ".join(leaked))
+
+
+def main() -> int:
+    text = check_skill()
+    check_language(text)
+    check_references(text)
+    check_product_modules(text)
+    check_module_playbooks(text)
+    check_subagent_helper(text)
+    check_ignored_not_tracked()
+    check_package_json()
+    print("validate-keystone: ok")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/validate-package.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Validate the Keystone release archive contents."""
+from __future__ import annotations
+
+import sys
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+ALLOWLIST = ROOT / "packaging.allowlist"
+
+REQUIRED = {
+    "README.md",
+    "HOW_IT_WORKS.md",
+    "package.json",
+    "packaging.allowlist",
+    "Makefile",
+    "scripts/build-metadata.py",
+    "scripts/validate-keystone.py",
+    "scripts/validate-package.py",
+    "scripts/package-keystone.sh",
+    ".pi/extensions/keystone.ts",
+    "skills/keystone/SKILL.md",
+    "skills/keystone/modules/router.md",
+    "skills/keystone/modules/research.md",
+    "skills/keystone/modules/shape.md",
+    "skills/keystone/modules/breakdown.md",
+    "skills/keystone/modules/build.md",
+    "skills/keystone/modules/debug.md",
+    "skills/keystone/modules/review.md",
+    "skills/keystone/modules/ship.md",
+    "skills/keystone/modules/health.md",
+    "skills/keystone/modules/helpers/subagents.md",
+    "skills/keystone/modules/gates/isolation.md",
+    "skills/keystone/modules/gates/proof.md",
+    ".claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+    ".codex-plugin/plugin.json",
+    ".agents/plugins/marketplace.json",
+}
+FORBIDDEN_NAMES = {
+    "index.html",
+    "styles.css",
+    "skill-engineering.md",
+    ".DS_Store",
+}
+FORBIDDEN_PREFIXES = (
+    "docs/",
+    "plans/",
+    "maintainers/",
+    "dist/",
+    ".git/",
+    ".keystone/plans/",
+    ".keystone/specs/",
+    ".keystone/tmp/",
+    "__pycache__/",
+)
+FORBIDDEN_SUFFIXES = (
+    ".pyc",
+    ".plan.md",
+    "-plan.md",
+    ".design.md",
+    "-design.md",
+)
+
+
+def fail(message: str) -> None:
+    print(f"validate-package: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def forbidden(path: str) -> bool:
+    base = path.rsplit("/", 1)[-1]
+    return (
+        base in FORBIDDEN_NAMES
+        or path.startswith(FORBIDDEN_PREFIXES)
+        or path.endswith(FORBIDDEN_SUFFIXES)
+    )
+
+
+def expand_allowlist() -> set[str] | None:
+    if not ALLOWLIST.is_file():
+        return None
+    expanded: set[str] = set()
+    for raw in ALLOWLIST.read_text().splitlines():
+        path = raw.strip()
+        if not path or path.startswith("#"):
+            continue
+        if forbidden(path) or path in {"dist", "docs", "plans", "maintainers", ".git"}:
+            fail(f"forbidden allowlist entry: {path}")
+        candidate = ROOT / path
+        if not candidate.exists():
+            fail(f"allowlisted path missing: {path}")
+        if candidate.is_dir():
+            for child in candidate.rglob("*"):
+                if child.is_file():
+                    rel = child.relative_to(ROOT).as_posix()
+                    if not forbidden(rel):
+                        expanded.add(rel)
+        else:
+            expanded.add(path)
+    return expanded
+
+
+def main(argv: list[str]) -> int:
+    archive = Path(argv[1]) if len(argv) > 1 else Path("dist/keystone.zip")
+    if not archive.is_file():
+        fail(f"archive not found: {archive}")
+    with zipfile.ZipFile(archive) as zf:
+        names = {name for name in zf.namelist() if not name.endswith("/")}
+    missing = sorted(REQUIRED - names)
+    if missing:
+        fail("missing required files: " + ", ".join(missing))
+    forbidden_names = sorted(name for name in names if forbidden(name))
+    if forbidden_names:
+        fail("forbidden files present: " + ", ".join(forbidden_names))
+
+    expected = expand_allowlist()
+    if expected is None:
+        expected_list = archive.parent / "keystone.files"
+        if expected_list.is_file():
+            expected = {
+                line.strip()
+                for line in expected_list.read_text().splitlines()
+                if line.strip()
+            }
+    if expected is not None:
+        extra = sorted(names - expected)
+        absent = sorted(expected - names)
+        if extra:
+            fail("archive contains files outside expanded allowlist: " + ", ".join(extra))
+        if absent:
+            fail("expanded allowlist files missing from archive: " + ", ".join(absent))
+
+    print("validate-package: ok")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/skills/keystone/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: keystone
+description: Use when the user invokes /keystone or asks Keystone to route product, research, writing, UI, design, planning, implementation, debugging, review, shipping, or health work through its canonical orchestrator.
+---
+
+# Keystone
+
+Keystone is a router/orchestrator skill. It selects the right internal module for the user's current request, carries handoffs between modules, and keeps only one public entrypoint: `/keystone`.
+
+## Routing rule
+
+Load exactly one primary module for the current task. Load gates or helper modules only when the primary module explicitly needs them. Do not expose internal modules as public slash commands. Actively route the work: name the selected module, preserve the current handoff packet, and state the next gate or check before taking irreversible action.
+
+## Orchestration sequences
+
+Use these common paths unless the user's immediate next action clearly points elsewhere:
+
+- Product or feature work: `research -> shape -> breakdown -> build -> review -> ship`.
+- Existing plan or approved design: `breakdown -> build -> review -> ship`.
+- Direct implementation request: `build -> review -> ship`, loading `breakdown` first only when execution order or verification is unclear.
+- Debug loop: `debug -> build -> proof gate -> review`; return to `debug` if proof fails or new symptoms appear.
+- Health finding that needs repair: `health -> build` for contained fixes, or `health -> review` when the finding needs independent validation before mutation.
+
+Do not add these as shipped modules; they are routing sequences over the existing nine modules.
+
+## Handoff packet contract
+
+Whenever one module hands work to another, carry a concise packet:
+
+- `source module`: module producing the handoff
+- `target module`: module to load next
+- `goal`: one-sentence outcome for the next module
+- `evidence`: facts, command output, user decisions, or citations already established
+- `files`: relevant paths and whether they are read-only, mutable, or protected
+- `risks`: known uncertainty, skipped checks, safety constraints, or rollback concerns
+- `next check`: the gate, command, question, or review the target should run first
+
+If the user overrides a gate, review, or sequence step, record the explicit override in the packet with the risk accepted. Never silently bypass hard safety constraints such as protected files, secret handling, isolation requirements, destructive operations, or policy restrictions; stop and ask or refuse as appropriate.
+
+## Re-entry contract
+
+When a module temporarily routes to another module and then resumes, the returning module must receive the handoff packet plus the result.
+
+- Build -> Debug -> Build: carry the failing symptom, reproduction command, suspected root cause, files inspected, fix recommendation, and proof command. On return to Build, rerun isolation if mutation scope changed, rerun proof for the original symptom, and rerun review if the fix touches behavior, public API, security, data, or release surfaces.
+- Build -> Research/Shape/Breakdown -> Build: carry the clarified decision or plan delta. On return, rerun the relevant Build preflight only for changed scope; do not redo unchanged gates without reason.
+- Review -> Debug/Build -> Review: carry review findings and changed files. On return, review the addressed findings and any newly touched risk area.
+- Health -> Build/Review: carry health evidence, severity, and recommended first check. Build may fix only contained, well-evidenced issues; uncertain or broad health findings go to Review first.
+
+## Subagents and reasoning
+
+When a module may delegate work, consult `modules/helpers/subagents.md` for host capability, safe delegation rules, and the recommended reasoning level for each Keystone module. If the host cannot enforce per-subagent reasoning, include the desired level in the subagent prompt or work inline.
+
+## Routing table
+
+| User intent | Primary module |
+|---|---|
+| Choose the right Keystone path, classify intent, resolve module ambiguity | `modules/router.md` |
+| Read, inspect, summarize, extract, research, compare sources, investigate options | `modules/research.md` |
+| Draft, rewrite, UI/UX, visual direction, product decisions, architecture, feature scope | `modules/shape.md` |
+| Breakdown approved design into executable tasks and verification steps | `modules/breakdown.md` |
+| Implement or change files/code/content | `modules/build.md` |
+| Diagnose failures, failing behavior, errors, bug reports, regressions, unexpected behavior | `modules/debug.md` |
+| Review work without changing it | `modules/review.md` |
+| Finalize completed work for delivery or integration | `modules/ship.md` |
+| Agent/tooling health, repository condition, skill drift, context rot, risks | `modules/health.md` |
+
+## Ambiguity rule
+
+If several modules could apply, choose the module matching the next irreversible action. If still ambiguous, ask one concise clarifying question before loading a primary module.