@ahmed-g-gad/apothem 0.1.1

package/src/apothem/audit/scan_plans_discipline.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: MIT
+
+"""Detect references to a global user-scope plans directory as a write target.
+
+Why this scan exists. The harness-agnostic plans discipline forbids any
+agent from writing plan artifacts to a global user-config root in any
+host project — plans belong under ``<project-root>/.plans/``. For the
+Claude Code harness specifically, the user-config root carries an
+unfortunate recursion: the apothem plan-suite itself lives under
+``~/.claude/.plans/`` during authoring, while the discipline being
+installed forbids any agent from writing to that path in any host
+project. The recursion is resolved by gitignoring the suite folder
+once the migration is complete; before that, every directive that
+points an agent at ``~/.claude/.plans/...`` (or any other harness's
+global plans path) as a WRITE target is a discipline violation that
+the refit phases need to remove. Read-references inside the discipline
+documentation (rules, site docs, plan-suite specs) are exempt because they
+describe the discipline itself.
+
+What this scan covers per finding. Lines mentioning
+``~/.claude/.plans/``, ``$CLAUDE_PROJECT_DIR/.plans/``, or equivalent
+global-plans path variants in a directive context. The scan flags
+write-intent verbs adjacent to the path (``write to``, ``create at``,
+``store under``, ``save to``, ``emit at``, ``land at``) as HIGH
+severity; bare references without write intent are flagged at MEDIUM
+because the operator may be using the path as a documentation pointer.
+
+What this scan excludes. Lines inside fenced code blocks (which
+document, rather than direct, the path). Files explicitly classified
+as discipline documentation (``src/apothem/rules/persistent-conventions-vigilance``,
+``site/content/docs/reference/plans-discipline.mdx``, the plan-suite specs themselves) are
+walked but their hits carry an ``is-discipline-doc`` flag in the extra
+field so the synthesis pass can rank them lower.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Any, Final
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _scan_lib import (
+    CONTENT_ROOT,
+    NARRATIVE_CLASSES,
+    SEVERITY_HIGH,
+    SEVERITY_MEDIUM,
+    Hit,
+    emit_json,
+    load_inventory,
+    read_text_safely,
+)
+
+# Path patterns that indicate a reference to the user-scope plans dir.
+_PLANS_PATH_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?:~/\.claude/\.plans/|\$HOME/\.claude/\.plans/|\$CLAUDE_PROJECT_DIR/\.plans/"
+    r"|%USERPROFILE%[\\/]\.claude[\\/]\.plans[\\/])",
+    re.IGNORECASE,
+)
+
+# Verbs that indicate a write-intent directive — adjacency raises the
+# severity classification.
+_WRITE_INTENT_RE: Final[re.Pattern[str]] = re.compile(
+    r"\b(?:write|writes|writing|create|creates|creating|store|stores|"
+    r"storing|save|saves|saving|emit|emits|emitting|land|lands|"
+    r"landing|generate|generates|generating|persist|persists|persisting|"
+    r"output|outputs|outputting|append|appends|appending|materialize|"
+    r"materializes|materializing|materialize|materializes|materializing"
+    r")\b",
+    re.IGNORECASE,
+)
+
+# Files whose entire purpose is to document the plans-discipline; their
+# references are read-targets, not write-targets, but the scan still
+# flags them so the synthesis pass can decide. Paths are content-root-
+# relative to match the inventory's record paths (the inventory is built
+# with the content root as --root, so its paths carry bare top-level
+# prefixes — `rules/...`, not `src/apothem/rules/...`). Surfaces outside
+# the content root (`site/`, the repo-root `CLAUDE.md`) are not in the
+# inventory and so never reach this scan; they are retained here only as
+# an intent record for the day the scan scope widens.
+_DISCIPLINE_DOC_PATHS: Final[frozenset[str]] = frozenset(
+    {
+        "rules/persistent-conventions-vigilance.md",
+        "site/content/docs/reference/plans-discipline.mdx",
+        "CLAUDE.md",
+    }
+)
+
+
+def _is_discipline_doc(rel: str) -> bool:
+    return rel in _DISCIPLINE_DOC_PATHS or rel.startswith(".plans/")
+
+
+def _scan_file(rel: str, content: str) -> list[Hit]:
+    """Walk a single narrative artifact for plans-discipline hits."""
+    hits: list[Hit] = []
+    in_fence = False
+    is_doc = _is_discipline_doc(rel)
+    for lineno, line in enumerate(content.splitlines(), start=1):
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        if not _PLANS_PATH_RE.search(line):
+            continue
+        write_intent = bool(_WRITE_INTENT_RE.search(line))
+        severity = SEVERITY_HIGH if write_intent else SEVERITY_MEDIUM
+        kind = "plans-write-target" if write_intent else "plans-path-reference"
+        hits.append(
+            Hit(
+                file=rel,
+                line=lineno,
+                signal=f"{kind}: {line.strip()[:120]}",
+                severity=severity,
+                remediation=(
+                    "Replace the user-scope plans path with a"
+                    " host-project-relative path (e.g.,"
+                    " '<project>/.plans/'); the discipline forbids the"
+                    " ecosystem from emitting plan artifacts under the"
+                    " user-config root."
+                ),
+                extra={"is-discipline-doc": is_doc},
+            )
+        )
+    return hits
+
+
+def _scan_record(record: dict[str, Any], root: Path) -> list[Hit]:
+    """Run the plans-discipline scan against one inventory record."""
+    cls = record.get("class", "")
+    if cls not in NARRATIVE_CLASSES:
+        return []
+    rel = record["path"]
+    path = root / rel
+    content = read_text_safely(path)
+    if not content:
+        return []
+    return _scan_file(rel, content)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--inventory",
+        type=Path,
+        default=Path(".audit/inventory.json"),
+    )
+    parser.add_argument("--root", type=Path, default=CONTENT_ROOT)
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path(".audit/drift-plans-discipline.json"),
+    )
+    args = parser.parse_args(argv)
+
+    if not args.inventory.exists():
+        print(
+            f"error: inventory not found at {args.inventory}",
+            file=sys.stderr,
+        )
+        return 1
+
+    records, sha = load_inventory(args.inventory)
+    hits: list[Hit] = []
+    for record in records:
+        hits.extend(_scan_record(record, args.root))
+    emit_json(args.output, "scan_plans_discipline", hits, sha)
+    by_signal: dict[str, int] = {}
+    for h in hits:
+        kind = h.signal.split(":", 1)[0]
+        by_signal[kind] = by_signal.get(kind, 0) + 1
+    summary = ", ".join(f"{k}={v}" for k, v in sorted(by_signal.items()))
+    discipline_doc_share = sum(1 for h in hits if h.extra.get("is-discipline-doc"))
+    print(
+        f"scan_plans_discipline: {len(hits)} hit(s) "
+        f"[{summary or 'none'}]; discipline-doc context: "
+        f"{discipline_doc_share}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/audit/scan_secrets_pii.py

@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: MIT
+
+"""Detect secrets, PII tokens, and host-specific absolute paths.
+
+Why this scan exists. Three risks live in the same scan because they
+share the same enforcement surface (a pre-commit / pre-emission gate)
+and the same scope (every text file in the working tree, not just the
+narrative subset). A leaked secret is a credential breach. A PII token
+embedded in narrative violates the canonical-banner allow-list and may
+expose contact data outside the operator's intent. An absolute path
+naming the operator's home directory or username binds the artifact to
+a single machine and breaks portability across operator hosts.
+
+What this scan covers per finding.
+
+- **Secret patterns.** API keys (AWS / GitHub / Stripe / Slack / generic
+  PEM blocks / OpenAI / Anthropic). Pattern set is curated per
+  upstream-vendor token shapes; any literal occurrence is HIGH severity.
+- **PII tokens.** Email addresses, full-name candidates flagged via
+  ``\\b[A-Z][a-z]+ [A-Z][a-z]+\\b`` (heuristic; high false-positive),
+  phone-like sequences. Banner-allowed contacts (canonical email,
+  website, GitHub handle) are exempt via the byte-exact banner-line
+  match.
+- **Absolute home paths.** ``/Users/<name>/`` (macOS), ``/home/<name>/``
+  (Linux), ``C:\\\\Users\\\\<name>\\\\`` (Windows). The operator's actual
+  username is detected by reading the canonical banner once at scan
+  start and used as the comparison anchor; non-operator usernames in
+  test fixtures are also flagged separately because they bind the
+  artifact to that specific test scenario.
+
+What this scan excludes. Memory and plan-artifact records are walked
+for absolute-path detection (a plan-artifact referencing the operator's
+home leaks the operator's username if the plan is shared) but excluded
+from secret scanning (per-project memory may legitimately reference
+host-specific tokens that never leave the project's own boundary).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Any, Final
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _scan_lib import (
+    CONTENT_ROOT,
+    NARRATIVE_CLASSES,
+    SEVERITY_HIGH,
+    SEVERITY_LOW,
+    SEVERITY_MEDIUM,
+    Hit,
+    emit_json,
+    load_inventory,
+    read_text_safely,
+)
+
+# Banner contacts that are explicitly allow-listed for PII detection.
+# The byte-exact banner content is treated as the canonical disclosure
+# surface; matching tokens elsewhere outside the banner are still
+# flagged as candidates for review.
+BANNER_EMAIL: Final[str] = "me@ahmedgad.com"
+BANNER_WEBSITE: Final[str] = "ahmedgad.com"
+BANNER_GITHUB_HANDLE: Final[str] = "ahmed-g-gad"
+BANNER_NAME: Final[str] = "Ahmed G. Gad"
+BANNER_USERNAME: Final[str] = "Gad"
+
+# Secret-pattern catalog. Each entry is a (label, regex) pair. The
+# regexes are intentionally narrow to limit false positives; broader
+# scanning is the gitleaks pre-commit hook's job at the hook-install
+# pass.
+_SECRET_PATTERNS: Final[list[tuple[str, re.Pattern[str]]]] = [
+    ("aws-access-key-id", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("aws-secret-access-key", re.compile(r"\b[A-Za-z0-9/+=]{40}\b(?=.{0,80}aws)")),
+    ("github-pat", re.compile(r"\bgh[pousr]_[A-Za-z0-9_]{36,}\b")),
+    ("anthropic-api-key", re.compile(r"\bsk-ant-[A-Za-z0-9-_]{30,}\b")),
+    ("openai-api-key", re.compile(r"\bsk-[A-Za-z0-9]{32,}\b")),
+    ("slack-token", re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b")),
+    ("stripe-key", re.compile(r"\b(?:sk|pk)_(?:test|live)_[0-9a-zA-Z]{24,}\b")),
+    (
+        "private-key-block",
+        re.compile(r"-----BEGIN (?:RSA|EC|OPENSSH|DSA|PRIVATE) KEY-----"),
+    ),
+    (
+        "generic-bearer-token",
+        re.compile(
+            r"\b(?:bearer|token|api[_-]?key|secret)\s*[:=]\s*[\"']?[A-Za-z0-9_-]{24,}[\"']?",
+            re.IGNORECASE,
+        ),
+    ),
+]
+
+# Absolute-path patterns. The operator's actual username is interpolated
+# at scan time so non-operator usernames in test fixtures show up as a
+# distinct (lower-severity) class.
+_PATH_USERS_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?<![\w/])(?:/Users/|/home/|[A-Z]:[\\/]Users[\\/])(?P<user>[A-Za-z0-9._-]+)[/\\]"
+)
+
+# Email pattern matching anywhere; the BANNER_EMAIL is allow-listed.
+_EMAIL_RE: Final[re.Pattern[str]] = re.compile(
+    r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"
+)
+
+
+def _scan_secrets(rel: str, content: str) -> list[Hit]:
+    """Walk content for secret-pattern matches."""
+    hits: list[Hit] = []
+    for lineno, line in enumerate(content.splitlines(), start=1):
+        for label, pattern in _SECRET_PATTERNS:
+            if pattern.search(line):
+                hits.append(
+                    Hit(
+                        file=rel,
+                        line=lineno,
+                        signal=f"secret-candidate: {label}",
+                        severity=SEVERITY_HIGH,
+                        remediation=(
+                            "Treat as a credential leak: rotate the secret"
+                            " upstream, remove the literal from the working"
+                            " tree, and verify git-history removal before"
+                            " any push to a remote."
+                        ),
+                    )
+                )
+                break  # one finding per line is enough
+    return hits
+
+
+def _scan_pii(rel: str, content: str) -> list[Hit]:
+    """Walk content for non-banner email occurrences."""
+    hits: list[Hit] = []
+    for lineno, line in enumerate(content.splitlines(), start=1):
+        for match in _EMAIL_RE.finditer(line):
+            email = match.group(0)
+            if email == BANNER_EMAIL:
+                continue
+            hits.append(
+                Hit(
+                    file=rel,
+                    line=lineno,
+                    signal=f"non-banner-email: {email}",
+                    severity=SEVERITY_MEDIUM,
+                    remediation=(
+                        "Replace with a vendor-neutral placeholder"
+                        " (example.com), the canonical banner email, or"
+                        " remove the contact data if not load-bearing."
+                    ),
+                )
+            )
+    return hits
+
+
+def _scan_paths(rel: str, content: str) -> list[Hit]:
+    """Walk content for absolute home-directory paths."""
+    hits: list[Hit] = []
+    for lineno, line in enumerate(content.splitlines(), start=1):
+        for match in _PATH_USERS_RE.finditer(line):
+            user = match.group("user")
+            severity = SEVERITY_MEDIUM if user == BANNER_USERNAME else SEVERITY_LOW
+            sig_kind = (
+                "operator-home-path"
+                if user == BANNER_USERNAME
+                else "non-operator-home-path"
+            )
+            hits.append(
+                Hit(
+                    file=rel,
+                    line=lineno,
+                    signal=f"{sig_kind}: {match.group(0)}",
+                    severity=severity,
+                    remediation=(
+                        "Replace the absolute path with a portable form"
+                        " (~/, $HOME, %USERPROFILE%, or the host-discovered"
+                        " environment variable that names the home root)."
+                    ),
+                )
+            )
+    return hits
+
+
+def _scan_record(record: dict[str, Any], root: Path) -> list[Hit]:
+    """Run all three scans against one inventory record.
+
+    All three scans (secrets, PII, paths) are restricted to narrative
+    classes. Memory JSONL session logs and plan-artifact files bind
+    per-machine state by design — flagging them as portability concerns
+    would generate noise that obscures the real findings in narrative
+    artifacts that DO get shared across hosts.
+    """
+    cls = record.get("class", "")
+    if cls not in NARRATIVE_CLASSES:
+        return []
+    rel = record["path"]
+    path = root / rel
+    content = read_text_safely(path)
+    if not content:
+        return []
+    hits: list[Hit] = []
+    hits.extend(_scan_secrets(rel, content))
+    hits.extend(_scan_pii(rel, content))
+    hits.extend(_scan_paths(rel, content))
+    return hits
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--inventory",
+        type=Path,
+        default=Path(".audit/inventory.json"),
+    )
+    parser.add_argument("--root", type=Path, default=CONTENT_ROOT)
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path(".audit/drift-secrets-pii.json"),
+    )
+    args = parser.parse_args(argv)
+
+    if not args.inventory.exists():
+        print(
+            f"error: inventory not found at {args.inventory}",
+            file=sys.stderr,
+        )
+        return 1
+
+    records, sha = load_inventory(args.inventory)
+    hits: list[Hit] = []
+    for record in records:
+        hits.extend(_scan_record(record, args.root))
+    emit_json(args.output, "scan_secrets_pii", hits, sha)
+    by_signal: dict[str, int] = {}
+    for h in hits:
+        kind = h.signal.split(":", 1)[0]
+        by_signal[kind] = by_signal.get(kind, 0) + 1
+    summary = ", ".join(f"{k}={v}" for k, v in sorted(by_signal.items()))
+    print(f"scan_secrets_pii: {len(hits)} hit(s) [{summary or 'none'}]")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())