autonomous-coding-toolkit 1.0.0

package/docs/plans/audit-findings.md

@@ -0,0 +1,186 @@
+# Hardening Pass Audit Findings
+
+> Generated: 2026-02-21 | Batches 1-2 of hardening pass
+
+---
+
+## Shellcheck Findings
+
+### Notes (SC1091 — source not followed)
+
+These are informational — shellcheck can't follow relative `source` paths without `-x` flag. Not actionable.
+
+| File | Line | Code | Description | Disposition |
+|------|------|------|-------------|-------------|
+| `scripts/run-plan.sh` | 17 | SC1091 | Not following: `./lib/run-plan-parser.sh` | SUPPRESS — relative source, use `-x` flag |
+| `scripts/run-plan.sh` | 18 | SC1091 | Not following: `./lib/run-plan-state.sh` | SUPPRESS — same |
+| `scripts/run-plan.sh` | 19 | SC1091 | Not following: `./lib/run-plan-quality-gate.sh` | SUPPRESS — same |
+| `scripts/run-plan.sh` | 20 | SC1091 | Not following: `./lib/run-plan-notify.sh` | SUPPRESS — same |
+| `scripts/run-plan.sh` | 21 | SC1091 | Not following: `./lib/run-plan-prompt.sh` | SUPPRESS — same |
+
+### Warnings
+
+| File | Line | Code | Description | Disposition |
+|------|------|------|-------------|-------------|
+| `scripts/run-plan.sh` | 111 | SC2034 | `COMPETITIVE_BATCHES` appears unused | SUPPRESS — used by sourced lib modules |
+| `scripts/run-plan.sh` | 123 | SC2034 | `MAX_BUDGET` appears unused | SUPPRESS — used by sourced lib modules |
+| `scripts/run-plan.sh` | 305 | SC1007 | Remove space after `=` in `CLAUDECODE= claude` | SUPPRESS — intentional: unsetting env var for subcommand |
+| `scripts/lesson-check.sh` | 20 | SC2034 | `lesson_severity` appears unused | FIX — either use it or remove from parse output |
+| `scripts/entropy-audit.sh` | 28 | SC2034 | `FIX_MODE` appears unused | FIX — parsed but never checked; add `--fix` implementation or remove |
+| `scripts/lib/run-plan-quality-gate.sh` | 65 | SC2034 | `passed` appears unused | FIX — declared but never read |
+
+### Info/Style
+
+| File | Line | Code | Description | Disposition |
+|------|------|------|-------------|-------------|
+| `scripts/setup-ralph-loop.sh` | 112 | SC2086 | Double quote to prevent globbing/word splitting: `$MAX_ITERATIONS` | FIX — quote variable |
+| `scripts/auto-compound.sh` | 73 | SC2012 | Use `find` instead of `ls` for non-alphanumeric filenames | FIX — replace `ls -t` with `find`+`sort` |
+| `scripts/entropy-audit.sh` | 73 | SC2016 | Expressions don't expand in single quotes | SUPPRESS — intentional: regex pattern uses literal `$` |
+| `scripts/entropy-audit.sh` | 201 | SC2016 | Expressions don't expand in single quotes | SUPPRESS — same, grep pattern with literal backticks |
+| `scripts/entropy-audit.sh` | 214 | SC2012 | Use `find` instead of `ls` | FIX — replace `ls` with `find` |
+| `scripts/lib/run-plan-parser.sh` | 32 | SC2295 | Expansions inside `${..}` need separate quoting | FIX — quote inner expansion |
+| `hooks/stop-hook.sh` | 78 | SC2181 | Check exit code directly instead of `$?` | FIX — restructure to `if ! cmd; then` |
+
+---
+
+## Summary
+
+| Severity | Total | FIX | SUPPRESS |
+|----------|-------|-----|----------|
+| Note (SC1091 source) | 5 | 0 | 5 |
+| Warning | 6 | 3 | 3 |
+| Info/Style | 7 | 5 | 2 |
+| **Total** | **18** | **8** | **10** |
+
+---
+
+## Lesson Scanner Results
+
+### lesson-check.sh against shell scripts
+
+```
+Target: scripts/*.sh, scripts/lib/*.sh, hooks/stop-hook.sh (15 files)
+Result: lesson-check: clean
+Exit code: 0
+```
+
+All shell scripts pass — expected since lessons target Python/JS patterns.
+
+### lesson-check.sh against Python/JS/TS files
+
+```
+Target: find . -name "*.py" -o -name "*.js" -o -name "*.ts"
+Result: No matching files found
+```
+
+This is a pure bash toolkit — no Python/JS/TS source files exist. Lesson scanner has no applicable targets.
+
+### Conclusion
+
+No lesson violations found. The toolkit's bash-only codebase is not covered by the current syntactic lesson set (which targets Python/JS). Future work: add bash-specific lessons (e.g., unquoted variables, missing `set -euo pipefail`).
+
+---
+
+## Lesson File Schema Validation (Batch 2)
+
+### Method
+
+Validated all 6 lesson files (`docs/lessons/0001-*.md` through `0006-*.md`) against the schema defined in `docs/lessons/TEMPLATE.md`.
+
+**Required fields checked:**
+- `id` (integer), `title` (non-empty), `severity` (blocker|should-fix|nice-to-have)
+- `languages` (array or `all`), `category` (enum of 6 values)
+- `pattern.type` (syntactic|semantic), `pattern.regex` (required if syntactic), `pattern.description`
+- `fix` (non-empty), `example.bad` (non-empty), `example.good` (non-empty)
+
+### Schema Results
+
+| File | id | severity | category | pattern.type | regex | All fields | Status |
+|------|----|----------|----------|-------------|-------|------------|--------|
+| `0001-bare-exception-swallowing.md` | 1 | blocker | silent-failures | syntactic | `^\s*except\s*:` | ✓ | PASS |
+| `0002-async-def-without-await.md` | 2 | blocker | async-traps | semantic | N/A | ✓ | PASS |
+| `0003-create-task-without-callback.md` | 3 | should-fix | silent-failures | semantic | N/A | ✓ | PASS |
+| `0004-hardcoded-test-counts.md` | 4 | should-fix | test-anti-patterns | syntactic | `assert.*==\s*\d+\|...` | ✓ | PASS |
+| `0005-sqlite-without-closing.md` | 5 | should-fix | silent-failures | syntactic | `sqlite3\.connect\(` | ✓ | PASS |
+| `0006-venv-pip-path.md` | 6 | should-fix | integration-boundaries | syntactic | `\.venv/bin/pip\b` | ✓ | PASS |
+
+**6/6 lesson files pass schema validation.** All required fields present, all enum values valid.
+
+### Regex Compilation Results
+
+Tested all 4 syntactic lesson regex patterns with `grep -P`:
+
+| Lesson | Regex | Compiles | Status |
+|--------|-------|----------|--------|
+| 0001 | `^\s*except\s*:` | ✓ | PASS |
+| 0004 | `assert.*==\s*\d+\|expect\(.*\)\.toBe\(\d+\)\|assert_equal.*\d+` | ✓ | PASS |
+| 0005 | `sqlite3\.connect\(` | ✓ | PASS |
+| 0006 | `\.venv/bin/pip\b` | ✓ | PASS |
+
+**4/4 syntactic regex patterns compile successfully** (grep -P exit code 0 or 1).
+
+### Observations
+
+- All lessons use valid enum values for `severity` and `category`
+- Semantic lessons (0002, 0003) correctly omit `regex` field
+- ID sequence is contiguous (1-6) with no gaps
+- No issues found — lesson schema is clean
+
+---
+
+## Manifest & Frontmatter Validation (Batch 2)
+
+### JSON Manifest Validation
+
+| File | Valid JSON | Required Fields | Status |
+|------|-----------|----------------|--------|
+| `.claude-plugin/plugin.json` | ✓ | name, description, version, author | PASS |
+| `.claude-plugin/marketplace.json` | ✓ | N/A (list format) | PASS |
+| `hooks/hooks.json` | ✓ | N/A (event-keyed) | PASS |
+
+**3/3 JSON files pass validation.**
+
+### Skill Frontmatter Validation
+
+Checked all 15 skills for required fields: `name`, `description`, `version`.
+
+| Skill | name | description | version | Status |
+|-------|------|-------------|---------|--------|
+| `brainstorming` | ✓ | ✓ | 1.0.0 | PASS |
+| `dispatching-parallel-agents` | ✓ | ✓ | 1.0.0 | PASS |
+| `executing-plans` | ✓ | ✓ | 1.0.0 | PASS |
+| `finishing-a-development-branch` | ✓ | ✓ | 1.0.0 | PASS |
+| `receiving-code-review` | ✓ | ✓ | 1.0.0 | PASS |
+| `requesting-code-review` | ✓ | ✓ | 1.0.0 | PASS |
+| `subagent-driven-development` | ✓ | ✓ | 1.0.0 | PASS |
+| `systematic-debugging` | ✓ | ✓ | 1.0.0 | PASS |
+| `test-driven-development` | ✓ | ✓ | 1.0.0 | PASS |
+| `using-git-worktrees` | ✓ | ✓ | 1.0.0 | PASS |
+| `using-superpowers` | ✓ | ✓ | 1.0.0 | PASS |
+| `verification-before-completion` | ✓ | ✓ | 1.0.0 | PASS |
+| `verify` | ✓ | ✓ | 1.0.0 | PASS |
+| `writing-plans` | ✓ | ✓ | 1.0.0 | PASS |
+| `writing-skills` | ✓ | ✓ | 1.0.0 | PASS |
+
+**15/15 skills pass frontmatter validation.**
+
+### Command Frontmatter Validation
+
+Checked all 6 commands for YAML frontmatter with `description` field (command name derives from filename).
+
+| Command | Frontmatter | description | Status |
+|---------|-------------|-------------|--------|
+| `cancel-ralph.md` | ✓ | ✓ | PASS |
+| `code-factory.md` | ✓ | ✓ | PASS |
+| `create-prd.md` | ✓ | ✓ | PASS |
+| `ralph-loop.md` | ✓ | ✓ | PASS |
+| `run-plan.md` | ✓ | ✓ | PASS |
+| `submit-lesson.md` | ✓ | ✓ | PASS |
+
+**6/6 commands pass frontmatter validation.**
+
+### Observations
+
+- All skills at version 1.0.0 — consistent versioning
+- Command files use `description` (not `name`) in frontmatter — name comes from filename per Claude Code convention
+- No missing or malformed frontmatter found across any file type

package/docs/telegram-notification-format.md

@@ -0,0 +1,98 @@
+# Telegram Notification Format
+
+Standard notification templates for `run-plan.sh` and Code Factory pipeline execution.
+
+## STARTED
+
+Sent once at pipeline launch.
+
+```
+🔧 <Feature Name> - STARTED
+
+Project: <project-name>
+Plan: <plan-filename>.md
+Repo: github.com/parthalon025/<repo-name>
+
+<N> batches, <M> tasks:
+- B1: <batch title>
+- B2: <batch title>
+- ...
+
+Running headless with retry on failure.
+```
+
+## Batch Complete (Success)
+
+Sent after each batch passes the quality gate.
+
+```
+✅ <Feature Name> — B<N>/<total> complete (<duration>s)
+
+*<Batch Title>*
+
+Tasks completed:
+• T<N>: <description of what was built/changed>
+• T<N+1>: <description>
+• ...
+
+Tests: <file count> files, <assertion count> assertions (↑<delta>)
+Quality gate: PASSED
+
+Errors during batch: <none | list>
+Lessons triggered: <none | lesson IDs>
+
+B<N+1> starting: <next batch title>
+```
+
+## Batch Complete (Failure)
+
+Sent when a batch fails after all retries.
+
+```
+❌ <Feature Name> — B<N>/<total> FAILED
+
+*<Batch Title>*
+
+Attempt <N> of <max>:
+Error: <error description>
+Quality gate: FAILED (<reason>)
+
+Errors captured:
+• <specific error 1>
+• <specific error 2>
+
+Lessons triggered: <lesson IDs if applicable>
+Action: <retry|stop|skip>
+```
+
+## COMPLETED
+
+Sent when all batches finish.
+
+```
+🏁 <Feature Name> - COMPLETED
+
+Project: <project-name>
+Duration: <total time>
+
+Batches: <N>/<N> passed
+Tests: <final count> (<total delta from start>)
+Commits: <commit count>
+
+Errors during run:
+• B1: <none | error summary>
+• B2: <none | error summary>
+• ...
+
+Lessons triggered: <none | lesson IDs and descriptions>
+```
+
+## Key Fields
+
+| Field | Source | Purpose |
+|-------|--------|---------|
+| Tasks completed | Batch commit diff | What was built — not what was planned |
+| Tests | `run-all-tests.sh` output | File count + assertion delta |
+| Errors during batch | Quality gate output, retry logs | What went wrong |
+| Lessons triggered | `lesson-check.sh` output | Anti-patterns detected in new code |
+| Duration | `.run-plan-state.json` durations | Wall clock per batch |

package/examples/example-plan.md

@@ -0,0 +1,51 @@
+# Example Implementation Plan
+
+> This is an example plan file that `run-plan.sh` can parse and execute.
+> The parser looks for `## Batch N:` headers to split batches and `### Task M:` for individual tasks.
+
+## Batch 1: Project Setup
+
+### Task 1: Initialize project structure
+
+Create the basic directory layout:
+- `src/` — source code
+- `tests/` — test files
+- `pyproject.toml` with pytest configuration
+
+### Task 2: Add configuration module
+
+Create `src/config.py`:
+- Load settings from environment variables
+- Provide defaults for development
+- Add `tests/test_config.py` with basic tests
+
+## Batch 2: Core Implementation
+
+### Task 3: Implement data parser
+
+Create `src/parser.py`:
+- Parse CSV input files into structured records
+- Handle malformed rows gracefully (log + skip, don't crash)
+- Add `tests/test_parser.py` covering: valid input, empty input, malformed rows
+
+### Task 4: Implement transformer
+
+Create `src/transformer.py`:
+- Transform parsed records into output format
+- Support configurable field mapping
+- Add `tests/test_transformer.py`
+
+## Batch 3: Integration and CLI
+
+### Task 5: Wire components together
+
+Create `src/pipeline.py`:
+- Connect parser → transformer → output writer
+- Add end-to-end test: CSV in → transformed output verified
+
+### Task 6: Add CLI entry point
+
+Create `src/cli.py`:
+- Accept input file and output file arguments
+- Report progress to stderr
+- Add `tests/test_cli.py` testing argument parsing and error cases

package/examples/example-prd.json

@@ -0,0 +1,72 @@
+[
+  {
+    "id": 1,
+    "title": "Create project structure",
+    "description": "Initialize directory layout with src/, tests/, and pyproject.toml",
+    "acceptance_criteria": [
+      "test -d src",
+      "test -d tests",
+      "test -f pyproject.toml",
+      "grep -q 'pytest' pyproject.toml"
+    ],
+    "passes": false,
+    "blocked_by": []
+  },
+  {
+    "id": 2,
+    "title": "Add configuration module",
+    "description": "Create src/config.py that loads settings from environment variables with sensible defaults",
+    "acceptance_criteria": [
+      "test -f src/config.py",
+      "python3 -c 'from src.config import Settings; s = Settings(); assert s is not None'",
+      "pytest tests/test_config.py -x"
+    ],
+    "passes": false,
+    "blocked_by": [1]
+  },
+  {
+    "id": 3,
+    "title": "Implement data parser",
+    "description": "Parse CSV input files into structured records with graceful error handling",
+    "acceptance_criteria": [
+      "test -f src/parser.py",
+      "pytest tests/test_parser.py -x",
+      "pytest tests/test_parser.py -k 'malformed' -x"
+    ],
+    "passes": false,
+    "blocked_by": [1]
+  },
+  {
+    "id": 4,
+    "title": "Implement transformer",
+    "description": "Transform parsed records into output format with configurable field mapping",
+    "acceptance_criteria": [
+      "test -f src/transformer.py",
+      "pytest tests/test_transformer.py -x"
+    ],
+    "passes": false,
+    "blocked_by": [3]
+  },
+  {
+    "id": 5,
+    "title": "Wire end-to-end pipeline",
+    "description": "Connect parser, transformer, and output writer into a single pipeline",
+    "acceptance_criteria": [
+      "test -f src/pipeline.py",
+      "pytest tests/test_pipeline.py -x"
+    ],
+    "passes": false,
+    "blocked_by": [3, 4]
+  },
+  {
+    "id": 6,
+    "title": "Run full quality gate",
+    "description": "Ensure all tests pass and no anti-patterns exist in the codebase",
+    "acceptance_criteria": [
+      "pytest tests/ -x",
+      "scripts/lesson-check.sh src/*.py"
+    ],
+    "passes": false,
+    "blocked_by": [1, 2, 3, 4, 5]
+  }
+]

package/examples/example-roadmap.md

@@ -0,0 +1,33 @@
+# Roadmap: User Management System
+
+Generated: 2026-02-24
+
+## Features (dependency order)
+
+### Phase 1: Foundation
+| # | Feature | Complexity | Risk | Dependencies |
+|---|---------|-----------|------|-------------|
+| 1 | Database schema and migrations | moderate | low | none |
+| 2 | Authentication API (JWT) | moderate | medium | none |
+
+### Phase 2: Core
+| # | Feature | Complexity | Risk | Dependencies |
+|---|---------|-----------|------|-------------|
+| 3 | User CRUD endpoints | moderate | low | #1 |
+| 4 | Role-based access control | complex | medium | #2, #3 |
+
+### Phase 3: Polish
+| # | Feature | Complexity | Risk | Dependencies |
+|---|---------|-----------|------|-------------|
+| 5 | Admin dashboard UI | moderate | low | #3, #4 |
+
+## Dependency Graph
+```
+1 ──→ 3 ──→ 4 ──→ 5
+2 ──────→ 4
+```
+
+## Total Estimate
+- Features: 5
+- Phases: 3
+- Estimated sessions: 5-8

package/examples/quickstart-plan.md

@@ -0,0 +1,63 @@
+# Quickstart Plan: Hello World with Quality Gate
+
+A minimal 2-batch plan demonstrating the toolkit's core loop: write test → implement → quality gate → next batch.
+
+## Batch 1: Setup and first test
+
+### Task 1: Create project structure
+
+Create the following files:
+
+- `src/hello.sh` — a bash script that prints "Hello, World!"
+- `tests/test-hello.sh` — a test that verifies the output
+
+```bash
+# src/hello.sh
+#!/usr/bin/env bash
+echo "Hello, World!"
+```
+
+```bash
+# tests/test-hello.sh
+#!/usr/bin/env bash
+set -euo pipefail
+
+output=$(bash src/hello.sh)
+if [[ "$output" == "Hello, World!" ]]; then
+    echo "PASS: hello output correct"
+else
+    echo "FAIL: expected 'Hello, World!', got '$output'"
+    exit 1
+fi
+```
+
+Make both executable: `chmod +x src/hello.sh tests/test-hello.sh`
+
+Run: `bash tests/test-hello.sh` — expect PASS.
+
+## Batch 2: Add parameterized greeting
+
+### Task 2: Accept a name argument
+
+Update `src/hello.sh` to accept an optional name argument:
+- `bash src/hello.sh` → "Hello, World!"
+- `bash src/hello.sh Alice` → "Hello, Alice!"
+
+### Task 3: Add test for parameterized greeting
+
+Add a second test case to `tests/test-hello.sh` that verifies `bash src/hello.sh Alice` outputs "Hello, Alice!".
+
+Run: `bash tests/test-hello.sh` — expect both PASS.
+
+## Running This Plan
+
+```bash
+# Headless (fully autonomous)
+scripts/run-plan.sh examples/quickstart-plan.md
+
+# In-session (with review between batches)
+/run-plan examples/quickstart-plan.md
+
+# Resume if interrupted
+scripts/run-plan.sh --resume
+```

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "description": "Autonomous Coding Toolkit hooks — setup and Ralph loop",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/setup-symlinks.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/setup-symlinks.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# setup-symlinks.sh — Auto-create ~/.local/bin symlinks on first session
+# Runs via SessionStart hook. Guard file prevents re-running after initial setup.
+set -euo pipefail
+
+PLUGIN_ROOT="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)"
+GUARD_FILE="${PLUGIN_ROOT}/.symlinks-installed"
+BIN_DIR="${HOME}/.local/bin"
+
+# Skip if already done
+[[ -f "$GUARD_FILE" ]] && exit 0
+
+# Ensure bin dir exists
+mkdir -p "$BIN_DIR"
+
+# Scripts to expose on PATH (user-facing CLI tools only)
+SCRIPTS=(
+    run-plan
+    quality-gate
+    lesson-check
+    policy-check
+    research-gate
+    auto-compound
+    entropy-audit
+    batch-audit
+    batch-test
+    mab-run
+    scope-infer
+    pipeline-status
+    setup-ralph-loop
+)
+
+installed=0
+for name in "${SCRIPTS[@]}"; do
+    script="${PLUGIN_ROOT}/scripts/${name}.sh"
+    link="${BIN_DIR}/${name}"
+    if [[ -f "$script" ]] && [[ ! -e "$link" ]]; then
+        ln -sf "$script" "$link"
+        installed=$((installed + 1))
+    fi
+done
+
+# Mark as done
+touch "$GUARD_FILE"
+
+if [[ $installed -gt 0 ]]; then
+    echo "Autonomous Coding Toolkit: installed $installed commands to ~/.local/bin"
+fi