project-init 0.3.0__py3-none-any.whl

project_init/templates/base/dot_claude/hooks/dag_workflow.py

@@ -0,0 +1,610 @@
+#!/usr/bin/env python3
+"""DAG-based workflow enforcement for the GitHub lifecycle.
+
+Subcommands:
+  check <node>          exit 0 if every prerequisite of <node> is satisfied,
+                        exit 2 otherwise (with reason on stdout).
+  guard                 read PreToolUse hook input JSON from stdin, map the
+                        Bash command to a target node, emit
+                        {decision: block, reason: ...} if disallowed.
+  nodes                 list every DAG node and its prerequisites.
+  push [<branch>] [N]   push current (or named) branch with retry + remote-SHA
+                        verification (handles transient GitHub 5xx).
+  promote [<pr>]        mark current (or numbered) draft PR ready for review.
+  finish [<pr>] [--review-cycle N]
+                        push, promote, then exec monitor_pr.sh --merge.
+  create-pr-nojira <type> <title> [--branch B] [--base B]
+                        create a no-issue feature branch + draft PR.
+
+The `check` and `guard` paths are pure read-only; they're used by hooks and
+lifecycle scripts. The other subcommands consolidate the bash lifecycle
+scripts (push_branch.sh, promote_review.sh, finish_pr.sh,
+create_nojira_pr.sh) so the tool is the single source of truth for the
+GitHub workflow. The .sh files become thin shims that exec into here.
+
+Issue-ref prefix detection:
+  By default, branches matching `[A-Z]{2,}-<n>` (e.g. PI-98, ACME-42) are
+  treated as issue-backed. Override with the DAG_ISSUE_PREFIX env var to pin
+  a specific prefix (e.g. DAG_ISSUE_PREFIX=PROJ matches only `PROJ-<n>`).
+  Branches with no recognized prefix fall through to the no-jira flow.
+
+stdlib only.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+CACHE_PATH = Path(".claude/.workflow-state.json")
+
+GRAPH: dict[str, list[str]] = {
+    "issue.created": [],
+    "branch.created": [],
+    "branch.pushed": ["branch.created"],
+    "pr.opened": ["branch.pushed", "issue.created"],
+    "ci.green": ["pr.opened"],
+    "review.approved": ["pr.opened"],
+    "pr.merged": ["ci.green", "review.approved"],
+}
+
+_CONFIGURED_PREFIX = os.environ.get("DAG_ISSUE_PREFIX", "").strip()
+if _CONFIGURED_PREFIX:
+    ISSUE_RE: re.Pattern[str] = re.compile(
+        rf"\b{re.escape(_CONFIGURED_PREFIX)}-(\d+)\b", re.IGNORECASE
+    )
+else:
+    ISSUE_RE = re.compile(r"\b[A-Z]{2,}-(\d+)\b")
+
+
+def _run(cmd: list[str]) -> tuple[int, str]:
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return 1, ""
+    return proc.returncode, proc.stdout
+
+
+def _gh(args: list[str]) -> tuple[int, str]:
+    return _run(["gh", *args])
+
+
+def _git(args: list[str]) -> tuple[int, str]:
+    return _run(["git", *args])
+
+
+def _current_branch() -> str | None:
+    code, out = _git(["branch", "--show-current"])
+    branch = out.strip()
+    return branch if code == 0 and branch else None
+
+
+def _issue_from_branch(branch: str) -> int | None:
+    m = ISSUE_RE.search(branch)
+    return int(m.group(1)) if m else None
+
+
+def check_issue_created() -> tuple[bool, str]:
+    branch = _current_branch()
+    if not branch:
+        return False, "no current branch"
+    n = _issue_from_branch(branch)
+    if n is None:
+        return True, f"branch '{branch}' has no issue ref (no-jira flow allowed)"
+    code, out = _gh(["issue", "view", str(n), "--json", "number,state"])
+    if code != 0:
+        return False, f"issue #{n} not found via gh"
+    try:
+        data = json.loads(out or "{}")
+    except json.JSONDecodeError:
+        return False, f"issue #{n}: malformed gh output"
+    if data.get("number") != n:
+        return False, f"issue #{n} not present"
+    return True, f"issue #{n} exists ({data.get('state', 'UNKNOWN')})"
+
+
+def check_branch_created() -> tuple[bool, str]:
+    branch = _current_branch()
+    if not branch:
+        return False, "not in a git repo / no current branch"
+    if branch in {"main", "master"}:
+        return False, "must be on a feature branch, not main/master"
+    return True, f"on branch '{branch}'"
+
+
+def check_branch_pushed() -> tuple[bool, str]:
+    branch = _current_branch()
+    if not branch:
+        return False, "no current branch"
+    code, _ = _git(["rev-parse", "--verify", f"origin/{branch}"])
+    if code != 0:
+        return False, f"origin/{branch} does not exist (push the branch first)"
+    code, out = _git(["rev-list", "--count", f"origin/{branch}..HEAD"])
+    if code == 0 and out.strip() and out.strip() != "0":
+        return False, f"branch has {out.strip()} unpushed commit(s)"
+    return True, f"branch '{branch}' is pushed and up to date with origin"
+
+
+def check_pr_opened() -> tuple[bool, str]:
+    code, out = _gh(["pr", "view", "--json", "number,state"])
+    if code != 0:
+        return False, "no PR exists for the current branch"
+    try:
+        data = json.loads(out or "{}")
+    except json.JSONDecodeError:
+        return False, "malformed gh pr view output"
+    if data.get("state") != "OPEN":
+        return False, f"PR is {data.get('state', 'unknown')}, not OPEN"
+    return True, f"PR #{data.get('number')} is open"
+
+
+def check_ci_green() -> tuple[bool, str]:
+    code, out = _gh(["pr", "view", "--json", "number,statusCheckRollup"])
+    if code != 0:
+        return False, "cannot read PR / CI status"
+    try:
+        data = json.loads(out or "{}")
+    except json.JSONDecodeError:
+        return False, "malformed gh statusCheckRollup output"
+    n = data.get("number", "?")
+    rollup = data.get("statusCheckRollup") or []
+    pending = failing = 0
+    for entry in rollup:
+        name = (entry.get("name") or entry.get("context") or "").lower()
+        if "review/decision" in name:
+            continue
+        status = (entry.get("status") or "").upper()
+        conclusion = (entry.get("conclusion") or "").upper()
+        if conclusion in {"FAILURE", "TIMED_OUT", "CANCELLED", "ERROR", "ACTION_REQUIRED"}:
+            failing += 1
+        elif status in {"PENDING", "QUEUED", "IN_PROGRESS", "WAITING"} or (
+            not conclusion and not status
+        ):
+            pending += 1
+    if failing:
+        return False, f"PR #{n}: {failing} CI check(s) failing"
+    if pending:
+        return False, f"PR #{n}: {pending} CI check(s) still running"
+    return True, f"PR #{n}: CI green"
+
+
+def check_review_approved() -> tuple[bool, str]:
+    code, out = _gh(["pr", "view", "--json", "number,reviewDecision"])
+    if code != 0:
+        return False, "cannot read PR review decision"
+    try:
+        data = json.loads(out or "{}")
+    except json.JSONDecodeError:
+        return False, "malformed gh reviewDecision output"
+    n = data.get("number", "?")
+    decision = data.get("reviewDecision") or ""
+    if decision == "APPROVED":
+        return True, f"PR #{n}: review approved"
+    if decision == "CHANGES_REQUESTED":
+        return False, f"PR #{n}: review requested changes"
+    return False, f"PR #{n}: review pending (decision={decision or 'none'})"
+
+
+def check_pr_merged() -> tuple[bool, str]:
+    code, out = _gh(["pr", "view", "--json", "number,state"])
+    if code != 0:
+        return False, "no PR for current branch"
+    try:
+        data = json.loads(out or "{}")
+    except json.JSONDecodeError:
+        return False, "malformed gh output"
+    if data.get("state") == "MERGED":
+        return True, f"PR #{data.get('number')} is merged"
+    return False, f"PR #{data.get('number')} state is {data.get('state')}"
+
+
+CHECKS = {
+    "issue.created": check_issue_created,
+    "branch.created": check_branch_created,
+    "branch.pushed": check_branch_pushed,
+    "pr.opened": check_pr_opened,
+    "ci.green": check_ci_green,
+    "review.approved": check_review_approved,
+    "pr.merged": check_pr_merged,
+}
+
+
+def prereqs_satisfied(node: str, _seen: set[str] | None = None) -> tuple[bool, str]:
+    """Walk all ancestors of `node` and return (True, '') if every prereq passes,
+    else (False, '<first failing prereq>: <reason>').
+    """
+    if node not in GRAPH:
+        return False, f"unknown node: {node}"
+    seen = _seen if _seen is not None else set()
+    if node in seen:
+        return True, ""
+    seen.add(node)
+    for prereq in GRAPH[node]:
+        ok, reason = CHECKS[prereq]()
+        if not ok:
+            return False, f"{prereq}: {reason}"
+        ok, reason = prereqs_satisfied(prereq, seen)
+        if not ok:
+            return False, reason
+    return True, "all prerequisites satisfied"
+
+
+# Steering rules: command pattern -> (target_node | None, redirect_message)
+# The first matching rule wins. target_node=None means a hard block with no
+# DAG validation; otherwise, prereqs of target_node are appended to the reason.
+COMMAND_RULES: list[tuple[re.Pattern[str], str | None, str]] = [
+    (
+        re.compile(r"git\s+push\s+(?:\S+\s+)?(?:origin\s+)?(?:main|master)\b"),
+        None,
+        "Direct pushes to main/master are blocked. Open a feature branch and PR.",
+    ),
+    (
+        re.compile(r"\bgh\s+api\s+repos/[^/\s]+/[^/\s]+/pulls/\d+/merge\b"),
+        "pr.merged",
+        "Use .claude/scripts/monitor_pr.sh <pr> --merge instead of `gh api .../merge` so CI and review gates are honored.",
+    ),
+    (
+        re.compile(r"\bgh\s+pr\s+merge\b"),
+        "pr.merged",
+        "Use .claude/scripts/monitor_pr.sh <pr> --merge instead of `gh pr merge` so CI, review waits, and review cycles are handled.",
+    ),
+    (
+        re.compile(r"\bgh\s+pr\s+checks\b.*--watch"),
+        None,
+        "Use .claude/scripts/monitor_pr.sh <pr> --merge instead of `gh pr checks --watch`.",
+    ),
+    (
+        re.compile(r"\bgh\s+pr\s+ready\b"),
+        "pr.opened",
+        "Use .claude/scripts/promote_review.sh instead of `gh pr ready`.",
+    ),
+    (
+        re.compile(r"\bgh\s+pr\s+create\b"),
+        "pr.opened",
+        "Use .claude/scripts/start_issue.sh (issue-backed) or .claude/scripts/create_nojira_pr.sh (no issue) instead of `gh pr create`.",
+    ),
+    (
+        re.compile(r"\bgh\s+issue\s+create\b"),
+        None,
+        "Use .claude/scripts/create_issue.sh (or the start_task skill) so priority, references, and acceptance criteria are captured.",
+    ),
+    (
+        re.compile(r"\bgit\s+push\b"),
+        "branch.pushed",
+        "Use .claude/scripts/push_branch.sh instead of raw `git push` so transient GitHub failures are retried and the remote SHA is verified.",
+    ),
+]
+
+
+_HEREDOC_RE = re.compile(
+    r"<<-?\s*['\"]?(\w+)['\"]?[ \t]*\n.*?\n\1[ \t]*(?:\n|$)",
+    re.DOTALL,
+)
+
+
+def _strip_heredocs(cmd: str) -> str:
+    """Remove heredoc body text so pattern rules don't fire on body content."""
+    return _HEREDOC_RE.sub("", cmd)
+
+
+def _redirect_target_exists(reason: str) -> bool:
+    """Best-effort: scan the redirect message for a `.claude/scripts/<name>`
+    reference and check whether the file exists. If no reference is found,
+    treat the rule as always-applicable (e.g. main/master block).
+    """
+    m = re.search(r"\.claude/scripts/([\w.-]+)", reason)
+    if not m:
+        return True
+    return (Path(".claude/scripts") / m.group(1)).exists()
+
+
+def guard(payload: dict) -> dict | None:
+    cmd = ((payload.get("tool_input") or {}).get("command") or "").strip()
+    if not cmd:
+        return None
+
+    # Strip heredoc bodies so pattern rules don't fire on body content
+    # (e.g. `gh issue create --body "$(cat <<'EOF'\n...git push...\nEOF\n)"`)
+    cmd_scan = _strip_heredocs(cmd)
+
+    for pattern, target, message in COMMAND_RULES:
+        if not pattern.search(cmd_scan):
+            continue
+        # If the redirect points at a wrapper script that doesn't exist in
+        # this repo, skip (don't block — there's nothing to redirect to).
+        if not _redirect_target_exists(message):
+            continue
+
+        reason = message
+        if target is not None:
+            ok, why = prereqs_satisfied(target)
+            if not ok:
+                reason = f"{message}\n\nDAG prerequisite for {target} not met: {why}."
+        return {"decision": "block", "reason": reason}
+    return None
+
+
+def cmd_check(node: str) -> int:
+    if node not in GRAPH:
+        sys.stdout.write(f"unknown node: {node}\n")
+        return 2
+    ok, reason = prereqs_satisfied(node)
+    if ok:
+        # Also report the node's own check, for human consumption.
+        own_ok, own_reason = CHECKS[node]()
+        marker = "OK" if own_ok else "REACHABLE (state not yet satisfied)"
+        sys.stdout.write(f"{marker}: {node} — {own_reason}\n")
+        return 0 if own_ok else 0  # prereqs satisfied = transition allowed
+    sys.stdout.write(f"BLOCKED: cannot reach {node}: {reason}\n")
+    return 2
+
+
+def cmd_guard() -> int:
+    raw = sys.stdin.read()
+    if not raw:
+        return 0
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return 0
+    result = guard(payload)
+    if result is not None:
+        sys.stdout.write(json.dumps(result))
+    return 0
+
+
+def _detect_pr_number() -> int | None:
+    code, out = _gh(["pr", "view", "--json", "number", "-q", ".number"])
+    if code != 0:
+        return None
+    try:
+        return int(out.strip())
+    except ValueError:
+        return None
+
+
+def cmd_push(branch: str | None, max_retries: int, *, force: bool = False) -> int:
+    """Push the current (or named) branch with retry + remote-SHA verification.
+
+    Handles transient GitHub 5xx where `git push` exits non-zero but the
+    commit actually landed on the remote. *force* adds --force-with-lease
+    for the rebase-after-squash-merge case; main/master are refused.
+    """
+    if branch is None:
+        branch = _current_branch()
+    if not branch:
+        sys.stderr.write("push: no current branch\n")
+        return 1
+    if force and branch in ("main", "master"):
+        sys.stderr.write("push: refusing to force-push main/master\n")
+        return 1
+
+    code, sha_out = _git(["rev-parse", branch])
+    if code != 0:
+        sys.stderr.write(f"push: cannot resolve sha for {branch}\n")
+        return 1
+    expected_sha = sha_out.strip()
+
+    def remote_has_sha() -> bool:
+        code, out = _git(["ls-remote", "origin", f"refs/heads/{branch}"])
+        if code != 0:
+            return False
+        for line in out.splitlines():
+            parts = line.split()
+            if parts and parts[0] == expected_sha:
+                return True
+        return False
+
+    for attempt in range(max_retries + 1):
+        push_cmd = ["git", "push", "-u", "origin", branch]
+        if force:
+            push_cmd.append("--force-with-lease")
+        proc = subprocess.run(push_cmd)
+        if proc.returncode == 0:
+            sys.stdout.write(f"push: pushed {branch} ({expected_sha})\n")
+            return 0
+        if remote_has_sha():
+            sys.stdout.write(
+                f"push: remote already has {expected_sha} on {branch} "
+                "(transient error, treating as success)\n"
+            )
+            _git(["branch", f"--set-upstream-to=origin/{branch}", branch])
+            return 0
+        if attempt < max_retries:
+            time.sleep(3)
+    sys.stderr.write(f"push: failed after {max_retries} retries\n")
+    return 1
+
+
+def cmd_promote(pr_number: int | None) -> int:
+    """Mark a draft PR ready for review."""
+    if pr_number is None:
+        pr_number = _detect_pr_number()
+    if pr_number is None:
+        sys.stderr.write(
+            "promote: no PR found for current branch. Pass a PR number.\n"
+        )
+        return 1
+    code, out = _gh(
+        ["pr", "view", str(pr_number), "--json", "isDraft", "-q", ".isDraft"]
+    )
+    if code != 0:
+        sys.stderr.write(f"promote: cannot read PR #{pr_number}\n")
+        return 1
+    if out.strip() == "false":
+        _, url = _gh(["pr", "view", str(pr_number), "--json", "url", "-q", ".url"])
+        sys.stdout.write(
+            f"PR #{pr_number} is already ready for review: {url.strip()}\n"
+        )
+        return 0
+    code, _ = _gh(["pr", "ready", str(pr_number)])
+    if code != 0:
+        sys.stderr.write(f"promote: gh pr ready failed for #{pr_number}\n")
+        return code
+    _, url = _gh(["pr", "view", str(pr_number), "--json", "url", "-q", ".url"])
+    sys.stdout.write(
+        f"PR #{pr_number} is now ready for review: {url.strip()}\n"
+    )
+    return 0
+
+
+def cmd_finish(pr_number: int | None, review_cycle: int | None) -> int:
+    """Push, promote, then hand off to monitor_pr.sh for CI/review/merge."""
+    rc = cmd_push(None, 3)
+    if rc != 0:
+        return rc
+    if pr_number is None:
+        pr_number = _detect_pr_number()
+    if pr_number is None:
+        sys.stderr.write("finish: no PR found for current branch.\n")
+        return 1
+    rc = cmd_promote(pr_number)
+    if rc != 0:
+        return rc
+    monitor_args = [".claude/scripts/monitor_pr.sh", str(pr_number), "--merge"]
+    if review_cycle is not None:
+        monitor_args += ["--review-cycle", str(review_cycle)]
+    return subprocess.run(monitor_args).returncode
+
+
+_VALID_TYPES = {"feat", "fix", "chore", "docs", "test"}
+_BRANCH_RE = re.compile(r"^(feat|fix|chore|docs|test)/[A-Za-z0-9._/-]+$")
+
+
+def _slugify(text: str) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", text.lower())
+    return s.strip("-")
+
+
+def cmd_create_pr_nojira(
+    type_: str, title: str, branch: str | None, base: str | None
+) -> int:
+    """Create a no-issue feature branch (if needed) and open a draft PR."""
+    if type_ not in _VALID_TYPES:
+        sys.stderr.write(
+            f"ERROR: invalid type '{type_}'. Valid: {' '.join(sorted(_VALID_TYPES))}\n"
+        )
+        return 1
+    if not title.strip():
+        sys.stderr.write("ERROR: title must not be empty\n")
+        return 1
+
+    current = _current_branch()
+    if not branch:
+        if current and current not in {"main", "master"}:
+            branch = current
+        else:
+            slug = _slugify(title)
+            if not slug:
+                sys.stderr.write(
+                    "ERROR: title must contain at least one letter or number\n"
+                )
+                return 1
+            prefix = "nojira-"
+            max_slug = max(12, 80 - len(type_) - 1 - len(prefix))
+            slug = slug[:max_slug].rstrip("-")
+            branch = f"{type_}/{prefix}{slug}"
+
+    if not _BRANCH_RE.match(branch):
+        sys.stderr.write(
+            f"ERROR: branch '{branch}' must start with feat|fix|chore|docs|test/\n"
+        )
+        return 1
+
+    if current == branch:
+        sys.stdout.write(f"Already on branch {branch}\n")
+    else:
+        code, _ = _git(["show-ref", "--verify", "--quiet", f"refs/heads/{branch}"])
+        if code == 0:
+            sys.stdout.write(f"Branch {branch} already exists - switching\n")
+            _git(["checkout", branch])
+        else:
+            _git(["checkout", "-b", branch])
+
+    rc = cmd_push(branch, 3)
+    if rc != 0:
+        return rc
+
+    code, url = _gh(["pr", "view", "--json", "url", "-q", ".url"])
+    if code == 0 and url.strip():
+        sys.stdout.write(f"Draft PR already exists: {url.strip()}\n")
+        return 0
+
+    # Conventional Commits, no scope = no linked issue (ADR-006)
+    pr_title = f"{type_}: {title}"
+    pr_body = "No linked issue (nojira)."
+    args = ["pr", "create", "--draft", "--title", pr_title, "--body", pr_body]
+    if base:
+        args += ["--base", base]
+    code, out = _gh(args)
+    if code != 0:
+        sys.stderr.write("create-pr-nojira: gh pr create failed\n")
+        return code
+    sys.stdout.write(f"Draft PR: {out.strip()}\n")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="dag_workflow")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_check = sub.add_parser("check", help="check whether a node is reachable")
+    p_check.add_argument("node", help="DAG node name (e.g. pr.merged)")
+
+    sub.add_parser("guard", help="PreToolUse hook entrypoint (reads stdin)")
+    sub.add_parser("nodes", help="list all DAG nodes")
+
+    p_push = sub.add_parser("push", help="push current branch with retry + SHA verify")
+    p_push.add_argument("branch", nargs="?", default=None)
+    p_push.add_argument("max_retries", nargs="?", type=int, default=3)
+    p_push.add_argument(
+        "--force-with-lease",
+        action="store_true",
+        dest="force_with_lease",
+        help="force-push safely after a rebase (refused on main/master)",
+    )
+
+    p_promote = sub.add_parser("promote", help="mark a draft PR ready for review")
+    p_promote.add_argument("pr_number", nargs="?", type=int, default=None)
+
+    p_finish = sub.add_parser("finish", help="push, promote, monitor_pr --merge")
+    p_finish.add_argument("pr_number", nargs="?", type=int, default=None)
+    p_finish.add_argument("--review-cycle", type=int, default=None)
+
+    p_nojira = sub.add_parser(
+        "create-pr-nojira",
+        help="create a no-issue branch + draft PR",
+    )
+    p_nojira.add_argument("type", choices=sorted(_VALID_TYPES))
+    p_nojira.add_argument("title")
+    p_nojira.add_argument("--branch", default=None)
+    p_nojira.add_argument("--base", default=None)
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "check":
+        return cmd_check(args.node)
+    if args.cmd == "guard":
+        return cmd_guard()
+    if args.cmd == "nodes":
+        for node, prereqs in GRAPH.items():
+            sys.stdout.write(f"{node}: requires={prereqs or '[]'}\n")
+        return 0
+    if args.cmd == "push":
+        return cmd_push(args.branch, args.max_retries, force=args.force_with_lease)
+    if args.cmd == "promote":
+        return cmd_promote(args.pr_number)
+    if args.cmd == "finish":
+        return cmd_finish(args.pr_number, args.review_cycle)
+    if args.cmd == "create-pr-nojira":
+        return cmd_create_pr_nojira(args.type, args.title, args.branch, args.base)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

project_init/templates/base/dot_claude/memory/MEMORY.md.tmpl

@@ -0,0 +1,11 @@
+<!--
+  MEMORY.md — project-level memory index.
+
+  One bullet per memory file. Keep lines under ~150 chars.
+  Each referenced file has frontmatter: name, description, type (user | feedback | project | reference).
+  See SCHEMA.md in this directory for the full convention.
+-->
+
+- [Project context](project_context.md) — goals, constraints, key decisions
+- [User role](user_role.md) — developer background and preferences
+- [Conventions](feedback_conventions.md) — agent behavior rules for this project

project_init/templates/base/dot_claude/memory/README.md

@@ -0,0 +1,51 @@
+# `.claude/memory/`
+
+Small, grep-able, human-readable memory files. Intended for facts an agent should reuse across sessions.
+
+See [`SCHEMA.md`](SCHEMA.md) for the authoritative governance rules (types, frontmatter, naming, lint enforcement).
+
+## Convention
+
+Every memory file has YAML frontmatter:
+
+```markdown
+---
+name: <short title>
+description: <one-line summary used for relevance ranking>
+type: user | feedback | project | reference
+---
+
+<body>
+```
+
+### Types
+
+| Type | When to use |
+|---|---|
+| `user` | About the human (role, preferences, expertise). |
+| `feedback` | Rules/corrections the user has given. Include **Why** and **How to apply**. |
+| `project` | Current-state facts about the project (deadlines, decisions, stakeholders). Include **Why** and **How to apply**. |
+| `reference` | Pointers to external systems (GitHub projects, dashboards, channels). |
+
+### What NOT to save
+
+- Code patterns/architecture (derivable from the repo)
+- Git history (use `git log`)
+- Ephemeral task state (use TODOs)
+- Anything already in `CLAUDE.md` or `project-init.md`
+
+## Index
+
+`MEMORY.md` in this directory is the index — one line per memory file. Keep it tight.
+
+## Why this split exists
+
+- `memory/` = small structured facts, agent-curated, fast to grep.
+- `vault/` = human-authored documentation (Obsidian). Larger, richer.
+
+## Graphify (if present)
+
+If this project was scaffolded with the `obsidian-graphify` preset,
+`.claude/rules/graphify.md` documents the code knowledge graph: query
+`graphify-out/graph.json` before grepping, rebuilt per commit. One-time
+setup: `.claude/scripts/setup_graphify.sh`.