mutate4py 0.1.0__tar.gz

mutate4py-0.1.0/.agents/backlog.md

@@ -0,0 +1,19 @@
+# Enforcement Gate Backlog
+
+Dated proposals for mechanical enforcement gates, config changes, or CI guardrails.
+Format: `<date> | <category> | <failure-class> | <affected> | <status> | <description>`
+
+---
+2026-06-28 | swarmforge-pattern | convention-gap | specifier | pending | Glossary canon is CONTEXT.md (## Glossary) per domain-modeling skill + sibling mutate4js, but F1-F4 specifier sessions wrote entries into an orphan docs/glossary.md (nothing linked it; the two drifted). Consolidated into CONTEXT.md and deleted docs/glossary.md in F5. specifier.prompt phase 3 says "glossary entries are part of the deliverable" without naming the file — add "write glossary terms to CONTEXT.md ## Glossary, never docs/glossary.md".
+2026-06-25 | project-config | tool-error | all-roles | pending | Disable GPG commit signing in all worktrees' .git/config to eliminate 1Password SSH agent failures (git config --local commit.gpgsign false per worktree, or a global swarm setup step)
+2026-06-25 | swarmforge-pattern | tool-error | architect,cleaner | pending | 1Password SSH agent unavailable in swarm sessions causes git fetch and commit signing failures; two roles required manual workaround (-c commit.gpgsign=false); setup-swarm should disable signing in each worktree
+2026-06-25 | swarmforge-pattern | tool-error | cleaner,QA,hardender | pending | External GitHub tool installs blocked by auto-mode classifier across 3 roles; engineering.prompt needs explicit fallback rule: "if external install is blocked, use locally installed binary and continue"
+2026-06-25 | swarmforge-pattern | tool-error | cleaner,QA,hardender | pending | extract.py returns zero non-null arc content on Claude Code 2.1.191+ across all roles (5 sessions: architect, cleaner, integrator, hardender, QA); investigate JSONL format change and update extract.py
+2026-06-26 | swarmforge-pattern | tool-error | specifier,coder,cleaner,architect,hardender,QA | pending | extract.py arc null-content now confirmed across 9+ sessions and 6 roles in CC 2.1.193; this is now critical-path for all agent-retro data analysis — ESCALATE
+2026-06-26 | swarmforge-pattern | convention-gap | specifier,specifier | pending | ir-dry-checker (specifier phase 6) is not installed; two specifier sessions in this pipeline hit it; either ship the tool or reword phase 6 to manual-prune
+2026-06-26 | swarmforge-pattern | convention-gap | specifier,architect | pending | role-level tool API discovery gap: both specifier (grill-with-docs invocation failure) and architect (fc.hexaString/fc.float missing) were blocked by undocumented API surfaces; add "run --help or grep available API before using any unfamiliar tool/library function" to constitution
+2026-06-26 | swarmforge-pattern | convention-gap | cleaner,QA,integrator | pending | pre-handoff lint+format verification gap: cleaner and QA do not run ruff check+format before handing off; integrator absorbs 2+ fix-push-watch cycles per pipeline run; add mandatory pre-handoff lint+format step to engineering verification
+2026-06-26 | swarmforge-pattern | missing-artifact | coder,QA,cleaner | pending | drywall DRY check blocked by auto-mode sandbox across 3 roles attempting binary download; pre-install drywall in worktree setup or grant explicit permission in project settings.json
+2026-06-26 | swarmforge-pattern | missing-artifact | QA,cleaner | pending | merge_and_process <role> <commit> appears in handoff PAYLOADs for non-hardender roles but no such script exists; both QA and cleaner had to infer the merge intent manually; either ship the script for all roles or update handoff spec to document the convention
+2026-06-28 | swarmforge-pattern | tool-error | hardender | pending | uv re-provisioning per Gherkin mutation makes acceptance mutation slow (~10s/mutation); consider pre-provisioning worker trees once in a shared acceptance fixture or mocking _provision_worker in acceptance scenarios to avoid per-mutation cost
+2026-06-28 | swarmforge-pattern | convention-gap | integrator | pending | gh pr create blocked by auto-mode classifier even when integrator role prompt explicitly owns "Open the PR"; consider pre-authorizing integrator's gh pr create in project settings.json allowlist

mutate4py-0.1.0/.agents/ledger-project.md

@@ -0,0 +1,54 @@
+# Ledger — Project Knowledge
+
+Permanent, append-only. Contains only `promoted` and `rejected→first-occurrence` items.
+Format: `<date> | <session-id> | <role> | <failure-class> | <verdict> | <one-line summary>`
+
+---
+2026-06-25 | 9bc9e159 | architect | convention-gap | promoted→AGENTS.md | Correct role name spelling: hardender (two d's); worktree dir names are authoritative
+2026-06-25 | 9bc9e159 | architect | tool-error | rejected→first-occurrence | extract.py null-arc: all arc entries return null content on Claude Code 2.1.191
+2026-06-25 | 00466112 | cleaner | missing-artifact | promoted→AGENTS.md | drywall at /Users/gabadi/.local/bin/drywall (not in PyPI); crap4py from local sibling
+2026-06-25 | 58d11592 | integrator | tool-error | rejected→first-occurrence | extract.py null-arc: integrator session confirms pattern (same failure class)
+2026-06-25 | e4b18370 | curator | tool-error | rejected→first-occurrence | agent-retro: use grep -A50 "## Actions" instead of cat to read retros (full dump = 4-6x larger)
+2026-06-25 | ba459785 | hardender | convention-gap | promoted→.agents/roles/hardender.md | mutate4py is the mutation tool — use mutmut on this project's own test suite, not itself
+2026-06-25 | ba459785 | hardender | missing-artifact | promoted→AGENTS.md | crap4py installed from local sibling ~/workspace/addi/crap4py (not PyPI or GitHub URL)
+2026-06-25 | ba459785 | hardender | missing-artifact | rejected→first-occurrence | gherkin-mutator --help not supported; read source to find --feature flag
+2026-06-25 | 4c684992 | QA | tool-error | rejected→first-occurrence | extract.py null-arc: QA session confirms pattern (5th role reporting same failure)
+2026-06-26 | ae4e1d02 | cleaner | convention-gap | promoted→AGENTS.md | uv run mutate4py is correct invocation; uvx breaks self-referential scanning
+2026-06-26 | 93e42778 | coder | convention-gap | promoted→.agents/roles/coder.md | dead-code guard: delete stale partial impl after extracting a helper, before running tests
+2026-06-26 | 93e42778 | coder | convention-gap | rejected→first-occurrence | Gherkin label "renaming the function" ambiguous (function vs parameter rename); specifier should clarify
+2026-06-26 | 86d7f06f | hardender | convention-gap | promoted→.agents/roles/hardender.md | merge_and_process means git merge + hardening sequence, not a script on PATH
+2026-06-26 | 86d7f06f | hardender | convention-gap | promoted→.agents/roles/hardender.md | mutmut 3.x uses --max-children not --max-workers
+2026-06-26 | ba459785 | hardender | missing-artifact | promoted→AGENTS.md | gherkin-mutator flags: --feature, --generated-dir required; no --help; defaults to features/a-feature.feature
+2026-06-26 | 48c13d25 | QA | convention-gap | promoted→AGENTS.md | manifest QA fixtures are committed inputs; all manifest QA steps must use writable-copy pattern
+2026-06-26 | 14e97446 | specifier | convention-gap | promoted→AGENTS.md | gherkin-parser requires two args: gherkin-parser <feature-file> <json-output>
+2026-06-26 | d24200ea | architect | convention-gap | promoted→AGENTS.md | _coverage.py must not import _discovery.py; IO-near code must not depend on IO-free domain types
+2026-06-26 | b2aa029b | cleaner | convention-gap | promoted→AGENTS.md | acceptance step files are boundary files (15-site threshold); pure logic belongs in *_helpers.py modules
+2026-06-26 | b2aa029b | cleaner | convention-gap | promoted→AGENTS.md | coverage_helpers.py is testable module for acceptance step helper functions; tests in tests/test_coverage_helpers.py
+2026-06-26 | b2aa029b | cleaner | convention-gap | rejected→first-occurrence | agent-retro step 5: scan site list for per-pattern contributors before starting boundary-file mutation-site reduction
+2026-06-26 | c53799e5 | architect | tool-error | rejected→first-occurrence | fork agent stalled (600s) when dispatched for open-ended architectural review with large inherited context
+2026-06-26 | 0fe93f63 | coder | convention-gap | promoted→AGENTS.md | gherkin-parser must be called without rtk prefix; rtk breaks it
+2026-06-26 | 0fe93f63 | coder | convention-gap | promoted→AGENTS.md | generate_acceptance.py: pass just module_name, not acceptance.steps.module_name
+2026-06-26 | 0fe93f63 | coder | convention-gap | promoted→AGENTS.md | strip+modify+re-embed pattern: when modifying source with embedded manifest, strip first then re-embed
+2026-06-26 | bb18021c | architect | convention-gap | rejected→first-occurrence | apply_mutant must stay in _discovery.py alongside Site and line-index helpers; do not re-extract
+2026-06-26 | f72497fa | cleaner | convention-gap | promoted→AGENTS.md | mutate4py --scan accepts one file at a time; loop over files separately
+2026-06-26 | da863ce7 | hardender | convention-gap | promoted→.agents/roles/hardender.md | mutmut run takes mutant-name patterns, not file paths; use bare mutmut run to run all
+2026-06-26 | da863ce7 | hardender | convention-gap | promoted→AGENTS.md | runner_adapter.py must be executable (chmod +x) before gherkin-mutator can use it
+2026-06-26 | da863ce7 | hardender | convention-gap | promoted→.agents/references/equivalent-mutants.md | five equivalent mutant categories for this project (falsy None, argparse dest, help-text, single-comma DA, single-op compare)
+2026-06-28 | 976a22ac | hardender | convention-gap | promoted→.agents/roles/hardender.md | mutmut v3 module-path filtering fails (AssertionError); always run `mutmut run --max-children 8` first to populate stats before filtering
+2026-06-28 | 976a22ac | hardender | convention-gap | promoted→.agents/roles/hardender.md | gherkin-mutator uses --feature <path> (named), not positional; check Clojure source at /tmp/aps-build/bb/... if CLI unclear
+2026-06-28 | dc019dd9 | cleaner | convention-gap | promoted→.agents/roles/cleaner.md | boundary file 15-site threshold is a trigger not hard gate; document irreducible minimum when all testable logic is extracted
+2026-06-28 | dc019dd9 | cleaner | convention-gap | promoted→.agents/roles/cleaner.md | when writing test for refactored function, verify error message strings match new implementation — do not copy from old code
+2026-06-28 | a80e933d | integrator | convention-gap | promoted→.agents/roles/QA.md | QA must run ruff check+format before handoff (recurrence of 9fd9fe97); QA.md created with pre-handoff verification rule
+2026-06-28 | 4f7feec9 | QA | convention-gap | promoted→.agents/roles/QA.md | before marking QA done, grep run_acceptance.sh for every *_qa.feature and confirm QA_STEPS_MAP entry exists; silent skip masks test failures
+2026-06-28 | 3d5cea42 | coder | convention-gap | promoted→.agents/roles/coder.md | check for run_acceptance.sh wrapper before invoking acceptance generation scripts directly; scripts require positional args and fail silently
+2026-06-28 | 3814e69e | cleaner | convention-gap | promoted→.agents/roles/cleaner.md | manifest "NEW" hashes after coder handoff are expected; do not hand-edit — mutation tool refreshes them on first scan
+2026-06-28 | 8c38deb4 | architect | convention-gap | promoted→AGENTS.md | __main__.py is CLI adapter only; scan_report/scan_report_with_coverage/update_manifest belong in _runner.py and are tested directly
+2026-06-28 | dc019dd9 | cleaner | convention-gap | promoted→AGENTS.md | cli_surface_helpers.py is testable module for CLI surface step helpers; tests in tests/test_cli_surface_helpers.py
+2026-06-28 | 7b3678f5 | architect | tool-error | rejected→first-occurrence | agent-retro: $CLAUDE_SKILL_DIR not set in harness; extract.py path resolution requires find fallback
+2026-06-28 | 3b4f8734 | hardender | convention-gap | promoted→.agents/roles/hardender.md | git checkout <file> after mutmut apply discards all local changes; save with git stash or patch before restoring
+2026-06-28 | 3b4f8734 | hardender | convention-gap | promoted→.agents/roles/hardender.md | always regenerate acceptance entrypoints after modifying step handlers before running gherkin-mutator
+2026-06-28 | 3b4f8734 | hardender | convention-gap | promoted→.agents/roles/hardender.md | gherkin-mutator --workers N requires concurrent runner; runner_adapter.py is single-process; always use --workers 1
+2026-06-28 | 3b4f8734 | hardender | convention-gap | promoted→.agents/references/equivalent-mutants.md | _cmd.run_command capture_output variants and _copy_tree follow_symlinks=None/True are equivalent mutants
+2026-06-28 | 5707a6e5 | coder | convention-gap | promoted→.agents/roles/coder.md | merge from hardener/cleaner can silently revert API contracts; diff public signatures before running tests
+2026-06-28 | 19ff3fa9 | QA | convention-gap | promoted→.agents/roles/QA.md | QA harness must handle CLI-rejected values (e.g. --max-workers 0) without changing CLI validator
+2026-06-28 | 19ff3fa9 | QA | convention-gap | promoted→.agents/roles/QA.md | shell counter files in acceptance steps must use PID not $COUNT; run_parallel cleans run-PID/ not workers/ parent

mutate4py-0.1.0/.agents/ledger-swarmforge.md

@@ -0,0 +1,68 @@
+# Ledger — SwarmForge Items
+
+Work queue for swarmforge-scoped retro actions, prunable.
+Format: `<date> | <session-id> | <role> | <failure-class> | <verdict> | <status> | <one-line summary>`
+
+---
+2026-06-25 | 9bc9e159 | architect | tool-error | promoted→ledger-swarmforge | pending | SSH/1Password signing failure: determine if swarm sessions should disable GPG signing by default
+2026-06-25 | 9bc9e159 | architect | convention-gap | promoted→ledger-swarmforge | pending | Constitution should list canonical role names to eliminate lookup errors
+2026-06-25 | 00466112 | cleaner | tool-error | promoted→ledger-swarmforge | pending | crap4py external install blocked by auto-mode; needs permission pre-approval or fallback rule
+2026-06-25 | 00466112 | cleaner | tool-error | promoted→ledger-swarmforge | pending | GPG commit fallback: document -c commit.gpgsign=false workaround for 1Password failures
+2026-06-25 | 58d11592 | integrator | missing-artifact | promoted→ledger-swarmforge | pending | gtimeout not on macOS; use gh pr checks --watch bare or install coreutils
+2026-06-25 | e4b18370 | curator | tool-error | promoted→ledger-swarmforge | pending | gh pr create blocked by auto-mode classifier; consider adding to curator allowed commands
+2026-06-25 | a9efd9cb | coder | convention-gap | promoted→ledger-swarmforge | pending | CLI flag names must be cross-checked against feature files before writing step handlers
+2026-06-25 | a9efd9cb | coder | convention-gap | promoted→ledger-swarmforge | pending | Write CLI step handlers when feature mixes API+CLI scenarios
+2026-06-25 | a9efd9cb | coder | convention-gap | promoted→ledger-swarmforge | pending | Regex step patterns capture concrete values not Gherkin placeholder names
+2026-06-25 | ba459785 | hardender | convention-gap | promoted→ledger-swarmforge | pending | Engineering rules mutation table: exception when project IS the mutation tool
+2026-06-25 | 4c684992 | QA | tool-error | promoted→ledger-swarmforge | pending | External tool install blocked by sandbox; add fallback-to-local-binary rule to engineering.prompt
+2026-06-26 | 34b59cea | specifier | convention-gap | promoted→ledger-swarmforge | pending | Specifier phase 3: for faithful-port features, exhaust upstream source before grilling the user
+2026-06-26 | 34b59cea | specifier | convention-gap | promoted→ledger-swarmforge | pending | Contradiction: grill-with-docs skill is disable-model-invocation:true but role says run it autonomously
+2026-06-26 | 34b59cea | specifier | missing-artifact | promoted→ledger-swarmforge | pending | ir-dry-checker (specifier phase 6) not installed; reword phase or provide the tool
+2026-06-26 | 34b59cea | specifier | tool-error | promoted→ledger-swarmforge | pending | git reset --hard blocked by auto-mode classifier in specifier startup; ready_for_next.sh should own sync
+2026-06-26 | ae4e1d02 | cleaner | convention-gap | promoted→ledger-swarmforge | pending | uv run mutate4py is correct (not uvx); uvx isolates env and breaks self-referential scanning
+2026-06-26 | 86d7f06f | hardender | convention-gap | promoted→ledger-swarmforge | pending | merge_and_process directive meaning not documented in hardender role; caused 2 extra tool calls
+2026-06-26 | 86d7f06f | hardender | convention-gap | promoted→ledger-swarmforge | pending | mutmut 3.x uses --max-children, not --max-workers; role prompt used wrong flag name
+2026-06-26 | 48c13d25 | QA | convention-gap | promoted→ledger-swarmforge | pending | git merge origin/<branch> fails for fetched branches; always use local branch name in merge commands
+2026-06-26 | f5e87210 | architect | convention-gap | promoted→ledger-swarmforge | pending | Handoff recipient typed from memory instead of conf lookup; already in AGENTS.md but not in architect role checklist
+2026-06-26 | f5e87210 | architect | convention-gap | promoted→ledger-swarmforge | pending | Before writing fast-check property tests, grep Object.keys(fc) to avoid unknown-arbitrary failures (fc.hexaString, fc.float 32-bit)
+2026-06-26 | 14e97446 | specifier | missing-artifact | promoted→ledger-swarmforge | pending | ir-dry-checker (phase 6) not installed; manual prune required; not recorded so future specifiers hunt for it again
+2026-06-26 | c53799e5 | architect | tool-error | promoted→ledger-swarmforge | pending | Fork agent stalled (600s watchdog) for architectural review; large swarm-persona context may cause fork hang on open-ended tasks
+2026-06-26 | 416dbe9a | cleaner | convention-gap | promoted→ledger-swarmforge | pending | When CRAP/DRY tools recorded as unavailable in memory/AGENTS.md, engineering startup should allow skipping with one-line note
+2026-06-26 | 416dbe9a | cleaner | convention-gap | promoted→ledger-swarmforge | pending | --update-manifest not yet implemented; cleaner should note manifest will be stale after src edits until a full run
+2026-06-26 | 9fd9fe97 | integrator | convention-gap | promoted→ledger-swarmforge | pending | QA role: before handing off, run ruff check --fix && ruff format and commit if any changes; prevents integrator fix cycles
+2026-06-26 | 9fd9fe97 | integrator | convention-gap | promoted→ledger-swarmforge | pending | Integrator: after gh pr merge, if error contains "cannot delete branch" (worktree conflict), treat as success and continue
+2026-06-26 | 9fd9fe97 | integrator | convention-gap | promoted→ledger-swarmforge | pending | Verify both ruff check and ruff format in local verification; both are separate CI steps
+2026-06-26 | eeab6b91 | QA | convention-gap | promoted→ledger-swarmforge | pending | QA verification: generate coverage LCOV before running crap4py (two-step: uv run coverage run then uv run coverage lcov)
+2026-06-26 | a6cab6bf | coder | convention-gap | promoted→ledger-swarmforge | pending | Scope find to src/ or specific subtree, never project root; venv noise bloats results by 50-100x
+2026-06-26 | 38ff0a59 | hardender | convention-gap | promoted→ledger-swarmforge | pending | After commit exit-code 128 with signing error, run git log to check if commit succeeded before retrying
+2026-06-26 | 4d4d0ea3 | integrator | convention-gap | promoted→ledger-swarmforge | pending | gh pr view without PR number resolves to current branch (swarmforge-integrator), not the feature branch; always pass explicit PR number
+2026-06-26 | 4d4d0ea3 | integrator | convention-gap | promoted→ledger-swarmforge | pending | gh pr comment may be blocked in auto-mode; include diagnosis inline in PR body/description as first-choice fallback
+2026-06-26 | 61ee6b27 | integrator | convention-gap | promoted→ledger-swarmforge | pending | Integrator: run ruff check && ruff format locally before pushing to confirm all issues resolved in single commit
+2026-06-26 | b0229ad6 | QA | missing-artifact | promoted→ledger-swarmforge | pending | QA DRY check: drywall binary download blocked by auto-mode; note SKIPPED if blocked and continue (binary may already exist at ~/.local/bin/drywall)
+2026-06-26 | d638c7e4 | QA | convention-gap | promoted→ledger-swarmforge | pending | Stale untracked test artifacts from prior QA sessions may exist in worktree root; prefer git stash -u over rm in auto-mode
+2026-06-26 | f585b9ac | architect | convention-gap | promoted→ledger-swarmforge | pending | Fork review prompts for src/ architectural review should include test/ property test files to catch type errors in test consumers
+2026-06-26 | 4d4d0ea3 | integrator | convention-gap | promoted→ledger-swarmforge | pending | After gh pr create fails with "already exists", capture PR URL from error output and continue with post-create gate
+2026-06-26 | 04c94859 | hardender | convention-gap | promoted→ledger-swarmforge | pending | Hardender: before first mutation run on a file, verify embedManifest format produces valid TS (/* */ wrapped JSON, not raw JSON)
+2026-06-26 | 04c94859 | hardender | convention-gap | promoted→ledger-swarmforge | pending | For TS/Bun mutation: use scoped test command per file (bun test test/X.test.ts) not full bun test — 6-8x speedup
+2026-06-26 | 52201f30 | coder | convention-gap | promoted→ledger-swarmforge | pending | Integrator handoff payload should signal "verify and forward" vs "implement" to disambiguate passthrough sessions
+2026-06-26 | fc5d7a74 | cleaner | convention-gap | promoted→ledger-swarmforge | pending | When adding type aliases, place them after all import statements, never between import blocks
+2026-06-26 | 0fe93f63 | coder | convention-gap | promoted→ledger-swarmforge | pending | Coder: before delegating implementation to a fork, run existing unit tests to confirm green baseline; prevents misattributing pre-existing failures
+2026-06-26 | b79e3962 | coder | convention-gap | promoted→ledger-swarmforge | pending | When spec text and spec examples contradict, trust examples first; validate algorithm against examples before overriding a fork's working implementation
+2026-06-26 | fc327d2f | QA | missing-artifact | promoted→ledger-swarmforge | pending | merge_and_process in PAYLOAD is not a script on PATH for non-hardender roles; all roles must infer: fetch+merge the named commit then run role-specific sequence
+2026-06-26 | 38acb0d3 | specifier | convention-gap | promoted→ledger-swarmforge | pending | Completion-cycle git_handoffs reuse fresh-spec payload template, giving no explicit "cycle done" signal; consider a distinct completion-notification type in handoff spec
+2026-06-28 | 8c38deb4 | architect | convention-gap | promoted→ledger-swarmforge | pending | Before moving domain functions out of a module, grep tests for direct imports of those function names; prevents post-hoc test-contract repair
+2026-06-28 | 8c38deb4 | architect | convention-gap | promoted→ledger-swarmforge | pending | Read existing test signatures for the old function before designing new API — don't discover test contract after implementing
+2026-06-28 | 8c38deb4 | architect | convention-gap | promoted→ledger-swarmforge | pending | Extend dependency-rule review phase to include test-import check for functions being moved before touching source file
+2026-06-28 | c6b84c63 | architect | convention-gap | promoted→ledger-swarmforge | pending | Think before Edit: if unsure whether a change is correct, articulate why before calling Edit — edit→revert pairs waste turns
+2026-06-28 | 4f7feec9 | QA | tool-error | promoted→ledger-swarmforge | pending | tool_result_sizes in extract.py output is a dict (keyed by tool name), not a list; retro SKILL.md Step 5 uses sizes[:5] list slice syntax — schema mismatch causes KeyError
+2026-06-28 | 5c32a862 | specifier | convention-gap | promoted→ledger-swarmforge | pending | When request names a flag/behavior the spec marks removed/locked, frontier brief must flag it as a reopenable assumption and ask; do not plan around spec stance as settled
+2026-06-28 | 5c32a862 | specifier | convention-gap | promoted→ledger-swarmforge | pending | When a decision reverses, grep for every assertion of the reversed fact across the whole contract (not just the named section) before claiming done
+2026-06-28 | b52f13f5 | specifier | convention-gap | promoted→ledger-swarmforge | pending | Default to terse Q→one-line-A when user signals non-expertise or confusion; offer depth on demand; lead dense explanations only when expertise is established
+2026-06-28 | b52f13f5 | specifier | convention-gap | promoted→ledger-swarmforge | pending | AskUserQuestion should follow shared mental model; if user answers options with new prerequisite questions, drop to prose and re-ask once rather than re-prompting same decision
+2026-06-28 | 3814e69e | cleaner | missing-artifact | promoted→ledger-swarmforge | pending | drywall binary download blocked in auto-mode again (cleaner); pre-install drywall in worktree setup or grant permission in settings.json (duplicate pattern, escalate)
+2026-06-28 | c8748468 | hardender | tool-error | promoted→ledger-swarmforge | pending | RTK swallows stdout when underlying process calls process.exit(1) before writing; use bare command without rtk when zero output is unexpected
+2026-06-28 | c8748468 | hardender | convention-gap | promoted→ledger-swarmforge | pending | Before writing handoff to: field, verify role name case with ls swarmforge/roles/ — names are case-sensitive (QA not qa)
+2026-06-28 | c8748468 | hardender | convention-gap | promoted→ledger-swarmforge | pending | Do not bun add -d <local-path> tools to package.json for analysis — install ephemerally, run tool, then revert package.json and bun.lock with git checkout --
+2026-06-28 | 5707a6e5 | coder | convention-gap | promoted→ledger-swarmforge | pending | After merge-result handoff, diff public function signatures of touched modules against pre-merge state before running tests
+2026-06-29 | eaa9acfe | integrator | convention-gap | promoted→ledger-swarmforge | pending | Integrator: explicit git push -u origin feat/<initiative> step must precede gh pr create; push is not implicit
+2026-06-29 | eaa9acfe | integrator | convention-gap | promoted→ledger-swarmforge | pending | Before pushing to CI, run both ruff check --fix AND ruff format in a single pass (they are separate CI steps)

mutate4py-0.1.0/.agents/references/equivalent-mutants.md

@@ -0,0 +1,21 @@
+# Equivalent Mutant Categories — mutate4py Project
+
+Recognized equivalent mutant patterns for this project. Surviving mutants in these categories do NOT need new tests — they are structurally equivalent for all valid inputs.
+
+## Categories (from hardender session da863ce7, 2026-06-26)
+
+1. **Falsy None vs False init** — replacing `None` with `False` (or vice versa) in initialization where the code only tests truthiness; both evaluate identically.
+
+2. **argparse `dest=None`** — `dest` in argparse derives from the flag name; `dest=None` vs `dest="<flag>"` produces the same attribute name at runtime.
+
+3. **Help-text mutations** — mutations inside `help="..."` strings for argparse arguments; help text has no behavioral effect.
+
+4. **Single-comma DA lines with different `maxsplit`** — `_parse_da_line` mutations on lines that have exactly one comma; split with `maxsplit=1` or without produces the same result.
+
+5. **Compare between-text with single operator occurrence** — `_mutate_compare` mutations where the between-text region contains exactly one operator; replace-first and replace-all are equivalent.
+
+## Additional Categories (from hardender session 3b4f8734, 2026-06-28)
+
+6. **`_cmd.run_command` `capture_output` variants** — mutants 5, 10, 13 in `_cmd.py`; `capture_output=True/False` variants produce identical behavior for the project's test inputs.
+
+7. **`_copy_tree` `follow_symlinks=None/True`** — mutants 13, 14; the only distinction is for symlinks-to-directories, which crash with `IsADirectoryError` on both variants in the current call sites.

mutate4py-0.1.0/.agents/roles/QA.md

@@ -0,0 +1,16 @@
+# QA Role — Operational Knowledge
+
+## Pre-Handoff Lint and Format Check
+Before handing off, MUST run `uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/`. Fix any failures before handoff. Do not hand off with lint or format violations — integrator absorbs CI fix cycles.
+
+## QA Feature Step Wiring
+Before marking QA done, grep `acceptance/run_acceptance.sh` for every `*_qa.feature` file present in `features/`. Confirm each has a `QA_STEPS_MAP` entry. A missing `QA_STEPS_MAP` entry causes silent `SKIP QA: no steps module for X` output — the feature is silently skipped and failures are masked.
+
+## QA Harness: Handling CLI-Rejected Values (e.g. --max-workers 0)
+When a QA feature passes a value that the CLI rejects (e.g., `--max-workers 0` to test serial mode), handle it in `_run_qa_cmd` — not by changing the CLI validator. Changing the CLI validator to accept test-only values breaks the cli-surface acceptance test.
+
+## Shell Counter Files in Acceptance Steps
+Shell scripts in acceptance steps must not use `$COUNT` from `ls dir | wc -l` as unique file names with parallel workers — it is not safe under concurrency. Use `$$` (PID) or content-based detection (grep for a token in the worker's source copy) instead.
+
+## Worker Directory Cleanup Assertions
+`run_parallel` cleans up `run-PID-NANOS/` (the run-specific subdirectory) but leaves the `workers/` parent directory. Assertions must check for empty run subdirs, not for the absence of `workers/`.

mutate4py-0.1.0/.agents/roles/cleaner.md

@@ -0,0 +1,10 @@
+# Cleaner Role — Operational Knowledge
+
+## Boundary File Irreducible Minimum
+The 15-mutation-site threshold is a trigger, not a hard gate. When all extractable testable logic is in `*_helpers.py` and remaining sites are Context class methods, subprocess calls, and guard clauses, document as "irreducible boundary minimum" and proceed. Do not loop indefinitely trying to reach 15.
+
+## Test Error Messages Must Match New Implementation
+When writing a test for a refactored function, verify expected error message strings match the new implementation before committing. Do not copy message strings from old code — refactored functions may use different error strings.
+
+## Manifest "NEW" Hashes After Coder Handoff
+When manifest entries show "NEW" hashes and stale line numbers after a coder handoff, this is expected — the mutation tool refreshes them on first scan. Do not hand-edit manifest entries; skip to cleanup work.

mutate4py-0.1.0/.agents/roles/coder.md

@@ -0,0 +1,10 @@
+# Coder Role — Operational Knowledge
+
+## Dead-Code Guard After Refactor
+After extracting a helper function from a function body, immediately delete all stale local variables, intermediate loops, and partial implementations before running tests. Do not rely on test failures (NameError, etc.) to surface dead code — it should be removed proactively as part of the refactor step.
+
+## Acceptance Convenience Wrapper
+Before invoking acceptance generation steps manually (`generate_acceptance.py`, `runner_adapter.py`), check for `acceptance/run_acceptance.sh` first — it is the correct entry point and handles sequencing. Calling generation scripts directly without required args fails silently or with cryptic errors.
+
+## Merge Handoff: Verify Public API Signatures
+After receiving a merge-result handoff (hardener or cleaner branch merged onto a feature branch), diff the public function signatures of all touched modules against their pre-merge state before running tests. A merge can silently revert API contract changes (e.g., function signature, return type); in a dynamically-typed project this manifests as a runtime TypeError, not a compile error.

mutate4py-0.1.0/.agents/roles/hardender.md

@@ -0,0 +1,32 @@
+# Hardender Role — Operational Knowledge
+
+## Mutation Tool for This Project
+This project (mutate4py) is self-hosted — it generates and checks its own mutation manifests. Use `uv run mutate4py` (not `uvx mutate4py`; uvx isolates the env and breaks self-referential scanning).
+
+Key commands:
+- `uv run mutate4py src/ --check-manifest` — verify all manifests are current (CI gate; exits 0 if current, 1 if missing/stale)
+- `uv run mutate4py <file> --scan` — scan a single file and print surviving mutants
+- `uv run mutate4py <file> --update-manifest` — regenerate and embed a file's manifest
+
+`--scan`, `--update-manifest`, and `--check-manifest` are mutually exclusive. `--scan` and `--update-manifest` accept exactly ONE file; for multi-file operations loop over files or use a directory with `--check-manifest`.
+
+## CRAP Tool
+crap4py is installed from local sibling `~/workspace/addi/crap4py` via `uv tool install ~/workspace/addi/crap4py`, not from PyPI or GitHub URL.
+
+## merge_and_process Directive
+`merge_and_process <role> <commit>` in a handoff payload is NOT a script on PATH. It means: run `git merge <commit>` in the hardender worktree, then execute the standard hardening sequence (unit → acceptance → property tests → mutation manifest check → Gherkin mutation → CRAP → DRY).
+
+## gherkin-mutator Named Arguments
+gherkin-mutator uses `--feature <path>` (named option), not a positional argument. Check `/tmp/aps-build/bb/src/aps/cli/gherkin_mutator.clj` source if CLI is unclear.
+
+## Restoring Files After Manual Mutation Debugging
+After manually editing a source file to simulate a mutant for debugging, restore with `git checkout <file>` ONLY if no other local changes exist in that file. If you have local edits (e.g. a DRY fix, refactor), first save them: `git stash` (or `git diff > patch.diff && git checkout <file> && git apply patch.diff`). `git checkout <file>` discards ALL unstaged and staged changes, not just the mutation.
+
+## Regenerate Acceptance Entrypoints After Step Handler Changes
+After modifying any acceptance step handler file (`*_steps.py`), regenerate the acceptance entrypoints via `gherkin-parser` + `generate_acceptance.py` BEFORE running `gherkin-mutator`. Stale generated entrypoints cause all 19+ mutations to error.
+
+## gherkin-mutator --workers
+`runner_adapter.py` is concurrent (ThreadPoolExecutor, default 4 workers via `RUNNER_WORKERS` env var). Use `--workers 4` with gherkin-mutator. For all features in parallel, use `acceptance/run_gherkin_mutation.sh`.
+
+## Equivalent Mutant Categories (Python)
+See `.agents/references/equivalent-mutants.md` for recognized equivalent mutant patterns that do not need test coverage.

mutate4py-0.1.0/.agents/skills/agent-retro/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: agent-retro
+description: Run a conversation retrospective — analyze what happened in this session, what worked, what didn't, and propose concrete improvements. Use when the user says "retro", "retrospective", "what happened in this session", "session review", "what did we do", "analyze this conversation", or when wrapping up a long session. Especially useful after using a skill you're developing. In swarmforge: invoked automatically as the last step before each role goes idle.
+compatibility: Primary — requires `entire` CLI (0.6.2+) for transcript extraction. Fallback — Claude Code ~/.claude/projects/ path. Python 3.8+ for the extraction script.
+metadata:
+  author: gabadi/swarm-forge (fork of giannimassi/agent-retro)
+  version: "0.1.0"
+---
+
+# agent-retro
+
+## Step 1 — Extract Session Data
+
+**Primary path (entire):**
+The extractor script lives next to this SKILL.md at `scripts/extract.py`. Resolve its directory portably (Claude Code sets `$CLAUDE_SKILL_DIR`; pi does not):
+```bash
+EXTRACT="${CLAUDE_SKILL_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)/..}/scripts/extract.py"; [ -f "$EXTRACT" ] || EXTRACT="scripts/extract.py"
+```
+If neither resolves, ask the operator for the path to this skill's `scripts/extract.py`.
+
+1. Run `entire session current --json` to get the active session ID and worktree path.
+2. Check: does `worktree_path` in the result match `$PWD`?
+   - If **NO** (stale result — wrong repo or ended session) → skip `entire session info` entirely; go to **JSONL fallback** below.
+   - If **YES** → proceed:
+     - Run `entire session info <id> --transcript > /tmp/retro-session.jsonl`
+     - Verify: `python3 "$EXTRACT" /tmp/retro-session.jsonl --metadata-only`
+     - If verification succeeds, run full extraction: `python3 "$EXTRACT" /tmp/retro-session.jsonl --summary > /tmp/retro-extract.json`
+     - Proceed to Step 2 with `/tmp/retro-extract.json`.
+
+**JSONL fallback:**
+Use when: `entire` is not installed, `entire session current` returns no session, or `worktree_path` does not match `$PWD`. The fallback depends on the harness — `extract.py` auto-detects the format from the first line (`{"type":"session"` → pi; otherwise Claude Code).
+
+**Claude Code fallback:**
+1. Find the Claude Code project dir for this worktree: `ls ~/.claude/projects/ | grep <last-segment-of-PWD>`. Note: dot-prefixed segments encode as double-dash (`.worktrees` → `--worktrees`), so do not use naive `sed` — use `grep` on the last path segment instead.
+2. Take the most recently modified `.jsonl` in that dir: `ls -t ~/.claude/projects/<encoded-cwd>/*.jsonl | head -1`.
+
+**pi fallback:**
+pi stores sessions under `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`. The encoding wraps the cwd with `--` and replaces every `/`, `\`, and `:` with `-` (so `/Users/gabadi/.agents-skills` → `--Users-gabadi-.agents-skills--`). Dot-prefixed segments are **single**-dashed (`.worktrees/coder` → `-worktrees-coder`), unlike Claude's double-dash — do not reuse the Claude encoding.
+1. Encode `$PWD` the same way and locate the dir:
+   ```bash
+   ENCODED="--$(echo "$PWD" | sed 's|^[/\\]||; s|[/\\:]|-|g')--"
+   ls -t ~/.pi/agent/sessions/"$ENCODED"/*.jsonl | head -1
+   ```
+   If the encoded lookup misses, fall back to `ls ~/.pi/agent/sessions/ | grep "$(basename "$PWD")"` to find the right dir.
+2. The most recently modified `.jsonl` in that dir is the current/last session.
+
+**Then (both harnesses):**
+3. Verify: `python3 "$EXTRACT" <path> --metadata-only`
+4. Run full extraction: `python3 "$EXTRACT" <path> --summary > /tmp/retro-extract.json`
+
+The pi parser produces the same schema as the Claude parser (`conversation_arc`, `tokens.total`, `tokens.estimated_cost_usd`, `tool_result_sizes`, `tools`). `tokens.total` uses the same key names (`input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`) mapped from pi's `usage.{input,output,cacheWrite,cacheRead}`. Cost comes from pi's own `usage.cost.total` when present.
+
+**If no transcript is found:** Report "No session transcript found" and stop. Do not fabricate data.
+
+Raw JSONL is 1MB+ per session — never stream transcript bytes inline into context. Always write to a temp file and pass the path to extract.py.
+
+**Null-arc guard:** Before using the arc, check whether content is populated:
+```bash
+python3 -c "
+import json
+d = json.load(open('/tmp/retro-extract.json'))
+arc = d.get('conversation_arc', [])
+non_null = sum(1 for e in arc if e.get('text') or e.get('content'))
+print(f'arc entries: {len(arc)}, non-null content: {non_null}')
+"
+```
+(Both the Claude and pi parsers populate `text`; the guard checks `text` or `content` for compatibility.)
+If `non_null == 0` and `len(arc) > 0`, `extract.py` silently failed. Fall back to **in-context reconstruction**: write the retro from live session memory — (1) what tool calls succeeded first try, (2) what failed or needed retries, (3) any user corrections or redirects, (4) token budget marked as `(unavailable — extract.py returned no cost data)`. Do not fabricate metrics.
+
+---
+
+## Step 2 — Read the Conversation Arc
+
+Read `conversation_arc` from `/tmp/retro-extract.json`. This is the full story of the session: every user message and assistant response in order.
+
+Identify:
+- User corrections ("no, not that", "stop", "undo", "wrong")
+- Redirects (user changing direction mid-task)
+- Repeated instructions (same request given more than once)
+- Pivots (abandoned approaches)
+- Friction moments (back-and-forth on a single point)
+
+---
+
+## Step 3 — Classify Outcomes
+
+Classify what the session produced:
+- New code / feature
+- Bug fix
+- Communication (messages, comments, docs)
+- Setup / configuration changes
+- Spec or design artifact
+- Process improvement
+- Review or analysis
+- Research
+- Skill development
+
+A session may have multiple outcomes.
+
+---
+
+## Step 4 — Analyze What Worked
+
+Identify:
+- First-try successes (task completed without corrections)
+- Efficient delegation (agents dispatched with clear scope)
+- Good skill matches (right skill for the task)
+- Clean conversation flow (no redirects)
+- Smart tool choice (right tool, right scope)
+
+---
+
+## Step 5 — Analyze What Didn't Work
+
+Identify friction patterns:
+- User corrections, redirects, repetitions, stops, frustration signals
+- Wasted agent dispatches (dispatched but result unused)
+- Oversized tool results (large reads never referenced)
+- Tool call retries (same tool called multiple times for the same target)
+- Abandoned approaches (started, then discarded)
+- Over-engineering (more than the task required)
+- Under-specification (task started with insufficient context)
+
+For skill-development retros: read the active SKILL.md (the `${CLAUDE_SKILL_DIR}/SKILL.md` of the skill being developed, or this skill's own `SKILL.md` resolved as above) and identify which instruction caused each friction.
+
+Read `tool_result_sizes` from the extract — flag any tool result over 50KB that was followed by no further reference to that file.
+
+---
+
+## Step 6 — Propose Actions
+
+Lead with the defense-first question: **"What defensive rule did this session's work absorb that future maintainers must keep intact?"** Answer it before cataloging friction — rule-shaped learnings surface before cause-shaped ones.
+
+Capture-first guard: enumerate every candidate learning from Steps 4–5 in full before writing anything to the retro file. Do not filter for "obviousness" or "self-correcting" here — capture everything; the curation stage downstream owns discards.
+
+For each friction pattern, propose one of these action types:
+- `skill-update` — change an existing skill. Include before/after text.
+- `skill-create` — create a new skill.
+- `rule-update` — change a rule or instruction in CLAUDE.md or a role prompt.
+- `rule-create` — create a new rule.
+- `setup-change` — change a configuration or environment setting.
+- `memory-update` — update or create a memory entry.
+- `investigate` — flag something for human review (uncertain root cause).
+- `acknowledge` — nothing to change; note what worked well.
+
+Be specific. "Improve X" is not a proposal. "Change the wording in Step 3 from Y to Z" is a proposal.
+
+**Scope** — tag every proposed action with exactly one scope value:
+- `project` — knowledge about the target project (its code, config, tools, conventions).
+- `swarmforge` — knowledge about the harness itself (role prompts, constitution, scripts, pipeline mechanics).
+- `skill` — a reusable procedure that should become or amend a skill.
+- `ephemeral` — true one-offs; recorded for audit, never promoted.
+
+---
+
+## Step 7 — Write the Retro File
+
+Write to `~/.claude/worklog/retros/YYYY-MM-DD-<slug>.md` where `<slug>` is a 3–5 word kebab-case summary of the session.
+
+Structure:
+```markdown
+# Session Retro: <slug>
+Date: YYYY-MM-DD
+Session ID: <id>
+Role: <swarmforge role name, or "interactive" outside a swarm>
+Branch: <branch>
+Duration: <N>m
+Cost: $<N>
+
+## Token Budget
+| Category | Tokens | Cost |
+|---|---|---|
+| Input | N | $N |
+| Output | N | $N |
+| Cache create | N | $N |
+| Cache read | N | $N |
+| **Total** | **N** | **$N** |
+
+## Tool Result Waste
+<table of oversized unused tool results, or "None detected">
+
+## What Worked
+<bullet list>
+
+## What Didn't Work
+<bullet list with root cause per item>
+
+## Actions
+| # | Type | Scope | Description | Target |
+|---|------|-------|-------------|--------|
+| 1 | skill-update | project | ... | ... |
+```
+
+---
+
+## Step 8 — Walk Through Actions
+
+Determine the mode:
+
+**Interactive session (a human is present):**
+- Present the retro file path and summary counts (N worked, N didn't work, N actions).
+- Walk through each proposed action one by one: show type, scope, description, target. Ask: "Apply? [y/n/defer]". Apply approved actions immediately; mark deferred/skipped in the table.
+- After the walkthrough, show the final action table with statuses.
+
+**Autonomous session (swarmforge role, no human in the loop):**
+- Do not ask anything. Do not apply any action.
+- Mark every action's status as `pending-curation` in the table and finish the retro file.
+- The curator role consumes the file downstream; your only job is complete, well-tagged capture.
+
+---
+
+## Step 9 — Preemptive Handoff Recommendation
+
+Check `session` metadata from the extract:
+- If `turn_count` > 500, `duration_seconds` > 14400 (4h), or `estimated_cost_usd` > 300:
+  - Add a `investigate` action: "Session size threshold reached — consider handoff"
+  - Include two ready-to-paste prompts:
+    - For `/compact`: "Continue from: <brief state summary>"
+    - For `/clear`: "Resume from: <brief state summary> — key context: <3 bullet points>"