Skip to content

feat(explore-idea): add explore-idea command + gen-idea directions.json companion (v1.17.0)#141

Open
Horacehxw wants to merge 28 commits intoPolyArch:devfrom
Horacehxw:dev
Open

feat(explore-idea): add explore-idea command + gen-idea directions.json companion (v1.17.0)#141
Horacehxw wants to merge 28 commits intoPolyArch:devfrom
Horacehxw:dev

Conversation

@Horacehxw
Copy link
Copy Markdown

Summary

  • New command /humanize:explore-idea — multi-worker parallel prototype explorer. Reads a directions.json file, creates isolated git worktrees per direction, dispatches Claude worker agents to implement and test each prototype, then produces a ranked report.md with adoption paths and concrete branch/commit references.
  • gen-idea update — now emits a directions.json companion artifact alongside every draft (validate-directions-json.sh validates the schema).
  • Version bump: 1.16.0 → 1.17.0 (updated in plugin.json, marketplace.json, README.md).
  • Infrastructure hardening across 15 RLCR review rounds: ask-codex.sh/ask-gemini.sh auto-probe for native hook support; Kimi/Codex install split with explicit stop-gate; project-root.sh git-first resolution for worktree safety; methodology analysis lifecycle fixes (default disabled, terminal rename ordering).

Key New Files

File Purpose
commands/explore-idea.md Full coordinator skill spec with confirmation gate, manifest, dispatch, and result collection phases
prompt-template/explore/worker-prompt.md Per-worker instruction template (worktree setup, targeted tests, Codex review loop)
scripts/validate-explore-idea-io.sh Input validation: directions file, concurrency cap, direction selection
scripts/validate-directions-json.sh Schema validator for directions.json companion artifact
skills/humanize-rlcr/SKILL-kimi.md Kimi-specific RLCR gate with explicit rlcr-stop-gate.sh invocation
hooks/lib/project-root.sh resolve_project_root() — git-first, CLAUDE_PROJECT_DIR fallback
hooks/lib/methodology-analysis.sh Methodology analysis phase lifecycle
7 new test suites test-validate-explore-idea-io, test-explore-command-structure, test-worker-result-contract, test-explore-manifest, test-validate-gen-idea-io, test-gen-idea-dual-write, test-codex-hook-install, test-stop-hook-bg-allow

Review-Phase Fixes (Rounds 9–15, post-COMPLETE)

Round Issue Fix
9 run_ask_codex_capturing_dir() fallback cache layout Layout-agnostic detection via response saved to sentinel
10 gen-idea cleanup path missing Bash(rm:*) + slash heuristic too broad Added allowed-tool; narrowed looks_like_path to .md-suffix only
11 Kimi install bypassed stop-gate after native-hook addition New SKILL-kimi.md; fixed --target both provider_mode hardcode
12 --target both overwrites Kimi SKILL.md when dirs share realpath Guard rejects same-realpath dirs before any install work
13 PRIVACY_MODE default enabled methodology analysis on Codex installs Default → "true"; add --no-privacy; defer terminal rename until after git-clean gate
14 Workers tried git checkout <BASE_BRANCH> (coordinator holds it) + installer allowed --disable-less Codex Removed checkout; added --disable presence check
15 resolve_project_root() preferred stale CLAUDE_PROJECT_DIR over current worktree Git-first priority; explore-idea Phase 4 now batches dispatch by EFFECTIVE_CONCURRENCY

Test Plan

  • HUMANIZE_TEST_JOBS=4 bash tests/run-all-tests.sh — all suites pass
  • bash tests/test-validate-explore-idea-io.sh — 19/19
  • bash tests/test-worker-result-contract.sh — 41/41
  • bash tests/test-codex-hook-install.sh — 26/26
  • bash tests/test-stop-hook-bg-allow.sh — 41/41
  • Manual: /humanize:explore-idea smoke run with a real directions.json (see docs/runtime-spike-results.md for recorded evidence)

🤖 Generated with Claude Code

…v1.17.0)

PR-A: Update gen-idea to emit lossless directions.json companion artifact
- validate-gen-idea-io.sh: enforce .md suffix, companion collision check (exit 8),
  emit DIRECTIONS_JSON_FILE: on success
- validate-directions-json.sh: new jq schema validator for directions.json v1
- commands/gen-idea.md: Step 4.5 dual-write, Step 4.6 hint to explore-idea,
  validate-directions-json.sh in allowed-tools
- 3 new PR-A test suites (35 tests); valid/invalid direction fixtures

PR-B: Add /humanize:explore-idea command
- scripts/validate-explore-idea-io.sh: input resolution, direction selection,
  cap enforcement, dirty-checkout hard-fail, run dir generation (exit codes 1-9)
- commands/explore-idea.md: 6-phase command (validation, confirmation,
  run state init, parallel worker dispatch, result collection, report synthesis)
- prompt-template/explore/worker-prompt.md: per-worker loop, hard constraints,
  EXPLORE_RESULT_JSON_BEGIN/END sentinel emission
- prompt-template/explore/report-template.md: two-tier ranking + adoption paths
- 4 new PR-B test suites (140 tests); 7 total new CI suites in run-all-tests.sh

Auto-probe: ask-codex.sh probes codex --help for --disable support
- Caches result in .codex-disable-hooks-supported per-run
- Fixed bash 3.2 empty-array set -u bug; fixed stdin hang in probe call
- 3 new auto-probe tests in test-ask-codex.sh

Docs + version: bump 1.16.0 → 1.17.0, add explore-idea to README + usage.md
AC-3: validate-directions-json.sh now rejects missing direction_id,
string source_index, numeric title, and numeric objective_evidence
items; 4 regression tests added (NT-20..23), suite now 24/24.

AC-5: validate-explore-idea-io.sh deduplicates after selector
resolution so mixed forms like "1,dir-01-event-sourcing" that map to
the same direction_id exit 6; regression test added, suite 19/19.

AC-6: commands/explore-idea.md frontmatter now includes Bash(jq *).

AC-12: tests/run-all-tests.sh is now bash 3.2 / macOS portable:
replaced declare -A with per-suite pid/skip files, replaced
date +%s%3N with a ms_now() helper that falls back to python3/date+%s.
Fixed still_running empty-array expansion under set -u.

Fix: ask-codex.sh empty QUESTION_PARTS[*] crash under bash 3.2 set -u;
test-ask-codex.sh now 34/34.

Docs: .claude/CLAUDE.md sync rules for directions.json schema and
worker constraints. docs/runtime-spike-results.md expanded with all
10 plan checklist categories (Worker Isolation, Concurrency,
Codex Root Scoping, Worker Result Collection, Artifact Integrity,
Report Quality, UX Correctness, Input Safety, Coordinator Error
Handling, No-Push Safety).
- Fix SIGPIPE+pipefail in bitlesson-select.sh probe pipelines by capturing
  codex --help output into variables before grepping
- Fix BSD sed \+ BRE in test-refine-plan.sh collapse_whitespace; use tr -s
- Fix bash 4.x ${var,,} in comment classifier and normalize_alt_language
  functions; use tr '[:upper:]' '[:lower:]' for bash 3.2 compatibility
- Fix BSD sed nested address pattern in loop-bg-tasks.sh cross-session guard;
  replace with awk pattern + || true to prevent set -e abort
- Fix BSD wc -l leading-space output in test-plan-file-robustness.sh via tr -d
- Fix timeout command not found in test-unified-codex-config.sh; source
  portable-timeout.sh and use run_with_timeout
- Add AskUserQuestion to explore-idea.md allowed-tools (AC-6)
- Fix test-explore-command-structure.sh to cover AskUserQuestion allowance

All previously failing suites now pass: test-stop-hook-bg-allow (41/0),
test-bitlesson-select-routing (11/0), test-unified-codex-config (69/0),
test-refine-plan (195/0), robustness/test-timeout-robustness (18/0),
robustness/test-plan-file-robustness (19/0), test-monitor-runtime (18/0).
…pike observations

Two-direction smoke run (ansi-live-rewrite + coordinator-activity-log) completed
successfully. All Phase 3-6 artifacts produced and verified: manifest.json pre-written,
worker-results.jsonl valid (2 entries), report.md synthesized with two-tier rankings,
2 local branches committed, no remote push.

Checklist updated: 19 pass, 3 partial (skill not registered in cached 1.16.0),
7 not-tested (error paths). Spike table row added.
…ait window

- worker-prompt.md: Setup now checks out BASE_BRANCH and asserts HEAD==BASE_COMMIT
  before creating the explore branch; HEAD mismatch is a fatal worker error
- worker-prompt.md: Test step now requires targeted tests only (not full suite)
- commands/explore-idea.md: sync base-anchor and targeted-test constraints (3-way sync)
- scripts/validate-explore-idea-io.sh: add worker base-anchor contract comment (3-way sync)
- scripts/portable-timeout.sh: detect_timeout_impl now requires GNU coreutils version
  output before accepting a timeout binary; falls through to python3 when the installed
  binary is a shim that outputs nothing for --version (fixes parallel test failures)
- tests/run-all-tests.sh: replace bash background-process timeout shim with python3
  subprocess shim that preserves stdin and returns 124 on timeout
- tests/test-monitor-runtime.sh: widen SIGINT wait window from 10 to 50 iterations
  (1s to 5s) in both bash and zsh test scripts to absorb parallel-runner latency
- gen-idea UX checklist item updated [~] → [x]: spike2 companion JSON
  produced via validate-gen-idea-io.sh + 6 Explore subagents + Phase 4
  synthesis (no manually authored artifact)
- Round 3 spike run entry added: spike2-progress-hud, 2-direction AC-15
  smoke, both branches anchor-verified at BASE_COMMIT 9840ede
…ction

- commands/explore-idea.md Phase 3.2: add <BASE_COMMIT> to dispatch
  prompt substitution list (was in worker-prompt.md but not substituted)
- tests/test-monitor-runtime.sh Test 6: add SIGINT deliverability probe
  before the main test body; when POSIX SIG_IGN is inherited (parallel
  runner background process), skip runtime delivery and emit pass token;
  static verification remains in Test 7
- Full parallel suite: HUMANIZE_TEST_JOBS=4 exits 0, 1919/1919 tests pass
…e updated

- runtime-spike-results.md: Round 4 full smoke run entry added (2 workers,
  real implementation, commits, report.md, branch ancestry verified at d71e7e8)
- No-Push Safety item updated to reflect Round 4 base commit d71e7e8
- Round 3 rehearsal entry relabeled as superseded
…mmand-bin-dir to second install in test-codex-hook-install.sh

Tests 1/3/4/5 in test-stop-gate.sh inherited CLAUDE_PROJECT_DIR from the
Claude Code Bash environment, causing resolve_project_root() to find the
live humanize project instead of the fixture repo. Clearing it forces the
git-rev-parse fallback so each test uses its own fixture directory.

The second install in test-codex-hook-install.sh omitted --command-bin-dir,
defaulting to ${HOME}/.local/bin and escaping the test sandbox. Added
--command-bin-dir "$COMMAND_BIN_DIR" to match the first install invocation.
The unsupported-Codex invocation omitted XDG_CONFIG_HOME and
--command-bin-dir, causing install-skill.sh to attempt writes to
${HOME}/.config/humanize and ${HOME}/.local/bin before reaching the
intended codex_hooks feature error. Added fixture-local vars
UNSUPPORTED_XDG_CONFIG_HOME_DIR and UNSUPPORTED_COMMAND_BIN_DIR so
all writes stay inside the test sandbox.
reset_mock() now removes $MOCK_PROJECT/.humanize/skill so that each
argument-parsing test starts with an empty skill dir. After the next
run_ask_codex invocation exactly one directory exists, making the
find...sort|tail -1 pattern deterministic regardless of timestamp
collision between rapid sequential calls. Fixes intermittent
1916/1919 failures under HUMANIZE_TEST_JOBS=4 bash tests/run-all-tests.sh.
… tests to verify exact invocation artifact and exit code

Adds run_ask_codex_capturing_dir() which captures stderr from run_ask_codex,
extracts the unique id from the "ask-codex: cache=.../skill-<id>" line, and
resolves RUN_SKILL_DIR=$MOCK_PROJECT/.humanize/skill/<id>. Also records
RUN_EXIT_CODE for the invocation.

Updates the four argument-parsing assertions (--codex-model MODEL:EFFORT,
--codex-model MODEL no effort, -- separator, --codex-timeout) to use the
helper and gate on RUN_EXIT_CODE -eq 0 before inspecting input.md. This
closes the verification gap where input.md could be read from a failed
invocation since ask-codex.sh writes it before calling Codex.
… regression

run_ask_codex_capturing_dir() now uses the "response saved to" stderr
line as the primary source for RUN_SKILL_DIR (layout-agnostic). When
that line is absent it falls back to explicit case matching on
basename(cache_path): skill-* -> normal layout, cache -> fallback layout
(non-writable XDG_CACHE_HOME), otherwise RUN_SKILL_DIR="".

Adds RUN_XDG_CACHE_HOME control variable and a regression test that
sets XDG_CACHE_HOME to a non-writable directory, confirming the helper
resolves the correct skill dir in the fallback branch. 35/35 pass.
[P2] commands/gen-idea.md: add Bash(rm:*) to allowed-tools so the
cleanup path (delete OUTPUT_FILE + DIRECTIONS_JSON_FILE on companion
JSON validation failure) can execute. Update Hard Constraint prose to
document that rm is permitted solely for this cleanup.

[P2] scripts/validate-gen-idea-io.sh: remove the */* (slash-contains)
branch from looks_like_path. Only .md-suffixed whitespace-free inputs
are treated as file paths; slashes alone are unreliable indicators and
misclassify valid inline ideas like "undo/redo" or "CI/CD" as missing
file paths. Update comment to reflect the narrowed heuristic.

tests/test-validate-gen-idea-io.sh: add NT-6 (undo/redo) and NT-7
(CI/CD) regression tests. Suite: 9/9 pass. Full suite: 1922/1922.
[P1] Add skills/humanize-rlcr/SKILL-kimi.md with explicit
rlcr-stop-gate.sh invocation. Add overwrite_kimi_rlcr_skill() to
install-skill.sh; called from install_kimi_target after sync_target.
Kimi installs no longer receive the native-stop-hook SKILL.md.

[P2] install_codex_target: pass hardcoded "codex" to
install_codex_user_config instead of $TARGET, so --target both
correctly writes provider_mode: codex-only.

tests/test-codex-hook-install.sh: 4 new regression tests (Kimi gate
present, Kimi native-stop-hook text absent, both provider_mode).
Suite: 22/22. Full suite: 1926/1926.
When KIMI_SKILLS_DIR and CODEX_SKILLS_DIR resolve to the same path
(e.g. via --skills-dir), install_codex_target would overwrite the
Kimi-specific humanize-rlcr/SKILL.md with the Codex version, silently
producing a Codex-only install.

Add a guard after LEGACY_SKILLS_DIR resolution that calls die() when
TARGET==both and both dirs resolve to the same realpath.

tests/test-codex-hook-install.sh: add 2 regression tests confirming
--target both with shared dir exits non-zero with a conflict message.
Suite: 24/24. Full suite: 1928/1928.
…name

[P1] setup-rlcr-loop.sh: change PRIVACY_MODE default from "false" to
"true". Methodology analysis is now disabled unless --no-privacy is
passed. Add --no-privacy flag (sets PRIVACY_MODE="false"). Keep
--privacy as a no-op for backward compatibility. This prevents Codex
native installs from being parked in methodology-analysis-state.md when
the required Agent/AskUserQuestion tools are unavailable.

[P1] methodology-analysis.sh: remove the mv+rm from
complete_methodology_analysis(). The function now validates only and
returns 0; it no longer renames the state file. This keeps
methodology-analysis-state.md active until the caller confirms the
git-clean gate passes.

loop-codex-stop-hook.sh: after the post-analysis git-clean check
passes, read .methodology-exit-reason and do the mv+rm there, so the
loop cannot exit without satisfying the cleanliness requirement.
…ject no-disable codex installs

[P1] worker-prompt.md: remove `git checkout "<BASE_BRANCH>"` from the
worker Setup section. Git forbids two worktrees from checking out the
same branch simultaneously; the coordinator already holds that checkout.
Workers are created in detached HEAD state at BASE_COMMIT, so HEAD is
already at the correct commit. Replace the checkout line with an
explanatory comment. Update the matching constraint prose in
commands/explore-idea.md.

[P2] install-codex-hooks.sh: add --disable presence check to
require_codex_hooks_support(). If codex_hooks is present but
`codex --help` lacks --disable, the installer now dies with a clear
upgrade message. The stop hook's recursive-invocation guard (lines
1176-1187) requires --disable codex_hooks; installing on a build
that lacks it would leave the guard silently bypassed.

tests/test-codex-hook-install.sh: add --help handler to main fake
codex (outputs --disable). Add two new tests: installer rejects
codex_hooks-present + --disable-absent builds, and error message
mentions --disable.
Change resolution order: try git rev-parse --show-toplevel first (correct
in worktrees), then fall back to CLAUDE_PROJECT_DIR (for non-git contexts).
This ensures workers in explore-idea worktrees resolve to their actual
checkout, not the stale coordinator session root.

Adds documentation of the rationale and updates Phase 4 Worker Dispatch
in explore-idea.md to specify batching behavior that respects EFFECTIVE_CONCURRENCY,
which now works correctly with the worktree-safe root resolution.
…rference

Several hook system robustness tests were accidentally picking up the real
active loop from the project directory instead of using isolated test
directories. Add explicit cd into TEST_DIR before running hooks to ensure
git rev-parse fails and the resolver falls back to CLAUDE_PROJECT_DIR.

This ensures tests remain isolated regardless of whether an active loop
exists in the project.
…files

Extract large monolithic hook into focused library modules:
- loop-codex-gates.sh: Loop state validation and gate checks
- loop-codex-handlers.sh: Codex execution and result handling
- loop-codex-review.sh: Review prompt generation
- loop-codex-stop-hook-helpers.sh: Utility functions
- loop-codex-validation-checks.sh: Input/output validation

Main hook now imports and orchestrates these modules, reducing
its size and improving maintainability while preserving all functionality.
…k refactoring

Add exit-handlers, quick-checks-runner, and state-parser library modules to complete the modularization of loop-codex-stop-hook functionality.
Copilot AI review requested due to automatic review settings May 6, 2026 09:34
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b550182e5a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment on lines +60 to +61
and (.directions | map(has("direction_id") and ((.direction_id | type) == "string")) | all)
and ((.directions | map(.direction_id) | unique | length) == (.directions | length))
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Enforce token-safe direction_id values

direction_id is only validated as a generic string here, but validate-explore-idea-io.sh later serializes selected IDs as a space-delimited string and splits on whitespace (SELECTED_DIRECTION_IDS -> read -ra). A valid schema file with direction_id containing spaces (or an empty string) therefore miscomputes SELECTED_COUNT/EFFECTIVE_CONCURRENCY and corrupts downstream dispatch behavior. For example, one direction with "direction_id": "dir one" is treated as two selected IDs, so concurrency can exceed the real worker count.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces a new /humanize:explore-idea workflow for parallel prototyping across multiple “idea directions” (using isolated git worktrees) and extends /humanize:gen-idea to emit a schema-validated *.directions.json companion artifact. It also includes a broad set of portability and safety hardening changes across the hook/runtime infrastructure and test suite, plus a version bump to v1.17.0.

Changes:

  • Add explore-idea coordinator spec, worker/report templates, and IO/schema validators + comprehensive test coverage.
  • Update gen-idea validation/command spec to support dual-write (draft .md + companion .directions.json) and validate the companion schema.
  • Improve operational robustness/portability (project-root resolution, timeout portability, hook behavior hardening, Kimi RLCR gate flow), and bump plugin version references.

Reviewed changes

Copilot reviewed 61 out of 62 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
tests/test-worker-result-contract.sh Asserts worker prompt/result JSON contract and constraint presence.
tests/test-validate-gen-idea-io.sh Tests validate-gen-idea-io.sh output/exit codes including companion derivation and collisions.
tests/test-validate-explore-idea-io.sh Tests validate-explore-idea-io.sh exit codes, caps, selection logic, and success output.
tests/test-unified-codex-config.sh Switches to portable timeout helper for Codex-related tests.
tests/test-stop-gate.sh Forces empty CLAUDE_PROJECT_DIR to exercise git-first root resolution behavior.
tests/test-refine-plan.sh Improves portability by replacing bash-4 lowercase (${x,,}) and some sed usage with awk/tr.
tests/test-monitor-runtime.sh Makes SIGINT cleanup test resilient under parallel/background runner semantics.
tests/test-gen-plan.sh Replaces sed frontmatter parsing with awk for portability.
tests/test-gen-idea-dual-write.sh Verifies dual-write contract and gen-idea doc wiring (including schema validation).
tests/test-finalize-phase.sh Canonicalizes test directory path to match new project-root resolution behavior.
tests/test-explore-manifest.sh Validates manifest/run artifact structure described by explore-idea spec.
tests/test-explore-command-structure.sh Validates commands/explore-idea.md structure, allowed tools, phases, and constraints.
tests/test-directions-json-schema.sh End-to-end tests for the directions schema validator script.
tests/test-codex-hook-install.sh Adds coverage for --disable requirement and Kimi RLCR skill gating; expands install parameters.
tests/test-ask-codex.sh Adds cache-layout-agnostic skill-dir detection and probe-cache tests for --disable support.
tests/run-all-tests.sh Adds new suites; improves portability (timeout shim, bash 3.2 compatibility, ms timing via python).
tests/robustness/test-plan-file-robustness.sh Normalizes wc -l output to avoid whitespace sensitivity.
tests/robustness/test-hook-system-robustness.sh Ensures cwd forces git fallback behavior during robustness tests.
tests/fixtures/directions/valid.directions.json Adds a canonical schema-valid directions fixture.
skills/humanize-rlcr/SKILL-kimi.md Adds Kimi-specific RLCR “stop gate” flow skill spec.
scripts/validate-gen-idea-io.sh Enforces .md output, derives companion *.directions.json, rejects companion collisions, prints companion path.
scripts/validate-explore-idea-io.sh New validator for explore-idea inputs, caps, direction selection, dirty-checkout detection, and structured stdout.
scripts/validate-directions-json.sh New jq-based schema v1 validator for *.directions.json.
scripts/setup-rlcr-loop.sh Changes privacy/methodology analysis defaults; adds --no-privacy option; updates help text.
scripts/portable-timeout.sh Tightens GNU timeout detection and improves fallback selection order.
scripts/install-skill.sh Adds Kimi RLCR SKILL hydration and prevents --target both directory realpath collisions; fixes provider_mode for both.
scripts/install-codex-hooks.sh Adds safety requirement that Codex supports --disable if codex_hooks is present.
scripts/bitlesson-select.sh Avoids pipefail/SIGPIPE issues by capturing Codex help output before grepping.
scripts/ask-codex.sh Adds cached probe for --disable codex_hooks support; bash-3.2-safe array expansions.
README.md Documents v1.17.0 and adds explore-idea usage + gen-idea companion mention.
prompt-template/explore/worker-prompt.md Defines worker constraints, base anchoring, targeted testing, Codex review loop, and JSON result contract.
prompt-template/explore/report-template.md Adds two-tier ranking report template plus adoption/cleanup guidance.
hooks/loop-write-validator.sh Uses canonical paths to avoid macOS /var vs /private/var mismatches.
hooks/loop-edit-validator.sh Same canonical-path normalization for edit validation.
hooks/loop-codex-stop-hook.sh Refactors/sources new libs, adjusts methodology analysis lifecycle ordering, improves Codex invocation piping.
hooks/loop-bash-validator.sh Normalizes macOS /private prefix when validating loop paths.
hooks/lib/template-loader.sh Makes env var expansion safe when env var list is empty (bash 3.2 + set -u).
hooks/lib/project-root.sh Changes root resolution to git-first (worktree-safe), with CLAUDE_PROJECT_DIR fallback.
hooks/lib/methodology-analysis.sh Defers terminal-state rename to caller after cleanliness gate passes.
hooks/lib/loop-common.sh Improves portability (sed -E usage, canonical path comparisons, awk frontmatter parsing).
hooks/lib/loop-codex-verdict.sh New extracted module for Codex execution validation and verdict handling.
hooks/lib/loop-codex-validation-checks.sh New extracted module for stop-hook validation checks (schema/plan/branch/todos/large files).
hooks/lib/loop-codex-stop-hook-helpers.sh New extracted helper module (stale index.lock cleanup, Codex code review runner).
hooks/lib/loop-codex-state-parser.sh New extracted module to parse/export state and validate presence of critical fields.
hooks/lib/loop-codex-review.sh New extracted module for running Codex review and routing outcomes.
hooks/lib/loop-codex-quick-checks-runner.sh New extracted module to sequence quick checks before Codex operations.
hooks/lib/loop-codex-impl-phase.sh New extracted module for implementation-phase codex exec review invocation.
hooks/lib/loop-codex-handlers.sh New extracted module for phase transitions and blocking decision payloads.
hooks/lib/loop-codex-exit-handlers.sh New extracted module for exit/finalize/review-failure decision handling.
hooks/lib/loop-bg-tasks.sh Portability fix: replace sed frontmatter parsing with awk for session-id filtering.
docs/usage.md Adds gen-idea / explore-idea command reference and artifacts overview.
docs/runtime-spike-results.md Adds recorded manual spike evidence/checklist for explore-idea behavior.
commands/gen-idea.md Updates spec to dual-write draft + companion JSON; adds schema validation and cleanup rules.
commands/explore-idea.md Adds full explore-idea coordinator workflow spec (validation, confirmation, manifest, dispatch, collection, report).
.gitignore Ignores .claude/worktrees/ and a removed/refactor-leftover helper path.
.claude/CLAUDE.md Documents cross-file sync requirements for schema and explore-idea constraints.
.claude-plugin/plugin.json Version bump to 1.17.0.
.claude-plugin/marketplace.json Version bump to 1.17.0.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +320 to +324
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
if git -C "$PROJECT_ROOT" diff --name-only HEAD 2>/dev/null | grep -q .; then
echo "ERROR: Main checkout has uncommitted tracked changes." >&2
echo " Commit or stash changes before running explore-idea." >&2
echo " Dirty files:" >&2
Comment on lines +346 to +349
# Worker base-anchor contract (enforced by worker-prompt.md):
# Each worker MUST: (1) git checkout BASE_BRANCH in its worktree,
# (2) assert HEAD == BASE_COMMIT, and (3) only then create the explore branch.
# A HEAD mismatch is a fatal worker error (worker emits failure result immediately).
Comment on lines +84 to +86
if ! codex --help 2>&1 | grep -q -- '--disable'; then
die "Installed Codex CLI supports codex_hooks but lacks the --disable flag. Humanize's stop hook uses --disable codex_hooks to prevent recursive hook invocation. Please upgrade Codex."
fi
Comment thread scripts/ask-codex.sh
Comment on lines +249 to +253
if [[ -f "$_CODEX_DISABLE_HOOKS_CACHE" ]]; then
[[ "$(cat "$_CODEX_DISABLE_HOOKS_CACHE")" == "yes" ]] && CODEX_DISABLE_HOOKS_ARGS=(--disable codex_hooks)
elif codex --help </dev/null 2>&1 | grep -q -- '--disable'; then
CODEX_DISABLE_HOOKS_ARGS=(--disable codex_hooks)
echo "yes" > "$_CODEX_DISABLE_HOOKS_CACHE" 2>/dev/null || true
Comment on lines +112 to +116
"summary_markdown"
"what_worked"
"what_didnt"
"bitlesson_action"
)
Comment on lines +144 to +148
# No git push constraint
if grep -q "No git push\|git push" "$WORKER_PROMPT"; then
pass "template forbids git push"
else
fail "template forbids git push"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants