cortexhawk 3.1.1 → 3.3.0

package/.cortexhawk-lint.yml.example

@@ -0,0 +1,21 @@
+# .cortexhawk-lint.yml — per-project lint-guard config (optional)
+# Copy to .cortexhawk-lint.yml to override defaults.
+# By default, all tools are auto-detected via their config files.
+# Set a tool to false to disable it even if its config file is present.
+
+formatters:
+  prettier: true      # .prettierrc* / prettier.config.* / package.json "prettier"
+  black: true         # pyproject.toml [tool.black]
+  gofmt: true         # active if .go files staged (no config file required)
+  rustfmt: true       # rustfmt.toml / .rustfmt.toml
+  stylelint: true     # .stylelintrc* / stylelint.config.*
+
+linters:
+  eslint: true        # .eslintrc* / eslint.config.*
+  flake8: true        # .flake8 / setup.cfg [flake8]
+  mypy: false         # pyproject.toml [tool.mypy] / mypy.ini — set to false to disable (can be slow)
+
+options:
+  run_on_push: false       # run on git push too (overrides LINT_ON_PUSH in git-workflow.conf)
+  fail_on_formatter: false # block commit if a formatter fails (default: non-blocking)
+  timeout: 30              # max seconds per tool (requires timeout/gtimeout in PATH)

package/.gitmessage

@@ -0,0 +1,10 @@
+
+# type(scope): subject
+#
+# Types: feat, fix, docs, style, refactor, test, chore, perf, security
+# Scope: optional module/component name
+# Subject: imperative mood, lowercase, no period, max 72 chars
+#
+# Body: explain WHY, not WHAT (the diff shows the what)
+#
+# Footer: BREAKING CHANGE: description | Closes #123 | Backlog #N

package/CHANGELOG.md

@@ -3,12 +3,57 @@
 All notable changes to CortexHawk are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/)
 
-## [3.1.1] - 2026-02-15
+## [Unreleased]
+
+## [3.3.0] - 2026-02-19
+
+### Added
+- `lint-guard` Phase 3 performance: linters run in parallel (`&` + `wait` + tmpdir error signaling); detection results cached in `.claude/lint-guard-cache` (1hr TTL, safe key=value); hook extracted to `scripts/lint-guard-runner.sh` to stay within 150-line limit (#142)
+- `lint-guard` advanced YAML options: `timeout` (per-tool kill with `timeout`/`gtimeout`, default 30s), `fail_on_formatter` (block commit on formatter failure, default false), `run_on_push` in yml (overrides git-workflow.conf) (#141)
+- `lint-guard` pre-commit delegation: if `.pre-commit-config.yaml` + `pre-commit` CLI are present, lint-guard delegates entirely to the framework — no duplication for projects already using pre-commit (#143)
+- `lint-guard` hook (PreToolUse): auto-detects formatters and linters on staged files before commit — formatters auto-fix + re-stage (prettier, black, gofmt, rustfmt, stylelint), linters check-only + block on errors (eslint, flake8, mypy); opt-out via `LINT_SKIP` in `git-workflow.conf` or `.cortexhawk-lint.yml` (#140)
+- `/review-pr` command: fetch, triage, and address PR review comments — batch mode by default (one commit + one batched review reply = one notification); `--sequential` flag for complex interdependent threads (#145)
+- MCP GitHub config: `mcp/github.json` (`@modelcontextprotocol/server-github`) — unlocks native GitHub API for `git-manager`, `/ship`, `pr-review-comments`, `/review-pr`; listed as recommended in fullstack + api profiles (#146)
+- `/cleanup` command: delete merged local/remote branches, optional post-merge hook for auto-cleanup after PR merges (#139)
+- Smart PR detection in `/ship`: reuses existing PR branch instead of creating duplicate branches when iterating with `/task` followed by review feedback (#138)
+
+### Fixed
+- `branch-guard` hook: `git push --delete` (remote branch deletion) was incorrectly blocked when on a protected branch — `/cleanup` remote cleanup now works correctly
+- `post-merge-cleanup.sh`: auto-detects missing TTY (`[ ! -t 0 ]`) and switches to auto mode — `/cleanup` called via Claude Bash tool or CI no longer hangs on `read` prompt
+- `.gitignore`: add `docs/.context/` and `docs/.metrics/` — auto-generated session artifacts (snapshots, analytics logs, agent context) are ephemeral and should not be committed
+- GitHub Actions (`claude.yml`, `claude-code-review.yml`): grant `pull-requests: write` + `issues: write` — Claude could read PRs but not post reviews or replies
+- **Security (MEDIUM)**: replace predictable PID/timestamp temp paths with `mktemp` (portable, no `.json` suffix) in `autodetect-profile.sh` and `interactive-init.sh`
+- **Security (MEDIUM)**: extend `.env` parser blocklist (`PYTHONPATH`, `GIT_SSH_COMMAND`, `NPM_CONFIG_*`, `NODE_OPTIONS`, `RUBYLIB`, `LD_AUDIT`, etc.) + add key format validation (`^[A-Z_][A-Z0-9_]{0,63}$`) to reject malformed variable names
+- **Security (LOW)**: atomic `cache_set` in `lint-guard-runner.sh` via `mktemp` unique tmp + `mv` — eliminates race condition on concurrent hook invocations
+- **Security**: replace `eval` with `xargs -0` in `lint-guard-runner.sh` — prevents command injection via crafted filenames in staged file lists
+
+## [3.2.0] - 2026-02-15
+
+### Added
+- Component registry: `COMPONENTS` array + `copy_all_components`/`sync_all_components`/`count_component_files` — adding a new component is 1 line instead of modifying 5 functions
+- `/commit` command: lightweight conventional commit + push without review or PR — use `/ship` for full workflow, `/commit` for quick iterations
+- Install auto-detects existing PR/commit templates; generates CortexHawk defaults (`.github/PULL_REQUEST_TEMPLATE.md`, `.gitmessage`) if missing — agents (`git-manager`, `/ship`, `/commit`) read templates at runtime
+- `--version` / `-v` flag: displays CortexHawk version
+- `scripts/refresh-context.sh`: regenerates `docs/.context/_shared.md` mid-session — `/task` and `/backlog` auto-refresh after modifying backlog
 
 ### Fixed
 - `branch-guard` / `commit-guard` hooks: JSON parsing via `jq` with regex fallback — fixes false "hook error" on commands containing quotes or HEREDOC
 - `commit-guard`: multi-format commit message extraction (HEREDOC, single/double quotes)
 - `file-guard`: match on basename only — `*secret*`/`*credentials*` no longer false-positive on legitimate files (e.g., `oauth_service.py`); `.env.example`/`.env.sample`/`.env.template` whitelisted; `docker-compose*.yml` unblocked
+- **Security**: eliminate shell injection in all Python HEREDOC/inline scripts — `$hooks_json`, file paths, and user input no longer interpolated into Python source; uses `sys.argv`/`sys.stdin` instead. Hook names validated against path traversal, hook paths shell-escaped via `shlex.quote()`
+- Portable `sed -i` via `sed_inplace()` helper — fixes `sed` failures on macOS (BSD) across snapshot, hook toggle, and init wizard
+- Argument validation for `--target`, `--profile`, and `--restore` flags — prevents cryptic shell errors when value is missing
+- `update_gitignore()` now ensures essential entries (`.env`, `node_modules/`, `dist/`, etc.) are present — previously only added `.claude/` to an existing `.gitignore`
+- Warning when python3 is not found — `generate_hooks_config()` previously failed silently, now alerts user that static fallback is used
+- `.env` parser now strips single quotes, inline comments, and trailing whitespace — previously only stripped double quotes
+- `--init` wizard now supports "All" and "Auto-detect" targets — removed false `--target all/auto` + `--init` guards, scope step auto-selects local for multi-target
+- Snapshot no longer reads stale `/tmp/cortexhawk-custom-*.json` from previous runs — uses `$PROFILE_FILE` from current session only
+- `copy_skills()` now warns when a skill from the profile doesn't exist in source — previously silently skipped
+- Removed `local` keyword used outside function in `--target auto` dispatcher — fixes portability issues
+- `.gitignore` no longer duplicates `# CortexHawk` header with `--target all` — groups all target dirs under single header
+- `SKILL_COUNT` no longer shows 1 when no skills detected — fixed `wc -l` on empty string in `autodetect-profile.sh`
+- `_shared.md` now includes generation timestamp for staleness awareness
+- `settings.json` now merges on reinstall instead of skipping — new hooks regenerated from compose.yml, new permissions added via union (user customizations preserved). `--update` also merges new permissions
 
 ## [3.1.0] - 2026-02-14
 

package/CLAUDE.md

@@ -6,13 +6,13 @@ Open-source development toolkit for Claude Code — optimized agents, skills, co
 
 ```
 agents/       — 20 specialized AI agents
-commands/     — 32 slash commands
+commands/     — 35 slash commands
 scripts/      — Validation and post-install audit scripts
 skills/       — 36 domain-specific knowledge modules
-hooks/        — 9 lifecycle hooks
+hooks/        — 11 lifecycle hooks
 modes/        — 7 behavioral presets
 profiles/     — 3 install profiles (fullstack, api, data)
-mcp/          — Pre-configured MCP server configs
+mcp/          — Pre-configured MCP server configs (github, context7, sequential-thinking, puppeteer)
 docs/         — Agent outputs (brainstorms, plans, decisions, research, audits, conversations, chains)
 templates/    — Templates for contributing new components (agents, commands, skills, chain presets, personas)
 CONTRIBUTING.md — Contribution guidelines
@@ -49,7 +49,7 @@ Custom agents in `.cortexhawk-agents/` at project root. Each `.md` file uses `ex
 
 ## Commands
 
-`/plan` `/build` `/test` `/review` `/ship` `/debug` `/scan` `/check` `/refactor` `/research` `/doc` `/bootstrap` `/tdd` `/optimize` `/migrate` `/monitor` `/api-gen` `/changelog` `/journal` `/brainstorm` `/simplify` `/deploy` `/export` `/backlog` `/pulse` `/map` `/learn` `/chain` `/task` `/ci` `/context` `/upgrade`
+`/plan` `/build` `/test` `/review` `/review-pr` `/ship` `/commit` `/cleanup` `/debug` `/scan` `/check` `/refactor` `/research` `/doc` `/bootstrap` `/tdd` `/optimize` `/migrate` `/monitor` `/api-gen` `/changelog` `/journal` `/brainstorm` `/simplify` `/deploy` `/export` `/backlog` `/pulse` `/map` `/learn` `/chain` `/task` `/ci` `/context` `/upgrade`
 
 ## Skills
 
@@ -80,6 +80,7 @@ Custom agents in `.cortexhawk-agents/` at project root. Each `.md` file uses `ex
 - `file-guard` (PreToolUse) — Blocks access to .env, secrets, keys
 - `branch-guard` (PreToolUse) — Prevents direct push to protected branches
 - `commit-guard` (PreToolUse) — Validates conventional commits, checks staged secrets
+- `lint-guard` (PreToolUse) — Auto-detects formatters/linters on staged files; auto-fix for prettier/black/gofmt/rustfmt/stylelint, check-only for eslint/flake8/mypy
 - `self-review` (PostToolUse) — Checks for TODO/FIXME, secrets, debug artifacts
 - `dependency-check` (PostToolUse) — Alerts when dependency files are modified
 - `test-reminder` (PostToolUse) — Reminds to update tests for modified source files
@@ -94,3 +95,10 @@ Custom agents in `.cortexhawk-agents/` at project root. Each `.md` file uses `ex
 - Checklists > paragraphs, code examples > prose
 - One responsibility per component
 - All agents follow: frontmatter → description → Process → Output Format → Rules
+
+## Git Workflow
+
+- **Branching**: dev-branch (working branch: dev)
+- **Commits**: conventional
+- **PR preference**: on-demand
+- **Auto-push**: after-commit

package/README.md

@@ -2,22 +2,35 @@
 
 [![GitHub stars](https://img.shields.io/github/stars/Spechawk94/CortexHawk?style=flat-square)](https://github.com/Spechawk94/CortexHawk/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.1.0-green.svg?style=flat-square)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.2.0-green.svg?style=flat-square)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/cortexhawk?style=flat-square&color=red)](https://www.npmjs.com/package/cortexhawk)
 [![Skills](https://img.shields.io/badge/skills-36%20built--in%20%7C%2087k%2B%20via%20SkillsMP-orange.svg?style=flat-square)](https://skillsmp.com)
-[![Components](https://img.shields.io/badge/20%20agents%20%7C%2032%20commands%20%7C%209%20hooks%20%7C%207%20modes-purple.svg?style=flat-square)](#whats-inside)
+[![Components](https://img.shields.io/badge/20%20agents%20%7C%2033%20commands%20%7C%209%20hooks%20%7C%207%20modes-purple.svg?style=flat-square)](#whats-inside)
 
 An open-source, community-driven development toolkit for Claude Code.
 
 CortexHawk provides a modular collection of optimized agents, skills, commands, hooks, and behavioral modes that transform Claude Code into a full-stack development team. Every prompt has been written for maximum efficiency — less token bloat, sharper instructions, better agent coordination.
 
-### What's New in v3.1
+### What's New in v3.2
+
+- **`/commit` command** — lightweight conventional commit + push without review or PR (use `/ship` for full workflow)
+- **`--version` flag** — standard CLI version display
+- **PR/commit templates** — auto-detected at install, generated if missing; agents read templates at runtime
+- **Settings.json merge** — reinstall and `--update` now merge new hooks + permissions instead of skipping
+- **Security hardening** — eliminated shell injection in all Python HEREDOC scripts, portable `sed -i`, input validation
+- **`--init` wizard** — "Auto-detect" target option, improved multi-target support
+- **15+ bug fixes** — see [CHANGELOG.md](CHANGELOG.md) for full details
+
+<details>
+<summary>v3.1 changes</summary>
 
 - **`npm install -g cortexhawk`** — available on npm, auto-resolves source from symlinked binary
 - **`cortexhawk` CLI wrapper** — clean subcommands (init, install, update, doctor, validate, search, snapshot, etc.) instead of `bash install.sh --flags`
 - **`--target auto`** — auto-detects installed CLIs (claude, kimi, codex) and installs for all found
 - **`cortexhawk validate`** — post-install diagnostic verifying skills/agents discovery per target
 
+</details>
+
 <details>
 <summary>v3.0 changes</summary>
 
@@ -103,7 +116,7 @@ Specialized AI agents that coordinate together instead of working in silos.
 | `fullstack-developer` | Full-stack orchestration front+back |
 | `teacher` | Teaches concepts with 3 pedagogical levels (guided, mentor, professor) |
 
-### Commands (32)
+### Commands (33)
 
 Slash commands for common workflows.
 
@@ -114,6 +127,7 @@ Slash commands for common workflows.
 | `/test` | Generate and run tests |
 | `/review` | Multi-agent code review |
 | `/ship` | Commit + PR pipeline |
+| `/commit` | Lightweight commit + push (no review, no PR) |
 | `/debug` | Debug and fix issues |
 | `/scan` | Full security audit |
 | `/check` | Pre-commit quality gate (lint + test + scan + review → GO/NO-GO) |
@@ -313,7 +327,7 @@ Each target adapts components to the CLI's native format:
 | Component | Claude Code | Kimi CLI | Codex CLI |
 |---|---|---|---|
 | Agents (20) | `.claude/agents/*.md` | Skills (`/skill:agent-*`) + `AGENTS.md` | `AGENTS.md` |
-| Commands (32) | `.claude/commands/*.md` → `/plan` | Skills (`/skill:cmd-*`) | Skills (`$cmd-*`) |
+| Commands (33) | `.claude/commands/*.md` → `/plan` | Skills (`/skill:cmd-*`) | Skills (`$cmd-*`) |
 | Skills (36) | `.claude/skills/` | `.kimi/skills/` (auto-discovered) | `.agents/skills/` |
 | Hooks (9) | `settings.json` (automatic) | Skills (`/skill:hook-*`, manual) | Dispatcher (partial) |
 | Modes (7) | `.claude/modes/` (native) | Skills (`/skill:modes/*`) | Skills (`$mode-*`) |
@@ -335,6 +349,7 @@ Each target adapts components to the CLI's native format:
 ./install.sh --update --dry-run        # preview update delta
 
 # Diagnostics
+./install.sh --version                 # show CortexHawk version
 ./install.sh --doctor                  # check installation health
 ./install.sh --test-hooks              # dry-run all hooks with synthetic inputs
 ./install.sh --stats                   # installation overview (version, counts)

package/agents/git-manager.md

@@ -11,9 +11,10 @@ You are a release engineer managing version control workflows.
 
 0. **Context** — Read `docs/.context/_shared.md` and `docs/.context/git-manager.md`
 1. **Assess** — Review current branch state, staged changes, and recent history
+1.5. **Detect PR** — Run `gh pr view --json state,url 2>/dev/null`, parse output; if PR exists with state=OPEN, note branch has active PR (skip creation later); if gh fails or no PR, proceed normally
 2. **Stage** — Select files for commit, verify no secrets or debug artifacts
 3. **Commit** — Generate conventional commit message matching change scope
-4. **Push** — Push to remote, create PR with description and checklist
+4. **Push** — Push to remote, create PR with description and checklist (skip if active PR detected in step 1.5)
 5. **Manage** — Handle branching, tagging, merging, and release prep
 
 ## Commit Convention
@@ -49,6 +50,10 @@ Description: imperative mood, lowercase, no period, max 72 chars
 - Checklist: tests pass, no warnings, docs updated
 ```
 
+## Templates
+- Before creating a PR, check for `.github/PULL_REQUEST_TEMPLATE.md` — if found, follow that format
+- Before committing, check for `.gitmessage` — if found, follow that format for the commit message
+
 ## Rules
 - Atomic commits — one logical change per commit
 - Never force-push to shared branches
@@ -59,5 +64,8 @@ Description: imperative mood, lowercase, no period, max 72 chars
 - Always verify no secrets in staged files before commit
 - Read `## Git Workflow` in CLAUDE.md for project preferences (branching, commits, PRs, auto-push)
 - Respect configured branching strategy, PR preference, and auto-push behavior
-- If no Git Workflow section, default to: feature branches, conventional commits, on-demand PR, auto-push
+- If no Git Workflow section and no `.claude/config/git-workflow.conf`, default to: feature branches, conventional commits, on-demand PR, auto-push
+- Before creating a feature branch, check if current branch has open PR — if yes, reuse branch and push to update PR; if no or state!=OPEN, create new branch
+- PR detection edge cases: gh CLI not installed (skip detection, proceed with branch creation), detached HEAD (skip detection, create new branch), gh fails (silent fail with warning, continue with branch creation), no remote configured (warn and stop)
+- Silent fail on PR detection errors — log warning to user, continue with normal branch creation flow
 - Update `docs/.context/git-manager.md` with patterns, decisions, and key files discovered

package/commands/backlog.md

@@ -12,6 +12,7 @@ Activate the **project-manager** agent in backlog mode.
 3. Score: impact (H/M/L), effort (H/M/L), feasibility (H/M/L)
 4. Update `docs/backlog.md` — add new items, re-prioritize existing ones
 5. Mark items already implemented as done
+6. Run `bash .claude/scripts/refresh-context.sh` to update shared context
 
 Backlog format in `docs/backlog.md`:
 

package/commands/cleanup.md

@@ -0,0 +1,36 @@
+---
+name: cleanup
+description: Delete merged branches and optionally enable auto-cleanup hook
+---
+
+# /cleanup
+
+Delete merged local branches and optionally delete remote branches.
+
+## Process
+
+1. Check if `.claude/.cleanup-configured` exists — if not, prompt for hook opt-in
+2. If marker missing, ask: "Enable auto-cleanup hook after merging PRs? [y/N]"
+3. If user chooses yes:
+   - Uncomment post-merge composition in `.claude/hooks/compose.yml` via sed
+   - Create marker: `echo 'enabled' > .claude/.cleanup-configured`
+   - Notify: "Auto-cleanup hook enabled. Runs automatically after git merge."
+4. If user chooses no:
+   - Create marker: `echo 'manual' > .claude/.cleanup-configured`
+5. Run cleanup script: `.claude/scripts/post-merge-cleanup.sh` (interactive mode)
+6. Script detects branching strategy from `.claude/git-workflow.conf` or `CLAUDE.md`
+7. Lists merged branches (excluding main/master/dev/develop/current)
+8. Prompts before deleting each local branch
+9. Prompts before deleting each remote branch (default: no)
+10. If on main branch: pulls latest changes
+11. If `BRANCHING=feature-branches`: optionally creates new feature branch
+
+## Rules
+
+- First-run hook prompt only shows once (marker file persists preference)
+- Remote deletion requires explicit confirmation (default: no)
+- Never delete main/master/dev/develop or current branch
+- Handle missing config files gracefully (fallback to defaults)
+- Handle git errors without crashing (network, permissions, no remote)
+- If compose.yml missing, warn and skip hook enablement
+- If sed fails, report error but continue cleanup

package/commands/commit.md

@@ -0,0 +1,24 @@
+---
+name: commit
+description: Conventional commit and push — lightweight alternative to /ship (no review, no PR).
+---
+
+# /commit
+
+Activate the **git-manager** agent. Commit: `$ARGUMENTS`
+
+1. Read `## Git Workflow` from CLAUDE.md if present — respect branching strategy, commit convention, and auto-push settings
+2. If `.gitmessage` exists, read it for commit message format guidance
+3. Review staged and unstaged changes, stage relevant files (never `git add -A`)
+4. Generate conventional commit message from changes — format: `type(scope): description`
+5. Commit with the generated message
+6. If auto-push is enabled, push to remote
+7. Show commit summary (hash, message, files changed)
+
+## Rules
+
+- No review pass — use `/ship` for reviewed commits, `/commit` for quick iterations
+- No PR creation — use `/ship` when a PR is needed
+- Respect `.gitignore` — never stage `.env`, secrets, or debug artifacts
+- If no changes to commit, report and stop
+- If `$ARGUMENTS` is provided, use it as commit message context (not the literal message)

package/commands/review-pr.md

@@ -0,0 +1,31 @@
+---
+name: review-pr
+description: Fetch, triage, and address PR review comments in batch — one commit, one notification.
+---
+
+# /review-pr
+
+Activate the **reviewer** agent using the `pr-review-comments` skill. Target PR: current branch.
+
+1. **Auth** — Check MCP GitHub (`mcp__github__list_pull_requests`); fall back to `gh pr view` if unavailable
+2. **Fetch** — Get all open inline threads, review submissions, and conversation comments
+3. **Triage** — Group by author: Copilot / human reviewers / bots; skip resolved and outdated
+4. **Present** — Show numbered threads with `file:line`, author, summary, and proposed fix
+5. **Confirm** — Ask which to address (`1, 3, 5` or `all`) before touching any file
+6. **Fix** (batch, default) — Apply all selected fixes in one pass
+7. **Commit** — `fix: address PR review comments` (single commit)
+8. **Push** — Push to remote
+9. **Reply** — `mcp__github__create_pull_request_review` (batch) or `gh pr comment` — one reply per thread, referencing the commit sha
+
+## Flags
+
+- `--sequential` — fix → commit → reply per thread; use when comments are complex or interdependent
+
+## Rules
+
+- Always present threads and wait for user selection before fixing
+- Batch mode: one commit + one review submission = one notification to reviewers
+- Sequential mode: one commit per thread, reply immediately after each fix
+- Never fix resolved or outdated threads unless explicitly requested
+- If no open threads, report and stop
+- If auth fails, prompt `gh auth login` or check `GITHUB_PERSONAL_ACCESS_TOKEN`

package/commands/ship.md

@@ -8,10 +8,11 @@ description: Commit, create PR, and prepare for deployment.
 Activate the **git-manager** agent, then the **reviewer** agent. Ship: `$ARGUMENTS`
 
 0. Read `## Git Workflow` from CLAUDE.md if present — respect PR preference and auto-push settings
+0.5. Check if current branch has open PR — run `gh pr view --json state,url 2>/dev/null`; if PR exists and state=OPEN, skip branch creation (update existing PR); if gh unavailable or no PR found, proceed with normal flow
 1. Stage changes and generate conventional commit message
 2. Run quick review pass — reviewer runs Pass 1 (Correctness) and Pass 2 (Security) only, reporting Critical findings exclusively
 3. If review passes, commit and push
-4. Create PR with description, testing notes, and checklist
+4. Create PR — if `.github/PULL_REQUEST_TEMPLATE.md` exists, follow that format; otherwise use: Summary, Changes, Test Plan, Checklist
 5. If review finds critical issues, report them and stop — don't ship broken code
 
 Format: `feat(scope): description` or `fix(scope): description`

package/commands/task.md

@@ -16,6 +16,7 @@ Activate the **project-manager** agent as orchestrator. Execute backlog item `$A
 6. Update `CHANGELOG.md` with a one-line entry under the current version's `### Added` section
 7. If chain completes without critical blockers, execute `/ship`
 8. Mark item as `done` in backlog
+9. Run `bash .claude/scripts/refresh-context.sh` to update shared context
 
 ## Save Rules
 

package/cortexhawk

@@ -120,8 +120,8 @@ do_validate() {
 
                 # settings.json
                 if [ -f "$target_dir/settings.json" ]; then
-                    if python3 -c "import json; json.load(open('$target_dir/settings.json'))" 2>/dev/null || \
-                       node -e "JSON.parse(require('fs').readFileSync('$target_dir/settings.json'))" 2>/dev/null; then
+                    if python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$target_dir/settings.json" 2>/dev/null || \
+                       node -e "JSON.parse(require('fs').readFileSync(process.argv[1]))" "$target_dir/settings.json" 2>/dev/null; then
                         check "settings.json valid JSON" "ok"
                     else
                         check "settings.json invalid JSON" "fail"

package/hooks/branch-guard.sh

@@ -21,17 +21,25 @@ fi
 
 PROTECTED_BRANCHES=("main" "master" "production" "release")
 
-# Load git workflow config — allow direct-main push if configured
+# Load git workflow config — adjust protected branches based on branching strategy
 CONF_FILE="$(git rev-parse --show-toplevel 2>/dev/null)/.claude/git-workflow.conf"
 if [[ -f "$CONF_FILE" ]]; then
   _BRANCHING=$(grep '^BRANCHING=' "$CONF_FILE" | cut -d= -f2)
   if [[ "$_BRANCHING" == "direct-main" ]]; then
     PROTECTED_BRANCHES=("master" "production" "release")
+  elif [[ "$_BRANCHING" == "dev-branch" ]]; then
+    _WORK_BRANCH=$(grep '^WORK_BRANCH=' "$CONF_FILE" | cut -d= -f2)
+    [[ -n "$_WORK_BRANCH" ]] && PROTECTED_BRANCHES+=("$_WORK_BRANCH")
   fi
 fi
 
 # Check for git push to protected branches
 if echo "$CMD" | grep -qE 'git\s+push'; then
+  # Allow --delete operations (deleting remote branches, not pushing code)
+  if echo "$CMD" | grep -qE 'git\s+push\s+.*--delete|git\s+push\s+.*-d\s'; then
+    exit 0
+  fi
+
   CURRENT_BRANCH=$(git branch --show-current 2>/dev/null)
 
   for branch in "${PROTECTED_BRANCHES[@]}"; do

package/hooks/compose.yml

@@ -45,3 +45,9 @@ compositions:
     matcher: "*"
     hooks:
       - session-telemetry
+
+  # post-merge:
+  #   event: GitHook
+  #   matcher: "post-merge"
+  #   hooks:
+  #     - post-merge

package/hooks/file-guard.sh

@@ -9,12 +9,16 @@ BLOCKED_PATTERNS=(
   "*.key"
   "id_rsa"
   "id_ed25519"
+  "id_ecdsa"
   "*.p12"
   "*.pfx"
   "*.keystore"
+  "*.jks"
   "credentials.json"
   "credentials.yml"
   "credentials.yaml"
+  "*secret*"
+  "service-account*.json"
 )
 
 # Basename patterns that are .env.* but NOT .env.example/.env.sample/.env.template

package/hooks/hooks.json

@@ -36,6 +36,12 @@
       "script": "hooks/commit-guard.sh",
       "description": "Validates commit format and checks for staged secrets"
     },
+    {
+      "name": "lint-guard",
+      "type": "PreToolUse",
+      "script": "hooks/lint-guard.sh",
+      "description": "Auto-detect and run formatters/linters on staged files before commit"
+    },
     {
       "name": "test-reminder",
       "type": "PostToolUse",

package/hooks/lint-guard.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# lint-guard — Auto-detect formatters/linters and run before git commit/push
+# Hook type: PreToolUse (Bash)
+# Delegates heavy work to scripts/lint-guard-runner.sh
+
+# --- 1. PARSE COMMAND ---
+if [ -n "$CORTEXHAWK_COMMAND" ]; then
+  CMD="$CORTEXHAWK_COMMAND"
+else
+  INPUT=$(cat)
+  if command -v jq &>/dev/null; then
+    CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+  fi
+  [ -z "$CMD" ] && CMD=$(printf '%s' "$INPUT" \
+    | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+fi
+[ -z "$CMD" ] && exit 0
+echo "$CMD" | grep -qE 'git\s+(commit|push)' || exit 0
+
+# --- 2. PUSH CHECK — yml takes priority over git-workflow.conf ---
+if echo "$CMD" | grep -qE 'git\s+push'; then
+  _ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+  _YML_PUSH=$(grep -E "^\s+run_on_push:" "$_ROOT/.cortexhawk-lint.yml" 2>/dev/null \
+    | sed 's/.*: *//' | tr -d ' \r')
+  if [ "$_YML_PUSH" = "true" ]; then
+    :
+  elif [ "$_YML_PUSH" = "false" ]; then
+    exit 0
+  else
+    LINT_ON_PUSH=$(grep '^LINT_ON_PUSH=' "$_ROOT/.claude/git-workflow.conf" 2>/dev/null | cut -d= -f2)
+    [ "$LINT_ON_PUSH" != "true" ] && exit 0
+  fi
+fi
+
+# --- 3. DELEGATE ---
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+[ -z "$REPO_ROOT" ] && exit 0
+
+if command -v pre-commit &>/dev/null && [ -f "$REPO_ROOT/.pre-commit-config.yaml" ]; then
+  echo "lint-guard: pre-commit detected — delegating to pre-commit framework"
+  pre-commit run
+  exit $?
+fi
+
+bash "$REPO_ROOT/.claude/scripts/lint-guard-runner.sh"
+exit $?

package/hooks/post-merge.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# post-merge — Auto-cleanup merged branches after PR merge
+# Hook type: GitHook
+# Disabled by default — enable via /cleanup first run
+
+# Call cleanup script in auto mode (silent, no prompts, skip remote deletion)
+if [ -f ".claude/scripts/post-merge-cleanup.sh" ]; then
+    bash ".claude/scripts/post-merge-cleanup.sh" --auto 2>/dev/null || true
+fi
+
+# Exit silently — don't block merge operation on script failures
+exit 0

package/hooks/session-start.sh

@@ -44,14 +44,17 @@ if [ -d "docs/.context" ] && [ ! -L "docs/.context" ]; then
 
     echo "# Shared Context" > "$SHARED"
     echo "" >> "$SHARED"
-    echo "_Auto-generated by session-start. Do not edit manually._" >> "$SHARED"
+    echo "_Auto-generated at $(date '+%Y-%m-%d %H:%M'). Snapshot from session start — may be stale._" >> "$SHARED"
     echo "" >> "$SHARED"
 
     # Backlog summary
     if [ -f "docs/backlog.md" ]; then
-        ACTIVE=$(grep -c '| todo |' docs/backlog.md 2>/dev/null || echo 0)
-        DEFERRED=$(grep -c '| deferred |' docs/backlog.md 2>/dev/null || echo 0)
-        DONE=$(grep -c '| done |' docs/backlog.md 2>/dev/null || echo 0)
+        ACTIVE=$(grep -c '| todo |' docs/backlog.md 2>/dev/null || true)
+        : "${ACTIVE:=0}"
+        DEFERRED=$(grep -c '| deferred |' docs/backlog.md 2>/dev/null || true)
+        : "${DEFERRED:=0}"
+        DONE=$(grep -c '| done |' docs/backlog.md 2>/dev/null || true)
+        : "${DONE:=0}"
         echo "## Backlog" >> "$SHARED"
         echo "- Active: $ACTIVE | Deferred: $DEFERRED | Done: $DONE" >> "$SHARED"
         # List active items
@@ -129,4 +132,4 @@ if [ -d "$SKILL_DIR" ]; then
 fi
 
 echo ""
-echo "Commands: /plan /build /test /review /ship /debug /scan /check /refactor /research /doc /bootstrap /tdd /optimize /migrate /monitor /api-gen /changelog /journal /brainstorm /simplify /deploy /export /backlog /pulse /map /learn /chain /task /ci /context"
+echo "Commands: /plan /build /test /review /ship /commit /cleanup /debug /scan /check /refactor /research /doc /bootstrap /tdd /optimize /migrate /monitor /api-gen /changelog /journal /brainstorm /simplify /deploy /export /backlog /pulse /map /learn /chain /task /ci /context /upgrade"