Teach rule candidate capture through the installed skill

[rob-archastro]

Review on ArchCode

Task: Codex sessions brainstorm repository rules and open a rules PR

Problem and author intent

The installed ArchDev skill described capturing a rule candidate, but it did not guide an agent through the current path from a concrete correction to a repository rule pair, a session candidate, and the customer-owned rules PR. Customers need the agent to keep those separate actions explicit so a brainstorming session does not silently activate policy or open a PR.

What changed

The core skill now points to a focused rule-candidates reference. It tells the agent to turn a correction into one checkable PR-diff obligation, inspect the repository adopt_to path and existing rule pairs, draft a Markdown/JEV pair, propose it only on the user's request, and verify the candidate with archdev rules candidates. The .md uses name, description, and date frontmatter, with no hand-authored sources; the .jev asks applicable and complies questions over the PR diff and relevant repository context. The agent runs archdev rules pr only after a separate explicit request and passes the full theme key. It does not edit adopted repository rules directly.

The eight generated harness plugin copies were refreshed from the canonical skill. The branch was rebased onto current main; the unrelated harness-setup commit formerly on this PR is already superseded on main and is absent from this branch.

Scope, risk, and user impact

• Scope: Agent guidance only, in the canonical skill and generated copies.
• Risk: Medium. An unclear instruction could lead to a noisy candidate or unwanted PR. The guidance requires explicit authorization for both writes, and candidates stay inert until a customer merges a rules PR.
• User impact: A customer using the installed skill can brainstorm, propose, inspect, and then request one rules PR without manually writing adopted policy files.
• Rollout: Hold this PR open and unmerged until the customer rollout decision.

Testing

• node tools/plugin-gen/src/cli.ts check: all 140 generated files match the catalog.
• node --test tools/plugin-gen/test/*.test.ts: 62/62 pass. .github/workflows/plugins.yml runs these checks on PRs.
• bash scripts/test-skill-bootstrap-cli.sh: passes against the released ArchDev CLI 0.52.1. .github/workflows/skill-bootstrap-checks.yml runs placement proofs on PRs. The Windows proof was not run locally; CI covers it.
• git diff --check origin/main...HEAD: passes.
• Fresh session proof: A new Codex session loaded this branch's skill from a clean firstlanding scratch checkout, inspected AGENTS.md, .archdev/rules.yaml, existing rule pairs and CI workflows, drafted the pair outside the repository, invoked archdev rules propose, and then found candidate rc_edd4dfee7bf526255a38f4ec41c610c0152aa925c564497b7c540e3b1a9ae334 open with source session and the expected theme and stored Markdown. The parent session independently repeated the candidate lookup and confirmed no repository source edits. After the production fix in firstlanding PR 18113 deployed, archdev rules pr opened firstlanding PR 18152 as the signed-in human. GitHub shows one open PR, one rules branch, and exactly the Markdown/JEV pair. The recorded transcript is local at /private/tmp/archdev-codex-proof-transcript.jsonl; it is not a CI artifact or publicly linked from this PR.

The first two rules pr attempts returned 502 on the old production GitHub service. The merged tree-response fix was absent from that production image; after production promotion completed, the same selection succeeded. No browser page proof was run because the user did not request browser access.

The fresh-session proof also exposed a rule-design gap: the firstlanding rule asks the checker to trace CI files that are usually unchanged, while the checker receives only the PR diff, title and description, and changed paths. The skill now tells agents to narrow or reject obligations that cannot be judged from those inputs. The proof rule in firstlanding PR 18152 remains open for separate review; its current wording should not be treated as a validated checker example.

Follow-ups

• Keep both this public skill PR and the firstlanding rules PR open for human review and rollout; do not merge either automatically.
• Attach or link a sanitized transcript if reviewers need to inspect the full fresh-session exchange.

[rob-archastro]

Orchestrator (repo-rules epic): in references/rule-candidates.md, "Follow the repository's rules/README.md when present" sends agents to an unrelated rules/ folder in most repos. The canonical rule format is the .md + .jev pair under adopt_to (default .archdev/rules/). Point the agent at the existing pairs that .archdev/rules.yaml lists, or at the default spec when none exist.

[rob-archastro]

Changed the guidance to read .archdev/rules.yaml and inspect existing .md + .jev pairs matched by its include patterns. adopt_to is explicitly the proposal destination, defaulting to .archdev/rules/. When no pairs exist, agents use the documented default Markdown/Jev format. Removed the unrelated rules/README.md instruction and regenerated all eight plugin copies. Generation check and all 62 plugin tests pass.

[rob-archastro]

Fixed the placement failures in 92097a7. The released CLI now defaults local setup to detected harnesses; all-harness setup requires explicit --all-harnesses. The skill/reference and generated copies now describe that behavior. Both placement proofs first assert detected-only setup, then explicitly request and verify all six harnesses while retaining the personal-config and uninstall-opt-out checks.

All three PR workflows now pass, including the released-CLI proof on Linux and native Windows PowerShell. The Bash proof also passed locally against checksum-verified CLI 0.50.4. This PR remains draft pending the CLI feature release. GitHub currently reports rebaseable=true.