feat(ce-compound): add lightweight headless depth

[yaniv256]

Summary

Adds an explicit depth selector for unattended ce-compound runs:

• mode:headless depth:lightweight uses the existing single-pass Lightweight workflow
• mode:headless depth:full uses Full, including the automatic session-history probe
• plain mode:headless remains a backward-compatible alias for Full

Lightweight keeps the same solution-doc artifact type, deterministic claims check, and frontmatter parser-safety check, but deliberately skips parallel research subagents, overlap and duplicate detection, session-history research, and semantic grounding validation. Unknown, conflicting, or non-headless depth: flags fail with Documentation skipped.

Before writing, Lightweight checks the exact proposed solution path. It updates an occupied path only when the existing document covers the same problem; otherwise it selects a distinct unused filename. This prevents unattended retries from overwriting unrelated learnings without adding Full mode's semantic overlap research.

Lightweight evaluates docs/solutions/ discoverability from the active project instructions already in context. It never reopens or edits instruction files. When no project instructions are active, the terminal report records not applicable instead of inventing a gap result. When Lightweight refines CONCEPTS.md, the headless report separately records whether those active instructions surface the shared vocabulary.

This is a focused implementation of the unattended depth request explored in #662. Thanks @benwilson for the earlier design and evaluation work, and @yaniv256 for the implementation in this PR.

Validation

• bun test ./tests/skills/ce-compound-headless-depth.test.ts: 13 pass
• bun run release:validate: passed
• bun run plugin:validate: passed
• bun test: 2,094 pass
• Fresh skill-creator checks: explicit headless Lightweight completed without child dispatch; plain headless selected Full and dispatched generic child agents; a repository without active project instructions reported discoverability as not applicable; a post-review Lightweight run completed only after the manual frontmatter parser-safety check passed; a run that refined CONCEPTS.md reported its instruction-file discoverability gap; an occupied-path run preserved the unrelated existing document and created the learning at a distinct unused path

---

[tmchow]

Thanks for the contribution. I pushed a follow-up commit to this branch.

The selector itself is useful, but the first version had a few contract problems:

• it said every headless run probes session history, which is false for Lightweight
• Lightweight had two competing completion templates
• the docs described the route as bounded and equivalent to Full even though it skips overlap detection, session history, and semantic grounding
• the tests checked selector wording but did not cover those contradictions
• the change overlaps with feat(ce-compound): add headless mode:autofix with depth selector #662 and needed to acknowledge that earlier work

I tightened the routing prose, made the reduced coverage explicit, added regression guards, and removed the pending-PR solution note. The focused tests, full suite, release validation, plugin validation, and fresh behavior checks all pass. The PR description now reflects the final behavior.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 43df43c708

ℹ️ 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".

[yaniv256]

Reviewed the follow-up at 43df43c7. The contract now matches the intended split: session-history probing is Full-only, headless Lightweight has one completion path, reduced coverage is explicit, the regression tests cover the prior contradictions, and the PR now acknowledges #662.

I also addressed the remaining discoverability inconsistency in 48f508c7. Lightweight now performs a read-only docs/solutions/ instruction-file discoverability check before reporting no gap or gap noted; it still never edits instruction files. A regression test verifies that the check is present and precedes completion reporting.

Validation at 48f508c7: focused tests 9/9, release validation passed, plugin validation passed, and the full suite passed 2,090/2,090.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7e414aff64

ℹ️ 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".

[tmchow]

@yaniv256 You found a smaller valid issue (Lightweight needed to evaluate discoverability before reporting a result). I had to implement a followup though to fix an issue you added:

• the skill referenced a Phase 2.6 that does not exist
• Lightweight was routed back through named instruction files even though project instructions are already loaded by the harness
• repositories without active project instructions had no accurate report state

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 256ad42d4a

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b3935d529c

ℹ️ 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".

[yaniv256]

I reviewed the current branch through f52aa1d4. The 48f508c7 follow-up addressed the missing discoverability evaluation but introduced three incorrect assumptions: it referenced a nonexistent phase, treated active project instructions as files to reopen rather than harness-provided context, and omitted the no-active-instructions state. Your 7e414aff correction resolves those issues.

I also reviewed the later fixes. Headless Lightweight now preserves frontmatter parser-safety validation, reports CONCEPTS.md discoverability when vocabulary changes, and guards exact output paths before writing. Both CI checks pass, and the current head is ready for maintainer review.

For any further changes, I’ll check the complete Lightweight workflow against the harness contract and the existing work in #662 before pushing.

[tmchow]

I reviewed the current branch through f52aa1d4. The 48f508c7 follow-up addressed the missing discoverability evaluation but introduced three incorrect assumptions: it referenced a nonexistent phase, treated active project instructions as files to reopen rather than harness-provided context, and omitted the no-active-instructions state. Your 7e414aff correction resolves those issues.

I also reviewed the later fixes. Headless Lightweight now preserves frontmatter parser-safety validation, reports CONCEPTS.md discoverability when vocabulary changes, and guards exact output paths before writing. Both CI checks pass, and the current head is ready for maintainer review.

For any further changes, I’ll check the complete Lightweight workflow against the harness contract and the existing work in #662 before pushing.

@yaniv256 Please make sure humans are reviewing your contributions and comments to the repo.