') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); })(); feat(plan-check): add plan validation workflows by ZenusZhang · Pull Request #117 · PolyArch/humanize · GitHub
Skip to content

feat(plan-check): add plan validation workflows - #117

Open
ZenusZhang wants to merge 2 commits into
PolyArch:devfrom
ZenusZhang:plan-check
Open

feat(plan-check): add plan validation workflows#117
ZenusZhang wants to merge 2 commits into
PolyArch:devfrom
ZenusZhang:plan-check

Conversation

@ZenusZhang

@ZenusZhangZenusZhang commented Apr 27, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

This PR adds Humanize plan validation workflows and wires them into both standalone plan checking and optional gen-plan --check execution.

It introduces:

  • A standalone /humanize:plan-check flow with IO validation, deterministic schema checks, semantic contradiction/ambiguity checks, report generation, resolution tracking, optional in-place repair, and optional recheck.
  • Integrated /humanize:gen-plan --check mode 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.
  • Checker agent specs for draft consistency, draft ambiguity, plan consistency, plan ambiguity, and draft-plan drift recovery.
  • Runtime helpers and tests for schema validation, finding normalization, ambiguity ID post-processing, rewrite backup/atomic write, artifact layout, and check-mode flow behavior.
  • Codex/Kimi skill wiring and usage docs for the new plan-check and gen-plan check-mode entrypoints.

Key Behavior

Standalone plan-check

/humanize:plan-check --plan <plan.md> now validates a plan before implementation begins:

  • deterministic schema validation uses the canonical gen-plan template;
  • semantic checks identify hard contradictions and execution-affecting ambiguities;
  • findings are written under .humanize/plan-check/<timestamp>/;
  • blocker findings can be resolved interactively;
  • accepted rewrites create backups and use atomic writes;
  • --recheck or plan_check_recheck=true can run one post-repair validation pass.

gen-plan check mode

/humanize:gen-plan --check and gen_plan_check=true now add two gates around plan generation:

  • check-draft runs after relevance validation and before the output plan is created. Draft contradiction/ambiguity blockers must be clarified before generation continues.
  • check-plan runs 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 under tmp/ 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-plan spawns native checker agents for draft consistency, draft ambiguity, plan consistency, plan ambiguity, and conditional draft-plan drift checks.
  • humanize-plan-check spawns native checker agents for plan consistency and plan ambiguity checks.
  • Checker agents use fork_context=false and receive only the checker instructions plus the exact draft or plan content needed for that checker.
  • They do not receive prior conversation history, project history, or unrelated repository context.
  • draft-plan-drift-checker is 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 --check could previously read checker prompts and perform semantic review directly in the parent session.

Tests

Validated with:

  • bash tests/test-gen-plan.sh
  • bash tests/test-plan-check.sh
  • bash tests/test-gen-plan-check.sh
  • git diff --check

CopilotAI review requested due to automatic review settings April 27, 2026 03:33
CopilotAI reviewed Apr 27, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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-check flags + gen_plan_check config 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
FileDescription
tests/test-unified-codex-config.shEnsures tests run with isolated XDG config home for defaults validation.
tests/test-plan-check.shAdds fixture-style tests for schema validation, report assembly, rewrite/recheck behavior, and regression cases.
tests/test-methodology-analysis.shAdds tests for readiness vs completion behavior in methodology analysis flow.
tests/test-gen-plan.shAdds assertions for --check/--no-check + gen_plan_check documentation and validator behavior.
tests/test-gen-idea.shAdds tests for raw-argument parsing behavior in gen-idea IO validation.
tests/test-config-merge.shAdds coverage for plan_check_recheck + gen_plan_check merged-config behavior.
tests/test-codex-hook-install.shAdds coverage for hooks installer existence, large codex features list, dry-run behavior, and plan-check skill installation.
tests/test-bitlesson-select-routing.shAdds regression test for empty codex_model fallback under nounset.
tests/test-ask-codex.shVerifies nested codex exec disables codex_hooks when supported.
tests/test-allowlist-validators.shAdds coverage for blocking stale same-round loop contract edits.
tests/run-all-tests.shWires new plan-check and gen-plan-check suites into the overall test runner.
tests/robustness/test-hook-system-robustness.shAdds symlink-root coverage for goal-tracker read/write/edit validators and backtick-literal regression assertion.
tests/fixtures/gen-plan-check/default-template.mdAdds fixture template for gen-plan check-mode tests.
tests/fixtures/gen-plan-check/default-expected.mdAdds expected output fixture for gen-plan check-mode tests.
tests/fixtures/gen-plan-check/default-draft.mdAdds draft fixture for gen-plan check-mode tests.
skills/humanize-plan-check/SKILL.mdAdds Codex flow entrypoint documentation for plan-check.
skills/humanize-gen-plan/SKILL.mdDocuments check-mode flags and config priority in the gen-plan skill.
scripts/validate-plan-check-io.shAdds IO validator for plan-check (plan existence, output dir resolution/creation, permissions, flags).
scripts/validate-gen-plan-io.shAdds --check/--no-check flags to the gen-plan IO validator and usage output.
scripts/validate-gen-idea-io.shAdds --raw-arguments parsing mode to preserve/normalize inline idea text and flags.
scripts/plan-check.shAdds deterministic report assembler: validates findings array schema, writes findings.json + report.md.
scripts/lib/plan-check-common.shAdds shared plan-check library: schema validators, report helpers, rewrite helpers, config resolution, ambiguity ID postprocessing.
scripts/lib/gen-plan-check-mode.shAdds resolver implementing --no-check > --check > config > default priority.
scripts/install-skill.shEnsures humanize-plan-check is installed and improves DRY-RUN behavior ordering.
scripts/install-codex-hooks.shAvoids probing Codex features during dry-run; improves feature-list probing robustness.
scripts/bitlesson-select.shSources loop-common earlier to ensure default model is initialized under set -u.
scripts/ask-codex.shDisables Codex hooks for nested codex exec runs when supported by installed CLI.
hooks/loop-write-validator.shUses new symlink-tolerant loop_paths_match for goal-tracker path checks.
hooks/loop-read-validator.shUses new symlink-tolerant loop_paths_match for goal-tracker path checks.
hooks/loop-edit-validator.shUses loop_paths_match for goal-tracker + adds “wrong directory path” validation for loop edits.
hooks/loop-codex-stop-hook.shSeparates methodology readiness gate from completion mutation; ensures completion is finalized before exit.
hooks/lib/methodology-analysis.shSplits readiness check from completion logic to avoid side effects during gating.
hooks/lib/loop-common.shAdds loop_paths_match helper; adjusts fallback text escaping for backticks.
docs/usage.mdDocuments new plan-check command and gen-plan check-mode behavior/config.
docs/install-for-kimi.mdDocuments installing the new humanize-plan-check skill.
docs/install-for-codex.mdDocuments installing the new humanize-plan-check skill.
config/default_config.jsonAdds defaults for plan_check_recheck and gen_plan_check.
commands/plan-check.mdAdds Claude command spec for plan-check workflow and sub-agent contract.
commands/gen-plan.mdAdds check-mode spec (draft check + plan check/repair + gating) and new allowed tools.
commands/gen-idea.mdSwitches gen-idea validation to --raw-arguments mode.
agents/plan-consistency-checker.mdAdds agent spec for plan contradiction detection output schema.
agents/plan-ambiguity-checker.mdAdds agent spec for plan ambiguity detection with stable, hash-based IDs.
agents/draft-plan-drift-checker.mdAdds drift checker spec used only to explain existing primary findings from sources.
agents/draft-consistency-checker.mdAdds draft contradiction checker spec.
agents/draft-ambiguity-checker.mdAdds draft ambiguity checker spec with stable IDs.
README.mdBumps version to 1.17.0.
.claude-plugin/plugin.jsonBumps plugin version to 1.17.0.
.claude-plugin/marketplace.jsonBumps marketplace version to 1.17.0.

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

Comment threadtests/test-config-merge.sh Outdated
Comment threadscripts/validate-plan-check-io.sh Outdated
Comment threadscripts/lib/plan-check-common.sh Outdated
Comment threadscripts/lib/plan-check-common.sh Outdated
chatgpt-codex-connector[bot]
chatgpt-codex-connectorBot reviewed Apr 27, 2026
View reviewed changes

@chatgpt-codex-connectorchatgpt-codex-connectorBot left a comment

Copy link
Copy Markdown

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: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".

Comment threadscripts/lib/plan-check-common.sh Outdated
Comment threadscripts/lib/plan-check-common.sh
zenus
feat(plan-check): add plan validation workflows
67bad96
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.
@zevorn

zevorn commented May 12, 2026

Copy link
Copy Markdown
Contributor

@codex review again

@chatgpt-codex-connector

chatgpt-codex-connectorBot commented May 12, 2026

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Another round soon, please!

ℹ️ About Codex in GitHub

Your team has set up Codex to 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 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@zevorn

zevorn commented May 13, 2026

Copy link
Copy Markdown
Contributor

@ZenusZhang Resolve conflicts please.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code reviewCopilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@chatgpt-codex-connectorchatgpt-codex-connector[bot]chatgpt-codex-connector[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@ZenusZhang@zevorn