project-kit-cli 1.1.0__tar.gz → 1.3.0__tar.gz

project_kit_cli-1.1.0/README.md → project_kit_cli-1.3.0/PKG-INFO

@@ -1,7 +1,32 @@
+Metadata-Version: 2.4
+Name: project-kit-cli
+Version: 1.3.0
+Summary: Project definition and dev-workflow kit that hands off to Spec Kit
+Keywords: project-management,spec-kit,claude-code,workflow,github
+Author: Miguel Tomás
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.12
+Project-URL: Homepage, https://miguelmatg.github.io/project-kit-site/
+Project-URL: Documentation, https://miguelmatg.github.io/project-kit-site/
+Description-Content-Type: text/markdown
+
 # project-kit
 
 [![PyPI](https://img.shields.io/pypi/v/project-kit-cli)](https://pypi.org/project/project-kit-cli/)
 [![License: MIT](https://img.shields.io/pypi/l/project-kit-cli)](https://pypi.org/project/project-kit-cli/)
+[![Website](https://img.shields.io/badge/website-project--kit-0a66e4)](https://miguelmatg.github.io/project-kit-site/)
+
+**Website:** [miguelmatg.github.io/project-kit-site](https://miguelmatg.github.io/project-kit-site/),
+with the phases, what to ask your agent and the commands, in English and Spanish.
 
 **Everything that happens before the first line of code.** project-kit guides you, with an AI
 agent, through defining a project, deciding its stack and architecture, agreeing how the team
@@ -82,8 +107,13 @@ Outside the sequence: `/pk-next` (runs the sequence for you), `/pk-grill` (hard
 contradictions, offered before each approval), `/pk-import` (start from existing documents),
 `/pk-skills`, `/pk-amend`, `/pk-verify` and `/pk-quiet` (runs long commands and reads long logs
 through `pjkit run`, `logs` and `peek` so that only what failed reaches the AI; it pays off with
-long output, see `pjkit docs quiet`). Each phase ends with `pjkit approve <phase>`, which only
-you run. A small project can skip three phases with `pjkit init --mode quick`.
+long output, see `pjkit docs quiet`) and `/pk-automate` (turns code the AI keeps writing into a
+saved script it runs instead). Each phase ends with `pjkit approve <phase>`, which only you run.
+A small project can skip three phases with `pjkit init --mode quick`.
+
+In Claude Code, work that needs no judgment goes to subagents with their own context and, if you
+want, a smaller model: `pk-tester` (tests and checks), `pk-provisioner` (an approved provision),
+`pk-runner` (saved scripts) and `pk-reviewer` (verification). See `pjkit docs automate`.
 
 ## Commands
 
@@ -102,22 +132,26 @@ you run. A small project can skip three phases with `pjkit init --mode quick`.
 | `pjkit uninstall [--apply] [--purge]` | Undo `init`: remove what project-kit installed and you did not edit |
 | `pjkit run -- <command>` | Run a command and print a small report instead of all its output (`logs`, `peek` and `stats` go with it) |
 | `pjkit mode [quick\|full]` | Show or change how many phases the project goes through |
+| `pjkit models [set]` | Which model each Claude Code subagent uses |
+| `pjkit actions [scripts]` | Code the AI wrote again and again, and the scripts saved instead |
 | `pjkit context` | Write or refresh the project block in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` |
 | `pjkit skills list\|show\|mark` | Recommended third-party skills and what the project decided |
 | `pjkit statusline [--install]` | A line for Claude Code's status bar: model, context, limits, project phase |
-| `pjkit hook install\|remove` | Tell Claude Code the project's state at the start of each session |
+| `pjkit hook install\|remove` | Tell Claude Code the project's state at the start of each session, and remember the code it writes |
 | `pjkit docs [topic]` | The guides |
 | `pjkit doctor` / `pjkit help` | Check the tools / a visual guide |
 
 Useful `init` options: `--from <path>`, `--mode quick|full`, `--no-context`, `--project-name`,
 `--language` (of the generated documents), `--agents claude,codex,...`, `--agent claude|none`,
-`--provider github|gitlab|none` and `--ai-coauthor keep|remove`.
+`--provider github|gitlab|none`, `--ai-coauthor keep|remove` and `--models recommended|inherit`.
 
 ## What it adds to your repository
 
 ```
 .project-kit/          config.yml, state.json, workflow.yml, templates/, handoff/
 .claude/skills/pk-*/   the skills (.agents/skills for the other agents)
+.claude/agents/pk-*    the subagents (Claude Code only)
+.project-kit/scripts/  scripts saved with /pk-automate (catalog: .project-kit/scripts.yml)
 docs/project/          brief.md, roadmap.md        (created by the phases)
 docs/adr/              one file per decision       (created by the phases)
 .githooks/commit-msg   only if you removed the AI co-author
@@ -129,8 +163,8 @@ date and `pjkit upgrade --apply` brings it up to date without touching what you
 
 ## Documentation
 
-`pjkit docs` lists every guide: `quickstart`, `example`, `session`, `flow`, `quiet`, `upgrade`,
-`provisioning`, `handoff`, `backlog-schema`, `skills`, `statusline` and `agents`.
+`pjkit docs` lists every guide: `quickstart`, `example`, `session`, `flow`, `quiet`, `automate`,
+`upgrade`, `provisioning`, `handoff`, `backlog-schema`, `skills`, `statusline` and `agents`.
 
 ## License
 

project_kit_cli-1.1.0/PKG-INFO → project_kit_cli-1.3.0/README.md

@@ -1,26 +1,11 @@
-Metadata-Version: 2.4
-Name: project-kit-cli
-Version: 1.1.0
-Summary: Project definition and dev-workflow kit that hands off to Spec Kit
-Keywords: project-management,spec-kit,claude-code,workflow,github
-Author: Miguel Tomás
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development
-Requires-Dist: pyyaml>=6.0.3
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-
 # project-kit
 
 [![PyPI](https://img.shields.io/pypi/v/project-kit-cli)](https://pypi.org/project/project-kit-cli/)
 [![License: MIT](https://img.shields.io/pypi/l/project-kit-cli)](https://pypi.org/project/project-kit-cli/)
+[![Website](https://img.shields.io/badge/website-project--kit-0a66e4)](https://miguelmatg.github.io/project-kit-site/)
+
+**Website:** [miguelmatg.github.io/project-kit-site](https://miguelmatg.github.io/project-kit-site/),
+with the phases, what to ask your agent and the commands, in English and Spanish.
 
 **Everything that happens before the first line of code.** project-kit guides you, with an AI
 agent, through defining a project, deciding its stack and architecture, agreeing how the team
@@ -101,8 +86,13 @@ Outside the sequence: `/pk-next` (runs the sequence for you), `/pk-grill` (hard
 contradictions, offered before each approval), `/pk-import` (start from existing documents),
 `/pk-skills`, `/pk-amend`, `/pk-verify` and `/pk-quiet` (runs long commands and reads long logs
 through `pjkit run`, `logs` and `peek` so that only what failed reaches the AI; it pays off with
-long output, see `pjkit docs quiet`). Each phase ends with `pjkit approve <phase>`, which only
-you run. A small project can skip three phases with `pjkit init --mode quick`.
+long output, see `pjkit docs quiet`) and `/pk-automate` (turns code the AI keeps writing into a
+saved script it runs instead). Each phase ends with `pjkit approve <phase>`, which only you run.
+A small project can skip three phases with `pjkit init --mode quick`.
+
+In Claude Code, work that needs no judgment goes to subagents with their own context and, if you
+want, a smaller model: `pk-tester` (tests and checks), `pk-provisioner` (an approved provision),
+`pk-runner` (saved scripts) and `pk-reviewer` (verification). See `pjkit docs automate`.
 
 ## Commands
 
@@ -121,22 +111,26 @@ you run. A small project can skip three phases with `pjkit init --mode quick`.
 | `pjkit uninstall [--apply] [--purge]` | Undo `init`: remove what project-kit installed and you did not edit |
 | `pjkit run -- <command>` | Run a command and print a small report instead of all its output (`logs`, `peek` and `stats` go with it) |
 | `pjkit mode [quick\|full]` | Show or change how many phases the project goes through |
+| `pjkit models [set]` | Which model each Claude Code subagent uses |
+| `pjkit actions [scripts]` | Code the AI wrote again and again, and the scripts saved instead |
 | `pjkit context` | Write or refresh the project block in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` |
 | `pjkit skills list\|show\|mark` | Recommended third-party skills and what the project decided |
 | `pjkit statusline [--install]` | A line for Claude Code's status bar: model, context, limits, project phase |
-| `pjkit hook install\|remove` | Tell Claude Code the project's state at the start of each session |
+| `pjkit hook install\|remove` | Tell Claude Code the project's state at the start of each session, and remember the code it writes |
 | `pjkit docs [topic]` | The guides |
 | `pjkit doctor` / `pjkit help` | Check the tools / a visual guide |
 
 Useful `init` options: `--from <path>`, `--mode quick|full`, `--no-context`, `--project-name`,
 `--language` (of the generated documents), `--agents claude,codex,...`, `--agent claude|none`,
-`--provider github|gitlab|none` and `--ai-coauthor keep|remove`.
+`--provider github|gitlab|none`, `--ai-coauthor keep|remove` and `--models recommended|inherit`.
 
 ## What it adds to your repository
 
 ```
 .project-kit/          config.yml, state.json, workflow.yml, templates/, handoff/
 .claude/skills/pk-*/   the skills (.agents/skills for the other agents)
+.claude/agents/pk-*    the subagents (Claude Code only)
+.project-kit/scripts/  scripts saved with /pk-automate (catalog: .project-kit/scripts.yml)
 docs/project/          brief.md, roadmap.md        (created by the phases)
 docs/adr/              one file per decision       (created by the phases)
 .githooks/commit-msg   only if you removed the AI co-author
@@ -148,8 +142,8 @@ date and `pjkit upgrade --apply` brings it up to date without touching what you
 
 ## Documentation
 
-`pjkit docs` lists every guide: `quickstart`, `example`, `session`, `flow`, `quiet`, `upgrade`,
-`provisioning`, `handoff`, `backlog-schema`, `skills`, `statusline` and `agents`.
+`pjkit docs` lists every guide: `quickstart`, `example`, `session`, `flow`, `quiet`, `automate`,
+`upgrade`, `provisioning`, `handoff`, `backlog-schema`, `skills`, `statusline` and `agents`.
 
 ## License
 

{project_kit_cli-1.1.0 → project_kit_cli-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "1.1.0"
+version = "1.3.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -27,6 +27,10 @@ dependencies = ["pyyaml>=6.0.3"]
 [[project.authors]]
 name = "Miguel Tomás"
 
+[project.urls]
+Homepage = "https://miguelmatg.github.io/project-kit-site/"
+Documentation = "https://miguelmatg.github.io/project-kit-site/"
+
 [project.scripts]
 pjkit = "project_kit.entry:main"
 

{project_kit_cli-1.1.0 → project_kit_cli-1.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "1.1.0"
+version = "1.3.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -21,6 +21,10 @@ dependencies = [
     "pyyaml>=6.0.3",
 ]
 
+[project.urls]
+Homepage = "https://miguelmatg.github.io/project-kit-site/"
+Documentation = "https://miguelmatg.github.io/project-kit-site/"
+
 [project.scripts]
 pjkit = "project_kit.entry:main"
 

project_kit_cli-1.3.0/src/project_kit/actions.py

@@ -0,0 +1,459 @@
+"""The memory of actions: notice when the AI writes the same code again and again.
+
+An agent asked for the same kind of thing (resize an image, read a web page, convert a file)
+writes much the same script every time, and every time pays for it in tokens. Claude Code calls
+``pjkit hook post-tool-use`` after each Bash, PowerShell and Write call (see ``claude_hooks``);
+this module keeps, for every piece of code that looks like a script, what it uses: the modules
+it imports, the functions and methods it calls, the commands and long options it runs. Two
+pieces of code that use much the same are the same action, even when the model named its
+variables differently or changed the URL, the path or the size this time. When a group
+has been written ``REPEATS`` times, the hook tells the agent once, and the ``pk-automate`` skill
+offers the user to save it as a script. What the user decided is remembered: a declined group is
+never offered again, a saved one is listed at the start of each session so the agent runs it
+instead of writing it.
+
+The memory is local (``.project-kit/actions/``, ignored by git). The scripts and their catalog
+(``.project-kit/scripts/`` and ``.project-kit/scripts.yml``) are the project's and are versioned.
+
+The hook runs after every command, so this module imports nothing heavy: no yaml, no config.
+Two hooks running at once can lose one occurrence; a count that is one short does no harm.
+"""
+
+import hashlib
+import json
+import re
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from project_kit.fsutil import atomic_write_text
+
+PROJECT_DIR = ".project-kit"  # config.PROJECT_DIR, not imported: config needs yaml
+MEMORY = Path(PROJECT_DIR) / "actions" / "memory.json"
+SCRIPTS_DIR = Path(PROJECT_DIR) / "scripts"
+CATALOG = Path(PROJECT_DIR) / "scripts.yml"
+HOOK_COMMAND = "pjkit hook post-tool-use"
+
+# How many times something is written before it is offered as a script.
+REPEATS = 3
+# The same thing again in the same session within this time is a retry, not a new occurrence.
+RETRY_SECONDS = 300
+# How alike two pieces of code must be to be "the same action": the share of what they use in
+# common (Jaccard). Code that uses fewer than MIN_FEATURES things only matches its exact shape.
+SIMILAR = 0.6
+MIN_FEATURES = 4
+MAX_GROUPS = 300
+MAX_EXAMPLE = 4000
+
+NEW, OFFERED, SAVED, DECLINED = "new", "offered", "saved", "declined"
+STATUSES = (NEW, OFFERED, SAVED, DECLINED)
+
+_SCRIPT_SUFFIXES = {".py", ".js", ".mjs", ".cjs", ".ts", ".sh", ".bash", ".ps1", ".rb", ".pl"}
+_SCRATCH_PARTS = {"tmp", "temp", "scratch", "scratchpad"}
+_INLINE = re.compile(
+    r"(?:^|[\s;&|(])(?:python3?|py|uv run(?: --\S+)* python3?|node|deno|ruby|perl|php|bun)"
+    r"(?:\.exe)?\s+(?:-c|-e|--eval|eval|-)(?:\s|$)|<<-?\s*['\"]?\w+|@['\"]\s*$",
+    re.MULTILINE,
+)
+
+_URL = re.compile(r"\b[a-z][a-z0-9+.-]*://\S+", re.IGNORECASE)
+_STRING = re.compile(
+    r'"""[\s\S]*?"""|\'\'\'[\s\S]*?\'\'\'|"(?:\\.|[^"\\\n])*"|\'(?:\\.|[^\'\\\n])*\''
+)
+_COMMENT = re.compile(r"(?m)^\s*(?:#|//|REM\b).*$")
+_PATH = re.compile(r"(?<![\w.])(?:[A-Za-z]:)?(?:\.{0,2}[/\\])[\w.@~+-]+(?:[/\\][\w.@~+-]*)*")
+_NUMBER = re.compile(r"\b\d+(?:\.\d+)?\b")
+_TOKEN = re.compile(r"\w+|[^\w\s]")
+
+# What a piece of code uses, read from the code itself: no parser, so it works for any language.
+_IMPORT = re.compile(
+    r"""\bimport\s+([\w.]+(?:\s*,\s*[\w.]+)*)|\bfrom\s+([\w.]+)\s+import"""
+    r"""|require\(\s*['"]([^'"]+)|\bfrom\s+['"]([^'"]+)['"]|Import-Module\s+([\w.-]+)"""
+)
+_ATTR = re.compile(r"\.\s*([A-Za-z_]\w*)")
+_CALL = re.compile(r"\b([A-Za-z_][\w-]*)\s*\(")
+_PIPED = re.compile(r"(?:^|\||&&|;|\$\()\s*([a-z][\w-]*)")
+_FLAG = re.compile(r"(?<![\w-])(--[a-z][\w-]*)")
+# Used by nearly every script, so they say nothing about what this one does.
+_COMMON = frozenset(
+    "print len open str int float bool list dict set tuple range enumerate isinstance sorted "
+    "format join split strip append extend items keys values read write close exit main self "
+    "import from if for while in not and or return with def class function const let var echo "
+    "cd cat python python3 py node uv run".split()
+)
+
+
+@dataclass
+class Group:
+    id: str
+    kind: str  # bash | write
+    count: int
+    first: str
+    last: str
+    session: str
+    status: str = NEW
+    script: str = ""  # name in the catalog, once saved
+    example: str = ""  # the latest occurrence, without secrets, cut at MAX_EXAMPLE
+    shape: str = ""  # hash of the normalized code
+    features: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Memory:
+    groups: list[Group] = field(default_factory=list)
+
+    def find(self, group_id: str) -> Group | None:
+        return next((g for g in self.groups if g.id == group_id), None)
+
+
+@dataclass(frozen=True)
+class Action:
+    kind: str
+    code: str
+
+
+def project_root(start: Path) -> Path | None:
+    for folder in (start, *start.parents):
+        if (folder / PROJECT_DIR / "config.yml").is_file():
+            return folder
+    return None
+
+
+# --- what counts as code ---------------------------------------------------------------------
+
+
+def _lines(text: str) -> int:
+    return sum(1 for line in text.splitlines() if line.strip())
+
+
+def _is_scratch(path: Path, root: Path) -> bool:
+    """A script written outside the project or in a temporary folder: a throwaway, not the
+    project's own code (which is edited over and over on purpose)."""
+    try:
+        rel = path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return True
+    return any(part.lower() in _SCRATCH_PARTS for part in rel.parts[:-1])
+
+
+def extract(payload: dict[str, Any], root: Path) -> Action | None:
+    """The code in a tool call, if it looks like a script someone may want to keep."""
+    tool = payload.get("tool_name")
+    data = payload.get("tool_input")
+    if not isinstance(data, dict):
+        return None
+    if tool in ("Bash", "PowerShell"):
+        code = data.get("command")
+        if not isinstance(code, str):
+            return None
+        stripped = code.strip()
+        if stripped.startswith("pjkit") or SCRIPTS_DIR.as_posix() in code.replace("\\", "/"):
+            return None  # already one of ours
+        inline = bool(_INLINE.search(code)) and len(stripped) >= 80
+        return Action("bash", code) if inline or _lines(code) >= 4 else None
+    if tool == "Write":
+        path, code = data.get("file_path"), data.get("content")
+        if not (isinstance(path, str) and isinstance(code, str)):
+            return None
+        target = Path(path)
+        if target.suffix.lower() not in _SCRIPT_SUFFIXES or _lines(code) < 5:
+            return None
+        if SCRIPTS_DIR.as_posix() in path.replace("\\", "/"):
+            return None
+        return Action("write", code) if _is_scratch(target, root) else None
+    return None
+
+
+# --- what "the same" means -------------------------------------------------------------------
+
+
+def normalize(code: str) -> str:
+    """The shape of the code: the values that change from one request to the next are gone."""
+    text = _URL.sub(" U ", code)
+    text = _STRING.sub(" S ", text)
+    text = _COMMENT.sub("", text)
+    text = _PATH.sub(" P ", text)
+    text = _NUMBER.sub("0", text)
+    return " ".join(_TOKEN.findall(text))
+
+
+def shape_hash(code: str) -> str:
+    return hashlib.sha1(normalize(code).encode()).hexdigest()[:8]
+
+
+def features(code: str) -> list[str]:
+    """What the code uses: modules, called functions and methods, commands, long options."""
+    found = set()
+    for match in _IMPORT.finditer(code):
+        names = next(g for g in match.groups() if g)
+        for name in names.split(","):
+            found.add("import:" + re.split(r"[./]", name.strip().lstrip("@"))[0])
+    body = _COMMENT.sub("", _STRING.sub(" S ", _URL.sub(" U ", code)))
+    first = body.strip().splitlines()[0] if body.strip() else ""
+    found |= {"." + name for name in _ATTR.findall(body)}
+    found |= {name + "()" for name in _CALL.findall(body)}
+    found |= {"$" + name for name in _PIPED.findall(first)}
+    found |= set(_FLAG.findall(body))
+    return sorted(f for f in found if f.split(":")[-1].strip(".()$").lower() not in _COMMON)
+
+
+def similarity(a: list[str], b: list[str]) -> float:
+    sa, sb = set(a), set(b)
+    if len(sa) < MIN_FEATURES or len(sb) < MIN_FEATURES:
+        return 0.0
+    return len(sa & sb) / len(sa | sb)
+
+
+def _same(group: "Group", shape: str, uses: list[str]) -> float:
+    return 1.0 if group.shape == shape else similarity(uses, group.features)
+
+
+# --- the memory ------------------------------------------------------------------------------
+
+
+def load(root: Path) -> Memory:
+    try:
+        data = json.loads((root / MEMORY).read_text(encoding="utf-8"))
+        groups = [Group(**g) for g in data["groups"]]
+    except (OSError, ValueError, KeyError, TypeError):
+        return Memory()  # missing or damaged: start again, it is only a memory
+    return Memory([g for g in groups if g.status in STATUSES])
+
+
+def save(root: Path, memory: Memory) -> None:
+    folder = root / MEMORY.parent
+    folder.mkdir(parents=True, exist_ok=True)
+    ignore = folder / ".gitignore"
+    if not ignore.exists():
+        ignore.write_text("*\n", encoding="utf-8")
+    if len(memory.groups) > MAX_GROUPS:  # forget what was seen once, oldest first
+        once = sorted((g for g in memory.groups if g.count == 1 and g.status == NEW),
+                      key=lambda g: g.last)  # fmt: skip
+        drop = {id(g) for g in once[: len(memory.groups) - MAX_GROUPS]}
+        memory.groups = [g for g in memory.groups if id(g) not in drop]
+    body = {"schema_version": 1, "groups": [asdict(g) for g in memory.groups]}
+    atomic_write_text(root / MEMORY, json.dumps(body, ensure_ascii=False) + "\n")
+
+
+def _redact(text: str) -> str:
+    from project_kit.redact import redact  # only when something is recorded
+
+    return redact(text)
+
+
+def record(root: Path, action: Action, session: str, now: datetime) -> tuple[Group, bool]:
+    """Add one occurrence. Returns its group and whether it has just become worth offering
+    (it then counts as offered, so it is offered once)."""
+    memory = load(root)
+    shape, uses = shape_hash(action.code), features(action.code)
+    stamp = now.isoformat(timespec="seconds")
+    # Any kind: the same script may be written to a file one day and run inline the next.
+    best = max(memory.groups, key=lambda g: _same(g, shape, uses), default=None)
+    if best is None or _same(best, shape, uses) < SIMILAR:
+        best = Group(shape, action.kind, 0, stamp, stamp, session, shape=shape, features=uses)
+        while memory.find(best.id):  # same shape as a group that grew apart from it: rare
+            best.id = hashlib.sha1(best.id.encode()).hexdigest()[:8]
+        memory.groups.append(best)
+    retry = (
+        best.count > 0
+        and best.session == session
+        and (now - datetime.fromisoformat(best.last)).total_seconds() < RETRY_SECONDS
+    )
+    if not retry:
+        best.count += 1
+    best.last, best.session = stamp, session
+    best.example = _redact(action.code)[:MAX_EXAMPLE]
+    offer = best.status == NEW and best.count >= REPEATS
+    if offer:
+        best.status = OFFERED
+    save(root, memory)
+    return best, offer
+
+
+def notice(group: Group) -> str:
+    return (
+        f"project-kit: this code (action {group.id}) has now been written {group.count} times "
+        "in this project. When the user's current request is done, follow the pk-automate skill "
+        "to offer to save it as a script, so that next time it is run instead of written again."
+    )
+
+
+def post_tool_use(payload: dict[str, Any], cwd: Path, now: datetime | None = None) -> str:
+    """What the hook prints: Claude Code's JSON with a notice, or nothing. Never raises."""
+    try:
+        root = project_root(cwd)
+        action = extract(payload, root) if root else None
+        if root is None or action is None:
+            return ""
+        session = str(payload.get("session_id") or "")
+        group, offer = record(root, action, session, now or datetime.now(UTC))
+        if not offer:
+            return ""
+    except Exception:  # noqa: BLE001 - a hook must never break the agent's work
+        return ""
+    return json.dumps(
+        {"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": notice(group)}}
+    )
+
+
+# --- what the user decided -------------------------------------------------------------------
+
+
+class ActionsError(ValueError):
+    """An unknown action, a missing script, a bad catalog."""
+
+
+def set_status(root: Path, group_id: str, status: str, script: str = "") -> Group:
+    memory = load(root)
+    group = memory.find(group_id)
+    if group is None:
+        raise ActionsError(f"No action {group_id!r}; `pjkit actions list --all` shows them.")
+    group.status, group.script = status, script
+    if status == NEW:
+        group.count = 0  # "not now": offered again after REPEATS more
+    save(root, memory)
+    return group
+
+
+def pending(memory: Memory) -> list[Group]:
+    return [g for g in memory.groups if g.status == OFFERED]
+
+
+def repeated(memory: Memory, *, everything: bool = False) -> list[Group]:
+    shown = [g for g in memory.groups if everything or g.count >= 2 or g.status != NEW]
+    return sorted(shown, key=lambda g: (-g.count, g.last))
+
+
+def summary(group: Group, width: int = 60) -> str:
+    """What the code uses, which says more than its first line (often ``python - <<EOF``)."""
+    modules = [f[7:] for f in group.features if f.startswith("import:")]
+    calls = [f[:-2] for f in group.features if f.endswith("()")]
+    text = ", ".join(modules) + (": " if modules and calls else "") + ", ".join(calls)
+    if not text:
+        text = next((x.strip() for x in group.example.splitlines() if x.strip()), "")
+    return text if len(text) <= width else text[: width - 3] + "..."
+
+
+def render_list(groups: list[Group]) -> str:
+    if not groups:
+        return "Nothing has been written more than once yet."
+    lines = [f"{'id':<9} {'times':>5}  {'status':<9} {'kind':<6} uses"]
+    for g in groups:
+        status = f"{g.status}:{g.script}" if g.status == SAVED else g.status
+        lines.append(f"{g.id:<9} {g.count:>5}  {status:<9} {g.kind:<6} {summary(g)}")
+    lines.append(
+        "\n`pjkit actions show <id>` shows the code. The pk-automate skill turns one into a script."
+    )
+    return "\n".join(lines)
+
+
+def render_group(group: Group) -> str:
+    head = (
+        f"Action {group.id}: {group.kind}, written {group.count} time(s), {group.status}"
+        + (f" (script {group.script})" if group.script else "")
+        + f"; first {group.first}, last {group.last}."
+    )
+    return f"{head}\nThe latest one (secrets removed):\n\n{group.example}"
+
+
+# --- the catalog of saved scripts ------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Script:
+    name: str
+    file: str  # relative to SCRIPTS_DIR
+    description: str
+    usage: str
+    action: str = ""  # the group it came from, if any
+
+
+_NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,47}")
+
+
+def load_catalog(root: Path) -> list[Script]:
+    import yaml  # not at module level: the hook path must stay light
+
+    path = root / CATALOG
+    if not path.exists():
+        return []
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        raise ActionsError(f"scripts.yml is not valid YAML: {exc}") from exc
+    entries = data.get("scripts", []) if isinstance(data, dict) else None
+    if not isinstance(entries, list):
+        raise ActionsError("scripts.yml must have a list under `scripts`")
+    scripts = []
+    for entry in entries:
+        if not isinstance(entry, dict) or not all(
+            isinstance(entry.get(k), str) for k in ("name", "file", "description", "usage")
+        ):
+            raise ActionsError("every script in scripts.yml needs name, file, description, usage")
+        scripts.append(Script(**{k: str(entry.get(k, "")) for k in Script.__dataclass_fields__}))
+    return scripts
+
+
+def save_catalog(root: Path, scripts: list[Script]) -> None:
+    import yaml
+
+    body = {
+        "schema_version": 1,
+        "scripts": [{k: v for k, v in asdict(s).items() if v} for s in scripts],
+    }
+    header = (
+        "# Scripts saved so the AI runs them instead of writing the same code again.\n"
+        "# Kept by `pjkit actions save`; safe to edit by hand.\n"
+    )
+    text = yaml.safe_dump(body, sort_keys=False, allow_unicode=True, width=100)
+    atomic_write_text(root / CATALOG, header + text)
+
+
+def add_script(root: Path, script: Script) -> None:
+    """Add (or replace, by name) a script in the catalog; mark its action as saved."""
+    if not _NAME.fullmatch(script.name):
+        raise ActionsError(f"{script.name!r}: use lowercase letters, digits and dashes")
+    file = (root / SCRIPTS_DIR / script.file).resolve()
+    if not file.is_relative_to((root / SCRIPTS_DIR).resolve()) or not file.is_file():
+        raise ActionsError(f"{(SCRIPTS_DIR / script.file).as_posix()} does not exist")
+    if not script.description.strip() or not script.usage.strip():
+        raise ActionsError("a script needs a description and a usage line")
+    if script.action:
+        set_status(root, script.action, SAVED, script.name)
+    scripts = [s for s in load_catalog(root) if s.name != script.name] + [script]
+    save_catalog(root, sorted(scripts, key=lambda s: s.name))
+
+
+def render_catalog(scripts: list[Script]) -> str:
+    if not scripts:
+        return "No scripts saved yet."
+    lines = []
+    for s in scripts:
+        lines += [f"{s.name}: {s.description}", f"    {s.usage}"]
+    return "\n".join(lines)
+
+
+def session_lines(root: Path, limit: int = 12) -> list[str]:
+    """What the start of a session needs to know: the saved scripts and what awaits a decision."""
+    lines = []
+    try:
+        scripts = load_catalog(root)
+    except ActionsError:
+        scripts = []
+    if scripts:
+        lines.append(
+            "Saved scripts: before writing code for one of these, run the script instead "
+            "(usage: `pjkit actions scripts`; in Claude Code, through the pk-runner subagent):"
+        )
+        lines += [f"- {s.name}: {s.description}" for s in scripts[:limit]]
+        if len(scripts) > limit:
+            lines.append(f"- and {len(scripts) - limit} more.")
+    waiting = pending(load(root))
+    if waiting:
+        ids = ", ".join(g.id for g in waiting)
+        lines.append(
+            f"Code written again and again is waiting for the user's decision ({ids}): at a "
+            "natural pause, follow the pk-automate skill."
+        )
+    return lines