@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/plans_discipline_language_grep.py

@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify the canonical Plans Discipline language reaches every required surface.
+
+Why this validator exists. Spec section 3 declares Plans Discipline as
+multi-surface enforcement (defense-in-depth). Four surfaces MUST carry
+the directive:
+
+* ``AGENTS.md`` — the canonical project instruction surface.
+* ``CLAUDE.md`` — the Claude Code mirror.
+* ``src/apothem/output-styles/default.md`` — the ecosystem-default tonal floor.
+* ``.github/copilot-instructions.md`` — the Copilot-side mirror.
+
+Each surface MUST contain either (a) the byte-exact fixture sentence
+at ``tests/fixtures/plans-discipline.txt``, or (b) a semantic-paraphrase
+that covers the canonical token set with sufficient density. The
+two-mode admission honors the multi-surface-coherence comparator's
+semantic-equivalence-token approach: byte-exact reproduction is
+strongest, paraphrase with token coverage is acceptable.
+
+Detection strategy. The validator walks the four surfaces from
+``--root`` (the repository root). Per surface, it first probes for
+byte-exact fixture presence; on miss, it computes a token-coverage
+score against the canonical token set. A coverage of ``COVERAGE_FLOOR``
+(0.6) admits the surface; below the floor is a finding.
+
+Exit semantics. Exits 0 when every surface passes; exits 2 on any
+finding. The exit-2 convention matches the conformity-gate
+orchestrator's EXIT_FAIL constant.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+GREP_NAME: Final[str] = "plans-discipline-language-grep"
+RULE_ANCHOR: Final[str] = "CLAUDE.md Plans Discipline (multi-surface language)"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+# Surfaces that MUST carry the Plans Discipline directive. Paths are
+# relative to the repository root supplied at invocation.
+REQUIRED_SURFACES: Final[tuple[str, ...]] = (
+    "AGENTS.md",
+    "CLAUDE.md",
+    "src/apothem/output-styles/default.md",
+    ".github/copilot-instructions.md",
+)
+
+# Path to the byte-exact fixture relative to the repository root.
+FIXTURE_PATH: Final[str] = "tests/fixtures/plans-discipline.txt"
+
+# Canonical token set the paraphrase tolerance scores against. Each entry is a
+# tuple of accepted alternatives; the entry counts toward coverage when ANY of
+# its alternatives appears (case-insensitive substring). The tokens capture the
+# directive's load-bearing semantics: the canonical destination, the negative
+# claim, the global ban, and the non-negotiability frame.
+#
+# The canonical-destination entry is the sole project-local plans location
+# ``<project-root>/.apothem/plans/``; a legacy ``<project-root>/.plans/`` tree
+# is no longer canonical — operators upgrade it via ``apothem migrate-workspace``.
+CANONICAL_TOKENS: Final[tuple[tuple[str, ...], ...]] = (
+    ("<project-root>/.apothem/plans/",),
+    ("~/.codex/",),
+    ("~/.claude/",),
+    ("never",),
+    ("global",),
+    ("plans discipline",),
+)
+COVERAGE_FLOOR: Final[float] = 0.6
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One surface that lacks the directive at admission strength."""
+
+    surface: str
+    detail: str
+    coverage: float
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class SurfaceVerdict:
+    """Per-surface admission record (informational; survives passing surfaces)."""
+
+    surface: str
+    mode: str
+    coverage: float
+    admitted: bool
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    """Aggregated multi-surface sweep result."""
+
+    grep: str
+    root: str
+    fixture_present: bool
+    surfaces: list[SurfaceVerdict]
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "fixture_present": self.fixture_present,
+            "surfaces": [asdict(s) for s in self.surfaces],
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _read_fixture(root: Path) -> str | None:
+    """Return the fixture body, or None when the fixture file is absent."""
+    fixture_file = root / FIXTURE_PATH
+    if not fixture_file.exists():
+        return None
+    return fixture_file.read_text(encoding="utf-8").strip()
+
+
+def _coverage(body: str, tokens: tuple[tuple[str, ...], ...]) -> float:
+    """Fraction of token entries present in body (case-insensitive substring).
+
+    Each entry is a tuple of accepted alternatives; an entry counts when ANY of
+    its alternatives appears. The canonical-destination entry admits the sole
+    project-local ``<project-root>/.apothem/plans/`` phrasing.
+    """
+    if not tokens:
+        return 1.0
+    lowered = body.lower()
+    matched = sum(
+        1
+        for alternatives in tokens
+        if any(alt.lower() in lowered for alt in alternatives)
+    )
+    return matched / len(tokens)
+
+
+def _verdict_for_surface(
+    surface_path: str,
+    body: str,
+    fixture_text: str | None,
+) -> tuple[SurfaceVerdict, Finding | None]:
+    """Score one surface; return its verdict and any finding."""
+    if fixture_text and fixture_text in body:
+        verdict = SurfaceVerdict(
+            surface=surface_path, mode="byte-exact", coverage=1.0, admitted=True
+        )
+        return verdict, None
+    coverage = _coverage(body, CANONICAL_TOKENS)
+    admitted = coverage >= COVERAGE_FLOOR
+    verdict = SurfaceVerdict(
+        surface=surface_path,
+        mode="paraphrase",
+        coverage=round(coverage, 3),
+        admitted=admitted,
+    )
+    if admitted:
+        return verdict, None
+    finding = Finding(
+        surface=surface_path,
+        detail=(
+            f"plans-discipline language insufficient: coverage "
+            f"{coverage:.2f} < floor {COVERAGE_FLOOR:.2f} and "
+            f"byte-exact fixture absent"
+        ),
+        coverage=round(coverage, 3),
+    )
+    return verdict, finding
+
+
+def check(root: Path) -> GrepResult:
+    """Sweep the four required surfaces under root for the directive."""
+    fixture_text = _read_fixture(root)
+    fixture_present = fixture_text is not None
+    verdicts: list[SurfaceVerdict] = []
+    findings: list[Finding] = []
+    if not fixture_present:
+        findings.append(
+            Finding(
+                surface=FIXTURE_PATH,
+                detail=(
+                    "byte-exact fixture absent at canonical path; "
+                    "byte-exact admission disabled for every surface"
+                ),
+                coverage=0.0,
+            )
+        )
+    for surface_path in REQUIRED_SURFACES:
+        full_path = root / surface_path
+        if not full_path.exists():
+            verdicts.append(
+                SurfaceVerdict(
+                    surface=surface_path,
+                    mode="absent",
+                    coverage=0.0,
+                    admitted=False,
+                )
+            )
+            findings.append(
+                Finding(
+                    surface=surface_path,
+                    detail="surface file absent at canonical path",
+                    coverage=0.0,
+                )
+            )
+            continue
+        body = full_path.read_text(encoding="utf-8")
+        verdict, finding = _verdict_for_surface(surface_path, body, fixture_text)
+        verdicts.append(verdict)
+        if finding is not None:
+            findings.append(finding)
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        fixture_present=fixture_present,
+        surfaces=verdicts,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> Path:
+    if len(argv) >= 2:
+        return Path(argv[1])
+    return Path.cwd()
+
+
+def _main(argv: list[str]) -> int:
+    root = _read_input(argv)
+    result = check(root)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))

package/src/apothem/conformity/production_ready_pr_grep.py

@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag commits whose change-set lacks the production-ready four-class shape.
+
+Why this enforcement exists. The production-ready discipline M15 requires
+every change touching public surface to ship in the same change-set with
+tests, documentation, and a CHANGELOG entry. A code change without its
+companions persists as half-finished — the follow-up never lands; the
+release notes lie. The pre-emission gate's mechanical bar 15 (M15 production-ready) catches
+change-sets where public-surface code was modified but the companion
+classes (tests / docs / CHANGELOG) are absent or trivially populated.
+
+Detection strategy. The grep inspects the staged diff via `git diff
+--cached --name-only` and classifies every touched file into one of
+four classes (code, tests, docs, changelog). When code-class files are
+touched, the grep verifies at least one tests-class and at least one
+docs-class file is also touched, plus the changelog-class file is
+present in the change-set. Per-file invocation is a soft pass — the
+grep operates at change-set granularity rather than per-file, so the
+orchestrator's per-Write dispatch returns clean and the CLI mode
+performs the substantive check.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+# Per-class path patterns. Patterns are inclusive — a file matching
+# multiple patterns counts toward every class it matches.
+CODE_PATTERNS: Final[tuple[re.Pattern[str], ...]] = (
+    re.compile(r"^src/.+\.(?:py|ts|js|go|rs|rb|java|kt|swift)$"),
+    re.compile(r"^lib/.+\.(?:py|ts|js|go|rs)$"),
+    re.compile(r"^(?:rules|commands|agents|skills|hooks|tools)/.+\.(?:py|md)$"),
+)
+TEST_PATTERNS: Final[tuple[re.Pattern[str], ...]] = (
+    re.compile(r"^tests?/.+"),
+    re.compile(r".+/test_[A-Za-z0-9_]+\.py$"),
+    re.compile(r".+_test\.(?:py|go|rs)$"),
+    re.compile(r".+\.test\.(?:ts|js)$"),
+)
+DOCS_PATTERNS: Final[tuple[re.Pattern[str], ...]] = (
+    re.compile(r"^docs?/.+"),
+    re.compile(r"^README\.md$"),
+    re.compile(r"^CONTRIBUTING\.md$"),
+)
+CHANGELOG_PATTERNS: Final[tuple[re.Pattern[str], ...]] = (
+    re.compile(r"^CHANGELOG\.md$"),
+    re.compile(r"^CHANGES(?:\.md)?$"),
+    re.compile(r"^HISTORY\.md$"),
+)
+
+# Per-file invocation mode: when the grep is dispatched against a
+# single file (orchestrator's PreToolUse path), return PASS without
+# inspecting git. The substantive check fires at commit-time CLI use.
+PER_FILE_PASS_MODE: Final[bool] = True
+
+GREP_NAME: Final[str] = "production-ready-pr-grep"
+RULE_ANCHOR: Final[str] = "M15 production-ready §Same-change-set"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+STAGED_FLAG: Final[str] = "--staged"
+
+# Subprocess timeout for the git invocation; the per-grep budget is
+# `gate.PER_GREP_BUDGET_SECONDS` (~520ms) but the staged-diff check is a
+# single git command that completes well under that ceiling on
+# representative repositories.
+GIT_TIMEOUT_SECONDS: Final[int] = 5
+
+
+@dataclass(frozen=True)
+class Finding:
+    issue: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    grep: str
+    path: str | None
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "path": self.path,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _classify(path: str) -> set[str]:
+    """Return the set of class labels the path matches."""
+    classes: set[str] = set()
+    if any(p.match(path) for p in CODE_PATTERNS):
+        classes.add("code")
+    if any(p.match(path) for p in TEST_PATTERNS):
+        classes.add("tests")
+    if any(p.match(path) for p in DOCS_PATTERNS):
+        classes.add("docs")
+    if any(p.match(path) for p in CHANGELOG_PATTERNS):
+        classes.add("changelog")
+    return classes
+
+
+def _staged_paths() -> list[str]:
+    """Return the staged-diff path list via git; empty on failure."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--cached", "--name-only"],  # noqa: S607  # PATH-resolved git is acceptable for a developer-tool grep; full-path resolution would require host-discovery and breaks portability across operator setups.
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=GIT_TIMEOUT_SECONDS,
+        )
+    except (
+        subprocess.CalledProcessError,
+        subprocess.TimeoutExpired,
+        FileNotFoundError,
+    ):
+        return []
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def _check_staged() -> GrepResult:
+    """Substantive check: inspect the staged diff against the four-class shape."""
+    paths = _staged_paths()
+    classes_present: set[str] = set()
+    for path in paths:
+        classes_present |= _classify(path)
+    findings: list[Finding] = []
+    if "code" in classes_present:
+        if "tests" not in classes_present:
+            findings.append(
+                Finding(
+                    issue="missing tests-class file",
+                    detail="code-class file modified; no tests/* file in the change-set",
+                )
+            )
+        if "docs" not in classes_present:
+            findings.append(
+                Finding(
+                    issue="missing docs-class file",
+                    detail="code-class file modified; no docs/* / README / CONTRIBUTING in the change-set",
+                )
+            )
+        if "changelog" not in classes_present:
+            findings.append(
+                Finding(
+                    issue="missing CHANGELOG entry",
+                    detail="code-class file modified; CHANGELOG.md is not part of the change-set",
+                )
+            )
+    return GrepResult(
+        grep=GREP_NAME,
+        path="<staged diff>",
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Per-file mode returns PASS; the substantive check fires via --staged."""
+    if PER_FILE_PASS_MODE:
+        return GrepResult(
+            grep=GREP_NAME,
+            path=str(path) if path is not None else None,
+            passed=True,
+        )
+    return _check_staged()
+
+
+def _read_input(argv: list[str]) -> tuple[str, Path | None]:
+    if len(argv) >= 2 and argv[1] != STDIN_FLAG:
+        path = Path(argv[1])
+        return path.read_text(encoding="utf-8"), path
+    return sys.stdin.read(), None
+
+
+def _main(argv: list[str]) -> int:
+    if len(argv) >= 2 and argv[1] == STAGED_FLAG:
+        result = _check_staged()
+    else:
+        content, path = _read_input(argv)
+        result = check(content, path)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))

package/src/apothem/conformity/recommend_next_step_grep.py

@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify every command file carries a `## Recommended Next Step` block.
+
+Why this enforcement exists. Per `rules/recommend-next-step.md`, every
+`commands/*.md` artifact terminates its working trace with a
+Recommended-Next-Step block so the operator's onward path is named at
+the close of every command. The block lands in one of two canonical
+forms: the singular `## Recommended Next Step` heading followed by
+substantive prose, or the multi-action `## Next Steps` heading whose
+option list carries exactly one `**Recommended**` marker.
+
+Detection strategy. The validator walks two terminal-surface classes —
+`src/apothem/commands/*.md` (excluding `README.md` — the command-class
+index is not itself a command) and `src/apothem/skills/*/SKILL.md` — to
+match the rule's declared command-and-skill scope. For each surface it
+locates either of the two heading forms; absence is a finding. For the
+singular form the validator verifies the heading is followed by at least
+one non-empty prose line. For the multi-action form the validator counts
+`**Recommended**` markers between the heading and the next sibling H2 (or
+end of file); exactly one is admissible. Zero or two-plus markers is a
+finding.
+
+Exit semantics. Exits 0 when every command file passes; exits 2 on any
+finding. The exit-2 convention matches the conformity-gate
+orchestrator's EXIT_FAIL constant.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+GREP_NAME: Final[str] = "recommend-next-step-grep"
+RULE_ANCHOR: Final[str] = "rules/recommend-next-step.md"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+# Terminal-surface roots relative to the repository root supplied at invocation.
+COMMANDS_DIR: Final[str] = "src/apothem/commands"
+SKILLS_DIR: Final[str] = "src/apothem/skills"
+
+# Filenames excluded from the sweep — folder-companion docs, not commands:
+# the human-facing directory index and the agent-facing companion.
+EXCLUDED_FILES: Final[frozenset[str]] = frozenset({"README.md", "AGENTS.md"})
+
+# Heading patterns. The singular form is the dominant convention; the
+# multi-action `## Next Steps` form is admissible when the command's
+# close branches across several options.
+SINGULAR_HEADING_RE: Final[re.Pattern[str]] = re.compile(
+    r"^##\s+Recommended\s+Next\s+Step\s*$"
+)
+MULTI_HEADING_RE: Final[re.Pattern[str]] = re.compile(r"^##\s+Next\s+Steps\s*$")
+
+# Any H2 heading — used to scope the multi-action block's option list to
+# the region between its own heading and the next sibling H2.
+ANY_H2_RE: Final[re.Pattern[str]] = re.compile(r"^##\s+\S")
+
+# Recommended marker. The convention is the literal `**Recommended**`
+# bolded token, matching the canonical option-annotation discipline.
+RECOMMENDED_MARKER_RE: Final[re.Pattern[str]] = re.compile(r"\*\*Recommended\*\*")
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One command file that lacks a valid Recommended-Next-Step block."""
+
+    surface: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    """Aggregated sweep result across every command file."""
+
+    grep: str
+    root: str
+    files_inspected: int
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "files_inspected": self.files_inspected,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _has_substantive_prose(lines: list[str], start_index: int) -> bool:
+    """Return True iff at least one non-empty prose line follows the heading.
+
+    The scan stops at the next H2 (sibling heading) or end of file.
+    Empty lines, whitespace-only lines, and HTML-comment lines do not
+    count as substantive content.
+    """
+    for line in lines[start_index + 1 :]:
+        if ANY_H2_RE.match(line):
+            return False
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("<!--") or stripped.startswith("-->"):
+            continue
+        return True
+    return False
+
+
+def _count_recommended_markers(lines: list[str], start_index: int) -> int:
+    """Count `**Recommended**` markers between heading and next H2."""
+    count = 0
+    for line in lines[start_index + 1 :]:
+        if ANY_H2_RE.match(line):
+            break
+        count += len(RECOMMENDED_MARKER_RE.findall(line))
+    return count
+
+
+def _classify_command_file(path: Path) -> Finding | None:
+    """Return a finding when the command file lacks a valid block."""
+    try:
+        body = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return Finding(
+            surface=str(path),
+            detail=f"could not read command file: {exc}",
+        )
+    lines = body.splitlines()
+    singular_index = next(
+        (i for i, line in enumerate(lines) if SINGULAR_HEADING_RE.match(line)),
+        None,
+    )
+    multi_index = next(
+        (i for i, line in enumerate(lines) if MULTI_HEADING_RE.match(line)),
+        None,
+    )
+    if singular_index is None and multi_index is None:
+        return Finding(
+            surface=str(path),
+            detail=(
+                "no `## Recommended Next Step` or `## Next Steps` heading "
+                "found; the command must close with the canonical block"
+            ),
+        )
+    if singular_index is not None:
+        if not _has_substantive_prose(lines, singular_index):
+            return Finding(
+                surface=str(path),
+                detail=(
+                    "`## Recommended Next Step` heading present but block is "
+                    "empty; the canonical form carries at least one prose line"
+                ),
+            )
+        return None
+    # Multi-action form: verify exactly one Recommended marker.
+    # singular_index is None here (else returned above) and not both were None,
+    # so multi_index is necessarily set; the guard narrows the type and is
+    # unreachable in practice.
+    if multi_index is None:  # pragma: no cover
+        return None
+    marker_count = _count_recommended_markers(lines, multi_index)
+    if marker_count == 0:
+        return Finding(
+            surface=str(path),
+            detail=(
+                "`## Next Steps` block carries zero `**Recommended**` markers; "
+                "the multi-action form requires exactly one"
+            ),
+        )
+    if marker_count > 1:
+        return Finding(
+            surface=str(path),
+            detail=(
+                f"`## Next Steps` block carries {marker_count} `**Recommended**` "
+                f"markers; the multi-action form admits exactly one"
+            ),
+        )
+    return None
+
+
+def check(root: Path) -> GrepResult:
+    """Sweep every command and skill surface under root for the block."""
+    findings: list[Finding] = []
+    files_inspected = 0
+
+    commands_dir = root / COMMANDS_DIR
+    if not commands_dir.is_dir():
+        findings.append(
+            Finding(
+                surface=COMMANDS_DIR,
+                detail=(f"commands directory absent at canonical path {commands_dir}"),
+            )
+        )
+    else:
+        for path in sorted(commands_dir.glob("*.md")):
+            if path.name in EXCLUDED_FILES:
+                continue
+            files_inspected += 1
+            finding = _classify_command_file(path)
+            if finding is not None:
+                findings.append(finding)
+
+    skills_dir = root / SKILLS_DIR
+    if not skills_dir.is_dir():
+        findings.append(
+            Finding(
+                surface=SKILLS_DIR,
+                detail=(f"skills directory absent at canonical path {skills_dir}"),
+            )
+        )
+    else:
+        for path in sorted(skills_dir.glob("*/SKILL.md")):
+            files_inspected += 1
+            finding = _classify_command_file(path)
+            if finding is not None:
+                findings.append(finding)
+
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        files_inspected=files_inspected,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> Path:
+    if len(argv) >= 2:
+        return Path(argv[1])
+    return Path.cwd()
+
+
+def _main(argv: list[str]) -> int:
+    root = _read_input(argv)
+    result = check(root)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))