agent-sdlc 0.3.0__tar.gz → 0.4.0__tar.gz

agent_sdlc-0.4.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: agent-sdlc
+Version: 0.4.0
+Summary: Diff-scoped mutation gate for pre-commit and agent Stop hooks
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PavelGuzenfeld/agent-sdlc
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: ast-grep-cli==0.45.3
+Provides-Extra: vocabulary
+Requires-Dist: nltk; extra == "vocabulary"
+Dynamic: license-file
+
+# agent-sdlc
+
+[![CI](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml/badge.svg)](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml)
+
+A software development lifecycle shipped as agent config for Claude Code and
+Codex: rules, skills, slash commands, hooks, and a diff-scoped mutation gate.
+
+Docs: <https://pavelguzenfeld.com/agent-sdlc/>
+
+## Why
+
+A coding agent writes the code and the tests for it, and tests written next
+to the code tend to agree with it, bugs included. We planted small realistic
+bugs in a mature, well-tested project, and the suite stayed green for 57% of
+them. Unit tests can each pass while the feature, entered the way a user
+enters it, still fails. agent-sdlc puts those checks, plus scope, intent and
+git safety, into hooks and a gate instead of leaving them to the agent's
+memory.
+
+| Problem | What catches it |
+|---|---|
+| Tests that pass but assert nothing | `mutation-gate`: a surviving mutant blocks the commit |
+| Tests shaped to the code | An adversary review that sees intent and tests, never the code |
+| Unit tests green, feature broken | One vertical-slice test per ticket, entered where a real consumer enters, red before any code |
+| Scope creep | 40-line limit without a ticket; one ticket, one branch, one PR |
+| Code bloat | Smallest-change and zero-comment rules; a `no-comments` hook; every added line must kill its mutants |
+| Design notes rotting in the tree | New `.md` files are blocked; intent lives in the tracker |
+| Destructive git | A hook that denies `reset --hard`, `add -A`, force-push |
+| AI tells and leaked identity in commits | `commit-msg` and `no-leaks` hooks |
+
+## How it fits together
+
+`x` marks a blocker. `[name]` is the rule in `rules/` that applies.
+
+```text
+ rules/*.md sync into .claude/rules and AGENTS.md; every session loads them
+
+  idea
+   |  /grill, or gh issue create
+   v
+ +--------------------------+
+ | ticket                   |  intent lives here, not in the tree  [tickets]
+ +--------------------------+
+   |  triage: model:* label + assignee
+   v                       x assigned to someone else: /kata stops
+                           unlabelled or unassigned: /kata asks first
+ +--------------------------+
+ | /kata N                  |  one ticket, one branch, one PR      [tickets]
+ | branch off origin/main   |
+ +--------------------------+
+   v
+ +--------------------------+
+ | red slice test           |  enters where a user enters,         [testing]
+ |                          |  watched failing first
+ +--------------------------+
+   v
+ +--------------------------+
+ | implement                |  smallest change           [diff-discipline]
+ |                          |  no comments, canonical names
+ +--------------------------+         [code-clarity] [naming]
+   |  every Bash call: git-guardrail  x reset --hard, add -A, force-push
+   v
+ +--------------------------+
+ | git commit               |
+ |  pre-commit              |
+ |   rules-check            |  x .claude/rules drifted from the pack
+ |   mutation-gate ---------+- x surviving mutant --> new test, or waiver
+ |   no-new-docs            |  x new .md file not allowlisted
+ |  commit-msg              |
+ |   commit-msg             |  x banned words, AI attribution    [voice]
+ |   diff-discipline        |  x over 40 lines, no ticket ref
+ |   no-leaks               |  x email, private IP, home path
+ +--------------------------+
+   |  gate green -> adversary review: sees intent and tests, never
+   |  the code; reports, never blocks; answer every finding
+   |  Stop hook: runs the same gate if no commit did
+   v
+ +--------------------------+
+ | push, PR "Closes #N"     |  x CI red
+ +--------------------------+
+   v
+ +--------------------------+
+ | you review, type LGTM    |  squash merge, branch deleted
+ +--------------------------+
+   v
+  /done: handoff, follow-up tickets --> back to "ticket"
+```
+
+## Example
+
+```python
+def is_adult(age):
+    return age >= 18
+
+def test_adult():
+    assert is_adult(30)
+
+def test_child():
+    assert not is_adult(5)
+```
+
+```text
+BLOCKED: 2 mutant(s) survived with no waiver.
+  age.py:2:11:operator:age >= 18 => age > 18
+  age.py:2:18:literal:18 => 19
+```
+
+Add `assert is_adult(18)` and `assert not is_adult(17)`, and the gate passes.
+
+## Install
+
+Claude Code:
+
+```bash
+claude plugin marketplace add PavelGuzenfeld/agent-sdlc
+claude plugin install agent-sdlc@agent-sdlc
+```
+
+Tools the gate needs, and Codex:
+
+```bash
+git clone https://github.com/PavelGuzenfeld/agent-sdlc
+cd agent-sdlc
+./install.sh --deps
+```
+
+| Want | Do |
+|---|---|
+| Claude Code | The plugin above; `--scope local` or `--scope project` keeps it to one repo |
+| Codex | `./install.sh --target codex`, or add the repo as a Codex marketplace source |
+| Gate dependencies | `./install.sh --deps` (`--deps=say` adds voice) |
+| Only the gate | `pip install agent-sdlc` (WordNet check: `agent-sdlc[vocabulary]`) |
+| The gate on a repo | Add `.mutation-gate.toml`, wire the pre-commit hooks |
+
+- `install.sh` links `skills/` into `~/.codex` and renders `commands/` as
+  Codex skills. It installs nothing into `~/.claude`. A second run changes
+  nothing.
+- Installed an older `install.sh` into `~/.claude`? `./install.sh
+  --uninstall-legacy` removes those links and hooks, or every hook fires twice.
+- `ast-grep-cli` adds an `sg` shim that can shadow the system `sg`; call
+  `ast-grep`.
+
+## Use it
+
+In Claude Code (Codex: `$name` instead of `/name`):
+
+1. Install the plugin and `./install.sh --deps`
+2. In your repo: `touch .mutation-gate.toml && mutation-gate rules sync`
+3. `claude`, then `/grill <idea>` or `gh issue create …`
+4. Approve the ticket: `gh issue edit 42 --add-label model:sonnet`
+5. `/kata 42`: a worker writes the failing slice test, implements, gates, opens the PR
+6. Review, then type `LGTM`: it squash-merges and cleans up
+7. `/done` to close out the session
+
+Full walkthrough, and what differs in Codex:
+<https://pavelguzenfeld.com/agent-sdlc/usage/>
+
+## With standard
+
+[standard](https://github.com/PavelGuzenfeld/standard) runs C++ and Python
+quality gates on the PR. agent-sdlc runs before the commit. Use both:
+
+```text
+ agent session  ->  git commit  ->  PR  ->  merge
+ '------ agent-sdlc -------'       '-- standard --'
+```
+
+Run standard's setup first, then `mutation-gate rules sync`. Copying its
+`AGENTS.md` afterwards drops the rules block. In CI, the agent-sdlc diff
+checks need `--range`, because `pre-commit run --from-ref` doesn't enforce
+them. Setup order, the CI job and the `docs/` allowlist:
+<https://pavelguzenfeld.com/agent-sdlc/usage/#with-standard>
+
+## What's inside
+
+| Path | What |
+|---|---|
+| `rules/` | How to work; synced into a repo with `mutation-gate rules sync` |
+| `commands/` | Slash commands: `/kata`, `/done`, `/grill`, `/rectify` … |
+| `skills/` | On-demand playbooks: `/diagnose`, `/sol-budget`, `/verify-generated-diff` … |
+| `bin/` | Hooks and helpers: `git-guardrail.sh`, the `/say` stack |
+| `mutation_gate/` | The gate and the `mutation-gate` CLI |
+
+CI runs `scripts/no-leaks.sh` on every PR. It flags emails, RFC1918
+addresses, user-at-host references, `/home/<user>/` paths and non-personal
+`ghcr.io/` paths, and prints only `file:line`.
+
+MIT, see [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md) for one vendored
+third-party skill. Contributions: [CONTRIBUTING.md](CONTRIBUTING.md), bound
+by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Security: [SECURITY.md](SECURITY.md).

agent_sdlc-0.4.0/README.md

@@ -0,0 +1,190 @@
+# agent-sdlc
+
+[![CI](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml/badge.svg)](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml)
+
+A software development lifecycle shipped as agent config for Claude Code and
+Codex: rules, skills, slash commands, hooks, and a diff-scoped mutation gate.
+
+Docs: <https://pavelguzenfeld.com/agent-sdlc/>
+
+## Why
+
+A coding agent writes the code and the tests for it, and tests written next
+to the code tend to agree with it, bugs included. We planted small realistic
+bugs in a mature, well-tested project, and the suite stayed green for 57% of
+them. Unit tests can each pass while the feature, entered the way a user
+enters it, still fails. agent-sdlc puts those checks, plus scope, intent and
+git safety, into hooks and a gate instead of leaving them to the agent's
+memory.
+
+| Problem | What catches it |
+|---|---|
+| Tests that pass but assert nothing | `mutation-gate`: a surviving mutant blocks the commit |
+| Tests shaped to the code | An adversary review that sees intent and tests, never the code |
+| Unit tests green, feature broken | One vertical-slice test per ticket, entered where a real consumer enters, red before any code |
+| Scope creep | 40-line limit without a ticket; one ticket, one branch, one PR |
+| Code bloat | Smallest-change and zero-comment rules; a `no-comments` hook; every added line must kill its mutants |
+| Design notes rotting in the tree | New `.md` files are blocked; intent lives in the tracker |
+| Destructive git | A hook that denies `reset --hard`, `add -A`, force-push |
+| AI tells and leaked identity in commits | `commit-msg` and `no-leaks` hooks |
+
+## How it fits together
+
+`x` marks a blocker. `[name]` is the rule in `rules/` that applies.
+
+```text
+ rules/*.md sync into .claude/rules and AGENTS.md; every session loads them
+
+  idea
+   |  /grill, or gh issue create
+   v
+ +--------------------------+
+ | ticket                   |  intent lives here, not in the tree  [tickets]
+ +--------------------------+
+   |  triage: model:* label + assignee
+   v                       x assigned to someone else: /kata stops
+                           unlabelled or unassigned: /kata asks first
+ +--------------------------+
+ | /kata N                  |  one ticket, one branch, one PR      [tickets]
+ | branch off origin/main   |
+ +--------------------------+
+   v
+ +--------------------------+
+ | red slice test           |  enters where a user enters,         [testing]
+ |                          |  watched failing first
+ +--------------------------+
+   v
+ +--------------------------+
+ | implement                |  smallest change           [diff-discipline]
+ |                          |  no comments, canonical names
+ +--------------------------+         [code-clarity] [naming]
+   |  every Bash call: git-guardrail  x reset --hard, add -A, force-push
+   v
+ +--------------------------+
+ | git commit               |
+ |  pre-commit              |
+ |   rules-check            |  x .claude/rules drifted from the pack
+ |   mutation-gate ---------+- x surviving mutant --> new test, or waiver
+ |   no-new-docs            |  x new .md file not allowlisted
+ |  commit-msg              |
+ |   commit-msg             |  x banned words, AI attribution    [voice]
+ |   diff-discipline        |  x over 40 lines, no ticket ref
+ |   no-leaks               |  x email, private IP, home path
+ +--------------------------+
+   |  gate green -> adversary review: sees intent and tests, never
+   |  the code; reports, never blocks; answer every finding
+   |  Stop hook: runs the same gate if no commit did
+   v
+ +--------------------------+
+ | push, PR "Closes #N"     |  x CI red
+ +--------------------------+
+   v
+ +--------------------------+
+ | you review, type LGTM    |  squash merge, branch deleted
+ +--------------------------+
+   v
+  /done: handoff, follow-up tickets --> back to "ticket"
+```
+
+## Example
+
+```python
+def is_adult(age):
+    return age >= 18
+
+def test_adult():
+    assert is_adult(30)
+
+def test_child():
+    assert not is_adult(5)
+```
+
+```text
+BLOCKED: 2 mutant(s) survived with no waiver.
+  age.py:2:11:operator:age >= 18 => age > 18
+  age.py:2:18:literal:18 => 19
+```
+
+Add `assert is_adult(18)` and `assert not is_adult(17)`, and the gate passes.
+
+## Install
+
+Claude Code:
+
+```bash
+claude plugin marketplace add PavelGuzenfeld/agent-sdlc
+claude plugin install agent-sdlc@agent-sdlc
+```
+
+Tools the gate needs, and Codex:
+
+```bash
+git clone https://github.com/PavelGuzenfeld/agent-sdlc
+cd agent-sdlc
+./install.sh --deps
+```
+
+| Want | Do |
+|---|---|
+| Claude Code | The plugin above; `--scope local` or `--scope project` keeps it to one repo |
+| Codex | `./install.sh --target codex`, or add the repo as a Codex marketplace source |
+| Gate dependencies | `./install.sh --deps` (`--deps=say` adds voice) |
+| Only the gate | `pip install agent-sdlc` (WordNet check: `agent-sdlc[vocabulary]`) |
+| The gate on a repo | Add `.mutation-gate.toml`, wire the pre-commit hooks |
+
+- `install.sh` links `skills/` into `~/.codex` and renders `commands/` as
+  Codex skills. It installs nothing into `~/.claude`. A second run changes
+  nothing.
+- Installed an older `install.sh` into `~/.claude`? `./install.sh
+  --uninstall-legacy` removes those links and hooks, or every hook fires twice.
+- `ast-grep-cli` adds an `sg` shim that can shadow the system `sg`; call
+  `ast-grep`.
+
+## Use it
+
+In Claude Code (Codex: `$name` instead of `/name`):
+
+1. Install the plugin and `./install.sh --deps`
+2. In your repo: `touch .mutation-gate.toml && mutation-gate rules sync`
+3. `claude`, then `/grill <idea>` or `gh issue create …`
+4. Approve the ticket: `gh issue edit 42 --add-label model:sonnet`
+5. `/kata 42`: a worker writes the failing slice test, implements, gates, opens the PR
+6. Review, then type `LGTM`: it squash-merges and cleans up
+7. `/done` to close out the session
+
+Full walkthrough, and what differs in Codex:
+<https://pavelguzenfeld.com/agent-sdlc/usage/>
+
+## With standard
+
+[standard](https://github.com/PavelGuzenfeld/standard) runs C++ and Python
+quality gates on the PR. agent-sdlc runs before the commit. Use both:
+
+```text
+ agent session  ->  git commit  ->  PR  ->  merge
+ '------ agent-sdlc -------'       '-- standard --'
+```
+
+Run standard's setup first, then `mutation-gate rules sync`. Copying its
+`AGENTS.md` afterwards drops the rules block. In CI, the agent-sdlc diff
+checks need `--range`, because `pre-commit run --from-ref` doesn't enforce
+them. Setup order, the CI job and the `docs/` allowlist:
+<https://pavelguzenfeld.com/agent-sdlc/usage/#with-standard>
+
+## What's inside
+
+| Path | What |
+|---|---|
+| `rules/` | How to work; synced into a repo with `mutation-gate rules sync` |
+| `commands/` | Slash commands: `/kata`, `/done`, `/grill`, `/rectify` … |
+| `skills/` | On-demand playbooks: `/diagnose`, `/sol-budget`, `/verify-generated-diff` … |
+| `bin/` | Hooks and helpers: `git-guardrail.sh`, the `/say` stack |
+| `mutation_gate/` | The gate and the `mutation-gate` CLI |
+
+CI runs `scripts/no-leaks.sh` on every PR. It flags emails, RFC1918
+addresses, user-at-host references, `/home/<user>/` paths and non-personal
+`ghcr.io/` paths, and prints only `file:line`.
+
+MIT, see [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md) for one vendored
+third-party skill. Contributions: [CONTRIBUTING.md](CONTRIBUTING.md), bound
+by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Security: [SECURITY.md](SECURITY.md).

agent_sdlc-0.4.0/agent_sdlc.egg-info/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: agent-sdlc
+Version: 0.4.0
+Summary: Diff-scoped mutation gate for pre-commit and agent Stop hooks
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PavelGuzenfeld/agent-sdlc
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: ast-grep-cli==0.45.3
+Provides-Extra: vocabulary
+Requires-Dist: nltk; extra == "vocabulary"
+Dynamic: license-file
+
+# agent-sdlc
+
+[![CI](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml/badge.svg)](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml)
+
+A software development lifecycle shipped as agent config for Claude Code and
+Codex: rules, skills, slash commands, hooks, and a diff-scoped mutation gate.
+
+Docs: <https://pavelguzenfeld.com/agent-sdlc/>
+
+## Why
+
+A coding agent writes the code and the tests for it, and tests written next
+to the code tend to agree with it, bugs included. We planted small realistic
+bugs in a mature, well-tested project, and the suite stayed green for 57% of
+them. Unit tests can each pass while the feature, entered the way a user
+enters it, still fails. agent-sdlc puts those checks, plus scope, intent and
+git safety, into hooks and a gate instead of leaving them to the agent's
+memory.
+
+| Problem | What catches it |
+|---|---|
+| Tests that pass but assert nothing | `mutation-gate`: a surviving mutant blocks the commit |
+| Tests shaped to the code | An adversary review that sees intent and tests, never the code |
+| Unit tests green, feature broken | One vertical-slice test per ticket, entered where a real consumer enters, red before any code |
+| Scope creep | 40-line limit without a ticket; one ticket, one branch, one PR |
+| Code bloat | Smallest-change and zero-comment rules; a `no-comments` hook; every added line must kill its mutants |
+| Design notes rotting in the tree | New `.md` files are blocked; intent lives in the tracker |
+| Destructive git | A hook that denies `reset --hard`, `add -A`, force-push |
+| AI tells and leaked identity in commits | `commit-msg` and `no-leaks` hooks |
+
+## How it fits together
+
+`x` marks a blocker. `[name]` is the rule in `rules/` that applies.
+
+```text
+ rules/*.md sync into .claude/rules and AGENTS.md; every session loads them
+
+  idea
+   |  /grill, or gh issue create
+   v
+ +--------------------------+
+ | ticket                   |  intent lives here, not in the tree  [tickets]
+ +--------------------------+
+   |  triage: model:* label + assignee
+   v                       x assigned to someone else: /kata stops
+                           unlabelled or unassigned: /kata asks first
+ +--------------------------+
+ | /kata N                  |  one ticket, one branch, one PR      [tickets]
+ | branch off origin/main   |
+ +--------------------------+
+   v
+ +--------------------------+
+ | red slice test           |  enters where a user enters,         [testing]
+ |                          |  watched failing first
+ +--------------------------+
+   v
+ +--------------------------+
+ | implement                |  smallest change           [diff-discipline]
+ |                          |  no comments, canonical names
+ +--------------------------+         [code-clarity] [naming]
+   |  every Bash call: git-guardrail  x reset --hard, add -A, force-push
+   v
+ +--------------------------+
+ | git commit               |
+ |  pre-commit              |
+ |   rules-check            |  x .claude/rules drifted from the pack
+ |   mutation-gate ---------+- x surviving mutant --> new test, or waiver
+ |   no-new-docs            |  x new .md file not allowlisted
+ |  commit-msg              |
+ |   commit-msg             |  x banned words, AI attribution    [voice]
+ |   diff-discipline        |  x over 40 lines, no ticket ref
+ |   no-leaks               |  x email, private IP, home path
+ +--------------------------+
+   |  gate green -> adversary review: sees intent and tests, never
+   |  the code; reports, never blocks; answer every finding
+   |  Stop hook: runs the same gate if no commit did
+   v
+ +--------------------------+
+ | push, PR "Closes #N"     |  x CI red
+ +--------------------------+
+   v
+ +--------------------------+
+ | you review, type LGTM    |  squash merge, branch deleted
+ +--------------------------+
+   v
+  /done: handoff, follow-up tickets --> back to "ticket"
+```
+
+## Example
+
+```python
+def is_adult(age):
+    return age >= 18
+
+def test_adult():
+    assert is_adult(30)
+
+def test_child():
+    assert not is_adult(5)
+```
+
+```text
+BLOCKED: 2 mutant(s) survived with no waiver.
+  age.py:2:11:operator:age >= 18 => age > 18
+  age.py:2:18:literal:18 => 19
+```
+
+Add `assert is_adult(18)` and `assert not is_adult(17)`, and the gate passes.
+
+## Install
+
+Claude Code:
+
+```bash
+claude plugin marketplace add PavelGuzenfeld/agent-sdlc
+claude plugin install agent-sdlc@agent-sdlc
+```
+
+Tools the gate needs, and Codex:
+
+```bash
+git clone https://github.com/PavelGuzenfeld/agent-sdlc
+cd agent-sdlc
+./install.sh --deps
+```
+
+| Want | Do |
+|---|---|
+| Claude Code | The plugin above; `--scope local` or `--scope project` keeps it to one repo |
+| Codex | `./install.sh --target codex`, or add the repo as a Codex marketplace source |
+| Gate dependencies | `./install.sh --deps` (`--deps=say` adds voice) |
+| Only the gate | `pip install agent-sdlc` (WordNet check: `agent-sdlc[vocabulary]`) |
+| The gate on a repo | Add `.mutation-gate.toml`, wire the pre-commit hooks |
+
+- `install.sh` links `skills/` into `~/.codex` and renders `commands/` as
+  Codex skills. It installs nothing into `~/.claude`. A second run changes
+  nothing.
+- Installed an older `install.sh` into `~/.claude`? `./install.sh
+  --uninstall-legacy` removes those links and hooks, or every hook fires twice.
+- `ast-grep-cli` adds an `sg` shim that can shadow the system `sg`; call
+  `ast-grep`.
+
+## Use it
+
+In Claude Code (Codex: `$name` instead of `/name`):
+
+1. Install the plugin and `./install.sh --deps`
+2. In your repo: `touch .mutation-gate.toml && mutation-gate rules sync`
+3. `claude`, then `/grill <idea>` or `gh issue create …`
+4. Approve the ticket: `gh issue edit 42 --add-label model:sonnet`
+5. `/kata 42`: a worker writes the failing slice test, implements, gates, opens the PR
+6. Review, then type `LGTM`: it squash-merges and cleans up
+7. `/done` to close out the session
+
+Full walkthrough, and what differs in Codex:
+<https://pavelguzenfeld.com/agent-sdlc/usage/>
+
+## With standard
+
+[standard](https://github.com/PavelGuzenfeld/standard) runs C++ and Python
+quality gates on the PR. agent-sdlc runs before the commit. Use both:
+
+```text
+ agent session  ->  git commit  ->  PR  ->  merge
+ '------ agent-sdlc -------'       '-- standard --'
+```
+
+Run standard's setup first, then `mutation-gate rules sync`. Copying its
+`AGENTS.md` afterwards drops the rules block. In CI, the agent-sdlc diff
+checks need `--range`, because `pre-commit run --from-ref` doesn't enforce
+them. Setup order, the CI job and the `docs/` allowlist:
+<https://pavelguzenfeld.com/agent-sdlc/usage/#with-standard>
+
+## What's inside
+
+| Path | What |
+|---|---|
+| `rules/` | How to work; synced into a repo with `mutation-gate rules sync` |
+| `commands/` | Slash commands: `/kata`, `/done`, `/grill`, `/rectify` … |
+| `skills/` | On-demand playbooks: `/diagnose`, `/sol-budget`, `/verify-generated-diff` … |
+| `bin/` | Hooks and helpers: `git-guardrail.sh`, the `/say` stack |
+| `mutation_gate/` | The gate and the `mutation-gate` CLI |
+
+CI runs `scripts/no-leaks.sh` on every PR. It flags emails, RFC1918
+addresses, user-at-host references, `/home/<user>/` paths and non-personal
+`ghcr.io/` paths, and prints only `file:line`.
+
+MIT, see [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md) for one vendored
+third-party skill. Contributions: [CONTRIBUTING.md](CONTRIBUTING.md), bound
+by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Security: [SECURITY.md](SECURITY.md).

{agent_sdlc-0.3.0 → agent_sdlc-0.4.0}/mutation_gate/__init__.py

@@ -1,3 +1,3 @@
 """Diff-scoped mutation gate. Spec: PavelGuzenfeld/dotfiles#9."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{agent_sdlc-0.3.0 → agent_sdlc-0.4.0}/mutation_gate/cli.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import select
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -20,6 +21,7 @@ from .repo import CACHE_ROOT, CONFIG_NAME, GateError, discover, git, skip_reason
 
 
 TIMEOUT_FACTOR = 6.0
+STOP_HOOK_PAYLOAD_WAIT_SECONDS = 1.0
 
 
 def _emit(line: str = "") -> None:
@@ -154,10 +156,19 @@ def _gate_file(
     return blocked, survivors, cands
 
 
+def _stdin_is_ready() -> bool:
+    try:
+        readable, _, _ = select.select([sys.stdin], [], [], STOP_HOOK_PAYLOAD_WAIT_SECONDS)
+    except (ValueError, OSError):
+        return True
+    return bool(readable)
+
+
 def _stop_hook_payload() -> dict:
     """The Stop hook's JSON on stdin carries `cwd` (#68 item 1) and
-    `transcript_path` (#100) — read once, since stdin is a one-shot stream."""
-    if sys.stdin.isatty():
+    `transcript_path` (#100) — read once, since stdin is a one-shot stream.
+    An agent shell's stdin is an open pipe that never writes or closes (#337)."""
+    if sys.stdin.isatty() or not _stdin_is_ready():
         return {}
     try:
         payload = json.loads(sys.stdin.read())

{agent_sdlc-0.3.0 → agent_sdlc-0.4.0}/mutation_gate/no_leaks.py

@@ -39,6 +39,9 @@ _GIT_SSH_CLONE_RE = re.compile(
 _NPM_VERSION_RE = re.compile(
     r"(^|[^A-Za-z0-9._%+/-])[A-Za-z0-9._%+-]+@[0-9]+\.[0-9]+\.[0-9]+([^0-9.]|$)"
 )
+_CLAUDE_PLUGIN_ID_RE = re.compile(
+    r"(^|[^A-Za-z0-9._%+/-])[A-Za-z0-9._-]+@[a]gent-sdlc([^A-Za-z0-9.-]|$)"
+)
 
 _BULLET_RE = re.compile(r"^\s*-\s*")
 _ARROW = "→"
@@ -54,7 +57,8 @@ class BannedName:
 
 def _carve_out(line: str) -> str:
     line = _GIT_SSH_CLONE_RE.sub(r"\1public-git-ssh-clone-url", line)
-    return _NPM_VERSION_RE.sub(r"\1npm-package-version\2", line)
+    line = _NPM_VERSION_RE.sub(r"\1npm-package-version\2", line)
+    return _CLAUDE_PLUGIN_ID_RE.sub(r"\1claude-plugin-id\2", line)
 
 
 def generic_hit(line: str) -> bool:

{agent_sdlc-0.3.0 → agent_sdlc-0.4.0}/mutation_gate/runner.py

@@ -45,18 +45,24 @@ TERM_GRACE_SECONDS = 15.0
 
 DOCKER_RUN_RE = re.compile(r"\bdocker\s+run\b")
 
+UNWRITTEN_PYCACHE = "/nonexistent/mutation-gate-pycache"
+
 # Root in the container writes these into the bind-mounted repo as directories a
 # host user then cannot rm without starting another container (#74).
-NO_ROOT_CACHE = "-e PYTHONDONTWRITEBYTECODE=1 -e PYTEST_ADDOPTS='-p no:cacheprovider'"
+NO_ROOT_CACHE = (
+    f"-e PYTHONDONTWRITEBYTECODE=1 -e PYTHONPYCACHEPREFIX={UNWRITTEN_PYCACHE}"
+    " -e PYTEST_ADDOPTS='-p no:cacheprovider'"
+)
 
 GIT_REPO_SCOPED = ("GIT_DIR", "GIT_INDEX_FILE", "GIT_WORK_TREE")
+NO_BYTECODE = {"PYTHONDONTWRITEBYTECODE": "1", "PYTHONPYCACHEPREFIX": UNWRITTEN_PYCACHE}
 
 
 def _test_env() -> dict[str, str]:
     """The environment a repo's own command runs in. Git exports these into every
     hook and they override `-C`, so a suite that builds a temp repo stages into
     the commit being gated instead (flowdiff#83)."""
-    return {k: v for k, v in os.environ.items() if k not in GIT_REPO_SCOPED}
+    return {k: v for k, v in os.environ.items() if k not in GIT_REPO_SCOPED} | NO_BYTECODE
 
 
 @dataclass

{agent_sdlc-0.3.0 → agent_sdlc-0.4.0}/rules/tickets.md

@@ -30,6 +30,12 @@ sets it alongside the `model:*` label — the label approves, the assignee
 names who works it. An agent works only tickets assigned to the `gh` user
 it runs as, `@me`, and its PR carries that same assignee.
 
+A PR waits for CI in one foreground call — `gh pr checks <PR> --watch
+--fail-fast` or `gh run watch <run> --exit-status` — with the Bash timeout at
+its 600000 ms maximum and the output to a file, re-issued on timeout. The call
+blocks until CI settles, so no turn is spent on a status check: every turn
+re-reads the whole context.
+
 ## Follow-ups
 
 A follow-up starts from `/done`, a kata worker, any agent mid-task, or the

agent_sdlc-0.4.0/tests/test_say_narrate_bin.py

@@ -0,0 +1,35 @@
+import importlib.util
+import shutil
+from pathlib import Path
+
+MODULE_PATH = Path(__file__).resolve().parents[1] / "bin" / "say-narrate.py"
+
+
+def _load_from(path: Path):
+    spec = importlib.util.spec_from_file_location("say_narrate_probe", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_bin_is_the_scripts_own_directory_under_a_plugin_only_install(monkeypatch, tmp_path):
+    monkeypatch.delenv("CLAUDE_PLUGIN_ROOT", raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path / "home-without-claude"))
+    plugin_bin = tmp_path / "plugin" / "bin"
+    plugin_bin.mkdir(parents=True)
+    shutil.copy(MODULE_PATH, plugin_bin / "say-narrate.py")
+
+    module = _load_from(plugin_bin / "say-narrate.py")
+
+    assert module.BIN == str(plugin_bin)
+
+
+def test_bin_ignores_a_plugin_root_that_points_somewhere_else(monkeypatch, tmp_path):
+    monkeypatch.setenv("CLAUDE_PLUGIN_ROOT", "/fake/plugin/root")
+    legacy_bin = tmp_path / ".claude" / "bin"
+    legacy_bin.mkdir(parents=True)
+    (legacy_bin / "say-narrate.py").symlink_to(MODULE_PATH)
+
+    module = _load_from(legacy_bin / "say-narrate.py")
+
+    assert module.BIN == str(legacy_bin)

agent_sdlc-0.3.0/PKG-INFO

@@ -1,115 +0,0 @@
-Metadata-Version: 2.4
-Name: agent-sdlc
-Version: 0.3.0
-Summary: Diff-scoped mutation gate for pre-commit and agent Stop hooks
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/PavelGuzenfeld/agent-sdlc
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE.md
-Requires-Dist: ast-grep-cli==0.45.3
-Provides-Extra: vocabulary
-Requires-Dist: nltk; extra == "vocabulary"
-Dynamic: license-file
-
-# agent-sdlc
-
-[![CI](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml/badge.svg)](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml)
-
-A software development lifecycle shipped as agent config for Claude Code and
-Codex: rules, skills, slash commands, hooks, and a diff-scoped mutation gate.
-
-Docs: <https://pavelguzenfeld.com/agent-sdlc/>
-
-## Why
-
-A coding agent writes the code and the tests for it, and tests written next
-to the code tend to agree with it, bugs included. On a mature suite, 57% of
-real bug-class mutants survived. agent-sdlc puts that check, plus scope,
-intent and git safety, into hooks and a gate instead of leaving them to the
-agent's memory.
-
-| Problem | What catches it |
-|---|---|
-| Tests that pass but assert nothing | `mutation-gate`: a surviving mutant blocks the commit |
-| Tests shaped to the code | An adversary review that sees intent and tests, never the code |
-| Scope creep | 40-line limit without a ticket; one ticket, one branch, one PR |
-| Design notes rotting in the tree | New `.md` files are blocked; intent lives in the tracker |
-| Destructive git | A hook that denies `reset --hard`, `add -A`, force-push |
-| AI tells and leaked identity in commits | `commit-msg` and `no-leaks` hooks |
-
-## Example
-
-```python
-def is_adult(age):
-    return age >= 18
-
-def test_adult():
-    assert is_adult(30)
-
-def test_child():
-    assert not is_adult(5)
-```
-
-```text
-BLOCKED: 2 mutant(s) survived with no waiver.
-  age.py:2:11:operator:age >= 18 => age > 18
-  age.py:2:18:literal:18 => 19
-```
-
-Add `assert is_adult(18)` and `assert not is_adult(17)`, and the gate passes.
-
-## Install
-
-```bash
-git clone https://github.com/PavelGuzenfeld/agent-sdlc
-cd agent-sdlc
-./install.sh --target all --deps
-```
-
-| Want | Do |
-|---|---|
-| The whole pack | `./install.sh --target all --deps` (targets: `claude`, `codex`, `all`; `--deps=say` adds voice) |
-| Only the gate | `pip install agent-sdlc` (WordNet check: `agent-sdlc[vocabulary]`) |
-| A plugin | `claude --plugin-dir /path/to/agent-sdlc`, or add the repo as a Codex marketplace source |
-| The gate on a repo | Add `.mutation-gate.toml`, wire the pre-commit hooks |
-
-- `install.sh` links `skills/` into `~/.claude` and `~/.codex`, links
-  `commands/` and `bin/` into `~/.claude`, renders `commands/` as Codex
-  skills and merges the hooks. A second run changes nothing.
-- `ast-grep-cli` adds an `sg` shim that can shadow the system `sg`; call
-  `ast-grep`.
-
-## Use it
-
-In Claude Code (Codex: `$name` instead of `/name`):
-
-1. `./install.sh --target claude --deps`
-2. In your repo: `touch .mutation-gate.toml && mutation-gate rules sync`
-3. `claude`, then `/grill <idea>` or `gh issue create …`
-4. Approve the ticket: `gh issue edit 42 --add-label model:sonnet`
-5. `/kata 42`: a worker writes the failing test, implements, gates, opens the PR
-6. Review, then type `LGTM`: it squash-merges and cleans up
-7. `/done` to close out the session
-
-Full walkthrough, and what differs in Codex:
-<https://pavelguzenfeld.com/agent-sdlc/usage/>
-
-## What's inside
-
-| Path | What |
-|---|---|
-| `rules/` | How to work; synced into a repo with `mutation-gate rules sync` |
-| `commands/` | Slash commands: `/kata`, `/done`, `/grill`, `/rectify` … |
-| `skills/` | On-demand playbooks: `/diagnose`, `/sol-budget`, `/verify-generated-diff` … |
-| `bin/` | Hooks and helpers: `git-guardrail.sh`, the `/say` stack |
-| `mutation_gate/` | The gate and the `mutation-gate` CLI |
-
-CI runs `scripts/no-leaks.sh` on every PR. It flags emails, RFC1918
-addresses, user-at-host references, `/home/<user>/` paths and non-personal
-`ghcr.io/` paths, and prints only `file:line`.
-
-MIT, see [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md) for one vendored
-third-party skill. Contributions: [CONTRIBUTING.md](CONTRIBUTING.md), bound
-by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Security: [SECURITY.md](SECURITY.md).

agent_sdlc-0.3.0/README.md

@@ -1,100 +0,0 @@
-# agent-sdlc
-
-[![CI](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml/badge.svg)](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml)
-
-A software development lifecycle shipped as agent config for Claude Code and
-Codex: rules, skills, slash commands, hooks, and a diff-scoped mutation gate.
-
-Docs: <https://pavelguzenfeld.com/agent-sdlc/>
-
-## Why
-
-A coding agent writes the code and the tests for it, and tests written next
-to the code tend to agree with it, bugs included. On a mature suite, 57% of
-real bug-class mutants survived. agent-sdlc puts that check, plus scope,
-intent and git safety, into hooks and a gate instead of leaving them to the
-agent's memory.
-
-| Problem | What catches it |
-|---|---|
-| Tests that pass but assert nothing | `mutation-gate`: a surviving mutant blocks the commit |
-| Tests shaped to the code | An adversary review that sees intent and tests, never the code |
-| Scope creep | 40-line limit without a ticket; one ticket, one branch, one PR |
-| Design notes rotting in the tree | New `.md` files are blocked; intent lives in the tracker |
-| Destructive git | A hook that denies `reset --hard`, `add -A`, force-push |
-| AI tells and leaked identity in commits | `commit-msg` and `no-leaks` hooks |
-
-## Example
-
-```python
-def is_adult(age):
-    return age >= 18
-
-def test_adult():
-    assert is_adult(30)
-
-def test_child():
-    assert not is_adult(5)
-```
-
-```text
-BLOCKED: 2 mutant(s) survived with no waiver.
-  age.py:2:11:operator:age >= 18 => age > 18
-  age.py:2:18:literal:18 => 19
-```
-
-Add `assert is_adult(18)` and `assert not is_adult(17)`, and the gate passes.
-
-## Install
-
-```bash
-git clone https://github.com/PavelGuzenfeld/agent-sdlc
-cd agent-sdlc
-./install.sh --target all --deps
-```
-
-| Want | Do |
-|---|---|
-| The whole pack | `./install.sh --target all --deps` (targets: `claude`, `codex`, `all`; `--deps=say` adds voice) |
-| Only the gate | `pip install agent-sdlc` (WordNet check: `agent-sdlc[vocabulary]`) |
-| A plugin | `claude --plugin-dir /path/to/agent-sdlc`, or add the repo as a Codex marketplace source |
-| The gate on a repo | Add `.mutation-gate.toml`, wire the pre-commit hooks |
-
-- `install.sh` links `skills/` into `~/.claude` and `~/.codex`, links
-  `commands/` and `bin/` into `~/.claude`, renders `commands/` as Codex
-  skills and merges the hooks. A second run changes nothing.
-- `ast-grep-cli` adds an `sg` shim that can shadow the system `sg`; call
-  `ast-grep`.
-
-## Use it
-
-In Claude Code (Codex: `$name` instead of `/name`):
-
-1. `./install.sh --target claude --deps`
-2. In your repo: `touch .mutation-gate.toml && mutation-gate rules sync`
-3. `claude`, then `/grill <idea>` or `gh issue create …`
-4. Approve the ticket: `gh issue edit 42 --add-label model:sonnet`
-5. `/kata 42`: a worker writes the failing test, implements, gates, opens the PR
-6. Review, then type `LGTM`: it squash-merges and cleans up
-7. `/done` to close out the session
-
-Full walkthrough, and what differs in Codex:
-<https://pavelguzenfeld.com/agent-sdlc/usage/>
-
-## What's inside
-
-| Path | What |
-|---|---|
-| `rules/` | How to work; synced into a repo with `mutation-gate rules sync` |
-| `commands/` | Slash commands: `/kata`, `/done`, `/grill`, `/rectify` … |
-| `skills/` | On-demand playbooks: `/diagnose`, `/sol-budget`, `/verify-generated-diff` … |
-| `bin/` | Hooks and helpers: `git-guardrail.sh`, the `/say` stack |
-| `mutation_gate/` | The gate and the `mutation-gate` CLI |
-
-CI runs `scripts/no-leaks.sh` on every PR. It flags emails, RFC1918
-addresses, user-at-host references, `/home/<user>/` paths and non-personal
-`ghcr.io/` paths, and prints only `file:line`.
-
-MIT, see [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md) for one vendored
-third-party skill. Contributions: [CONTRIBUTING.md](CONTRIBUTING.md), bound
-by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Security: [SECURITY.md](SECURITY.md).

agent_sdlc-0.3.0/agent_sdlc.egg-info/PKG-INFO

@@ -1,115 +0,0 @@
-Metadata-Version: 2.4
-Name: agent-sdlc
-Version: 0.3.0
-Summary: Diff-scoped mutation gate for pre-commit and agent Stop hooks
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/PavelGuzenfeld/agent-sdlc
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE.md
-Requires-Dist: ast-grep-cli==0.45.3
-Provides-Extra: vocabulary
-Requires-Dist: nltk; extra == "vocabulary"
-Dynamic: license-file
-
-# agent-sdlc
-
-[![CI](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml/badge.svg)](https://github.com/PavelGuzenfeld/agent-sdlc/actions/workflows/ci.yml)
-
-A software development lifecycle shipped as agent config for Claude Code and
-Codex: rules, skills, slash commands, hooks, and a diff-scoped mutation gate.
-
-Docs: <https://pavelguzenfeld.com/agent-sdlc/>
-
-## Why
-
-A coding agent writes the code and the tests for it, and tests written next
-to the code tend to agree with it, bugs included. On a mature suite, 57% of
-real bug-class mutants survived. agent-sdlc puts that check, plus scope,
-intent and git safety, into hooks and a gate instead of leaving them to the
-agent's memory.
-
-| Problem | What catches it |
-|---|---|
-| Tests that pass but assert nothing | `mutation-gate`: a surviving mutant blocks the commit |
-| Tests shaped to the code | An adversary review that sees intent and tests, never the code |
-| Scope creep | 40-line limit without a ticket; one ticket, one branch, one PR |
-| Design notes rotting in the tree | New `.md` files are blocked; intent lives in the tracker |
-| Destructive git | A hook that denies `reset --hard`, `add -A`, force-push |
-| AI tells and leaked identity in commits | `commit-msg` and `no-leaks` hooks |
-
-## Example
-
-```python
-def is_adult(age):
-    return age >= 18
-
-def test_adult():
-    assert is_adult(30)
-
-def test_child():
-    assert not is_adult(5)
-```
-
-```text
-BLOCKED: 2 mutant(s) survived with no waiver.
-  age.py:2:11:operator:age >= 18 => age > 18
-  age.py:2:18:literal:18 => 19
-```
-
-Add `assert is_adult(18)` and `assert not is_adult(17)`, and the gate passes.
-
-## Install
-
-```bash
-git clone https://github.com/PavelGuzenfeld/agent-sdlc
-cd agent-sdlc
-./install.sh --target all --deps
-```
-
-| Want | Do |
-|---|---|
-| The whole pack | `./install.sh --target all --deps` (targets: `claude`, `codex`, `all`; `--deps=say` adds voice) |
-| Only the gate | `pip install agent-sdlc` (WordNet check: `agent-sdlc[vocabulary]`) |
-| A plugin | `claude --plugin-dir /path/to/agent-sdlc`, or add the repo as a Codex marketplace source |
-| The gate on a repo | Add `.mutation-gate.toml`, wire the pre-commit hooks |
-
-- `install.sh` links `skills/` into `~/.claude` and `~/.codex`, links
-  `commands/` and `bin/` into `~/.claude`, renders `commands/` as Codex
-  skills and merges the hooks. A second run changes nothing.
-- `ast-grep-cli` adds an `sg` shim that can shadow the system `sg`; call
-  `ast-grep`.
-
-## Use it
-
-In Claude Code (Codex: `$name` instead of `/name`):
-
-1. `./install.sh --target claude --deps`
-2. In your repo: `touch .mutation-gate.toml && mutation-gate rules sync`
-3. `claude`, then `/grill <idea>` or `gh issue create …`
-4. Approve the ticket: `gh issue edit 42 --add-label model:sonnet`
-5. `/kata 42`: a worker writes the failing test, implements, gates, opens the PR
-6. Review, then type `LGTM`: it squash-merges and cleans up
-7. `/done` to close out the session
-
-Full walkthrough, and what differs in Codex:
-<https://pavelguzenfeld.com/agent-sdlc/usage/>
-
-## What's inside
-
-| Path | What |
-|---|---|
-| `rules/` | How to work; synced into a repo with `mutation-gate rules sync` |
-| `commands/` | Slash commands: `/kata`, `/done`, `/grill`, `/rectify` … |
-| `skills/` | On-demand playbooks: `/diagnose`, `/sol-budget`, `/verify-generated-diff` … |
-| `bin/` | Hooks and helpers: `git-guardrail.sh`, the `/say` stack |
-| `mutation_gate/` | The gate and the `mutation-gate` CLI |
-
-CI runs `scripts/no-leaks.sh` on every PR. It flags emails, RFC1918
-addresses, user-at-host references, `/home/<user>/` paths and non-personal
-`ghcr.io/` paths, and prints only `file:line`.
-
-MIT, see [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md) for one vendored
-third-party skill. Contributions: [CONTRIBUTING.md](CONTRIBUTING.md), bound
-by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Security: [SECURITY.md](SECURITY.md).

agent_sdlc-0.3.0/tests/test_say_narrate_bin.py

@@ -1,26 +0,0 @@
-import importlib.util
-from pathlib import Path
-
-MODULE_PATH = Path(__file__).resolve().parents[1] / "bin" / "say-narrate.py"
-
-
-def _load(monkeypatch, plugin_root):
-    if plugin_root is None:
-        monkeypatch.delenv("CLAUDE_PLUGIN_ROOT", raising=False)
-    else:
-        monkeypatch.setenv("CLAUDE_PLUGIN_ROOT", plugin_root)
-    spec = importlib.util.spec_from_file_location("say_narrate_probe", MODULE_PATH)
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def test_bin_resolves_under_plugin_root_when_set(monkeypatch):
-    module = _load(monkeypatch, "/fake/plugin/root")
-    assert module.BIN == "/fake/plugin/root/bin"
-
-
-def test_bin_falls_back_to_legacy_claude_bin_when_unset(monkeypatch, tmp_path):
-    monkeypatch.setenv("HOME", str(tmp_path))
-    module = _load(monkeypatch, None)
-    assert module.BIN == str(tmp_path / ".claude" / "bin")