feat(plan-check): add plan validation workflows#117
Open
ZenusZhang wants to merge 2 commits into
Open
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new plan-check validation/reporting workflow (plus Codex skill wiring) and integrates gen-plan check mode controls/config to support draft + plan validation/repair flows.
Changes:
- Introduces deterministic plan-check backend: schema validation helpers, IO validation, findings/report assembly, and a Codex skill entrypoint.
- Extends gen-plan with
--check/--no-checkflags +gen_plan_checkconfig resolution and updates docs/tests accordingly. - Improves hook/install robustness: symlink-tolerant goal-tracker path matching, methodology-analysis completion gating, and Codex hooks installer dry-run behavior.
Reviewed changes
Copilot reviewed 48 out of 49 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test-unified-codex-config.sh | Ensures tests run with isolated XDG config home for defaults validation. |
| tests/test-plan-check.sh | Adds fixture-style tests for schema validation, report assembly, rewrite/recheck behavior, and regression cases. |
| tests/test-methodology-analysis.sh | Adds tests for readiness vs completion behavior in methodology analysis flow. |
| tests/test-gen-plan.sh | Adds assertions for --check/--no-check + gen_plan_check documentation and validator behavior. |
| tests/test-gen-idea.sh | Adds tests for raw-argument parsing behavior in gen-idea IO validation. |
| tests/test-config-merge.sh | Adds coverage for plan_check_recheck + gen_plan_check merged-config behavior. |
| tests/test-codex-hook-install.sh | Adds coverage for hooks installer existence, large codex features list, dry-run behavior, and plan-check skill installation. |
| tests/test-bitlesson-select-routing.sh | Adds regression test for empty codex_model fallback under nounset. |
| tests/test-ask-codex.sh | Verifies nested codex exec disables codex_hooks when supported. |
| tests/test-allowlist-validators.sh | Adds coverage for blocking stale same-round loop contract edits. |
| tests/run-all-tests.sh | Wires new plan-check and gen-plan-check suites into the overall test runner. |
| tests/robustness/test-hook-system-robustness.sh | Adds symlink-root coverage for goal-tracker read/write/edit validators and backtick-literal regression assertion. |
| tests/fixtures/gen-plan-check/default-template.md | Adds fixture template for gen-plan check-mode tests. |
| tests/fixtures/gen-plan-check/default-expected.md | Adds expected output fixture for gen-plan check-mode tests. |
| tests/fixtures/gen-plan-check/default-draft.md | Adds draft fixture for gen-plan check-mode tests. |
| skills/humanize-plan-check/SKILL.md | Adds Codex flow entrypoint documentation for plan-check. |
| skills/humanize-gen-plan/SKILL.md | Documents check-mode flags and config priority in the gen-plan skill. |
| scripts/validate-plan-check-io.sh | Adds IO validator for plan-check (plan existence, output dir resolution/creation, permissions, flags). |
| scripts/validate-gen-plan-io.sh | Adds --check/--no-check flags to the gen-plan IO validator and usage output. |
| scripts/validate-gen-idea-io.sh | Adds --raw-arguments parsing mode to preserve/normalize inline idea text and flags. |
| scripts/plan-check.sh | Adds deterministic report assembler: validates findings array schema, writes findings.json + report.md. |
| scripts/lib/plan-check-common.sh | Adds shared plan-check library: schema validators, report helpers, rewrite helpers, config resolution, ambiguity ID postprocessing. |
| scripts/lib/gen-plan-check-mode.sh | Adds resolver implementing --no-check > --check > config > default priority. |
| scripts/install-skill.sh | Ensures humanize-plan-check is installed and improves DRY-RUN behavior ordering. |
| scripts/install-codex-hooks.sh | Avoids probing Codex features during dry-run; improves feature-list probing robustness. |
| scripts/bitlesson-select.sh | Sources loop-common earlier to ensure default model is initialized under set -u. |
| scripts/ask-codex.sh | Disables Codex hooks for nested codex exec runs when supported by installed CLI. |
| hooks/loop-write-validator.sh | Uses new symlink-tolerant loop_paths_match for goal-tracker path checks. |
| hooks/loop-read-validator.sh | Uses new symlink-tolerant loop_paths_match for goal-tracker path checks. |
| hooks/loop-edit-validator.sh | Uses loop_paths_match for goal-tracker + adds “wrong directory path” validation for loop edits. |
| hooks/loop-codex-stop-hook.sh | Separates methodology readiness gate from completion mutation; ensures completion is finalized before exit. |
| hooks/lib/methodology-analysis.sh | Splits readiness check from completion logic to avoid side effects during gating. |
| hooks/lib/loop-common.sh | Adds loop_paths_match helper; adjusts fallback text escaping for backticks. |
| docs/usage.md | Documents new plan-check command and gen-plan check-mode behavior/config. |
| docs/install-for-kimi.md | Documents installing the new humanize-plan-check skill. |
| docs/install-for-codex.md | Documents installing the new humanize-plan-check skill. |
| config/default_config.json | Adds defaults for plan_check_recheck and gen_plan_check. |
| commands/plan-check.md | Adds Claude command spec for plan-check workflow and sub-agent contract. |
| commands/gen-plan.md | Adds check-mode spec (draft check + plan check/repair + gating) and new allowed tools. |
| commands/gen-idea.md | Switches gen-idea validation to --raw-arguments mode. |
| agents/plan-consistency-checker.md | Adds agent spec for plan contradiction detection output schema. |
| agents/plan-ambiguity-checker.md | Adds agent spec for plan ambiguity detection with stable, hash-based IDs. |
| agents/draft-plan-drift-checker.md | Adds drift checker spec used only to explain existing primary findings from sources. |
| agents/draft-consistency-checker.md | Adds draft contradiction checker spec. |
| agents/draft-ambiguity-checker.md | Adds draft ambiguity checker spec with stable IDs. |
| README.md | Bumps version to 1.17.0. |
| .claude-plugin/plugin.json | Bumps plugin version to 1.17.0. |
| .claude-plugin/marketplace.json | Bumps marketplace version to 1.17.0. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4c89cf94fd
ℹ️ 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".
Add the standalone plan-check command, Codex/Kimi skill wiring, shared validation helpers, and integrated gen-plan check mode with draft and plan repair flows. Squashed from the local RLCR iteration history on top of the latest origin/dev; excludes the ask-gemini command/test follow-up from this plan-check PR.
Contributor
|
@codex review again |
|
Codex Review: Didn't find any major issues. Another round soon, please! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Contributor
|
@ZenusZhang Resolve conflicts please. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds Humanize plan validation workflows and wires them into both standalone plan checking and optional
gen-plan --checkexecution.It introduces:
/humanize:plan-checkflow with IO validation, deterministic schema checks, semantic contradiction/ambiguity checks, report generation, resolution tracking, optional in-place repair, and optional recheck./humanize:gen-plan --checkmode that checks the draft before plan generation, checks the generated plan afterward, repairs blocker findings using source-of-truth precedence, and gates optional RLCR auto-start on unresolved draft/plan blockers.Key Behavior
Standalone plan-check
/humanize:plan-check --plan <plan.md>now validates a plan before implementation begins:.humanize/plan-check/<timestamp>/;--recheckorplan_check_recheck=truecan run one post-repair validation pass.gen-plan check mode
/humanize:gen-plan --checkandgen_plan_check=truenow add two gates around plan generation:check-draftruns after relevance validation and before the output plan is created. Draft contradiction/ambiguity blockers must be clarified before generation continues.check-planruns after the plan body is generated. It merges schema findings, primary semantic findings, and conditional draft-plan drift findings, then repairs blockers using this precedence: explicit user answers, original draft text, repository facts discovered during planning, safe leader-agent judgment, then generated plan text.Check-mode artifacts are written flat under
.humanize/gen-plan-check/<timestamp>/; temporary files stay undertmp/and are cleaned up before exit.Codex Checker Isolation
The Codex skill port now explicitly treats effective check mode as a request for native checker sub-agents instead of parent-session self-review.
For Codex:
humanize-gen-planspawns native checker agents for draft consistency, draft ambiguity, plan consistency, plan ambiguity, and conditional draft-plan drift checks.humanize-plan-checkspawns native checker agents for plan consistency and plan ambiguity checks.fork_context=falseand receive only the checker instructions plus the exact draft or plan content needed for that checker.draft-plan-drift-checkeris the only intentionally broader checker, and its payload is still bounded to plan body, original draft content, collected clarifications, and primary plan findings.This closes the Codex behavior gap where
gen-plan --checkcould previously read checker prompts and perform semantic review directly in the parent session.Tests
Validated with:
bash tests/test-gen-plan.shbash tests/test-plan-check.shbash tests/test-gen-plan-check.shgit diff --check