fix(setup): honor provider roots and calibrate agent workflows

.github/pull_request_template.md

@@ -13,6 +13,15 @@ Keep this receipt factual. If a check was not run, say why.
 - Related product / engineering / continuity docs:
 - Breaking change, migration, or rollout note: None / describe
 
+## PR size
+
+- Counted additions + deletions against the PR base:
+- Excluded generated/lockfile/pure-rename/binary paths and reasons: None / describe
+- Above 500 lines: why keeping this change together improves review:
+- Above 1,000 lines: split plan, or explicit independent-reviewer exception
+  (reviewed head, rationale, and review approach):
+  <!-- If independent review was user-waived, record the user's separate size exception. -->
+
 ## Verification
 
 - Focused checks:

AGENTS.md

@@ -56,6 +56,32 @@ facts. It is not an agent-policy source.
 - Sandbox authorization to access the parent registry or a sibling target does
   not load that sibling's instructions into this session.
 
+## Product-delivery hook
+
+The installed `~/.agents/workflows/product-delivery/` contract applies to this
+repository, not only to the projects it seeds. In addition to its explicit
+role, user-request, and active-artifact triggers, its complete flow activates
+when a change alters any of these contracts:
+
+- installation ownership, target boundaries, overwrite or recovery behavior;
+- skill acquisition sources, reviewed revisions/hashes, or integrity validation;
+- provider adapter fields, discovery locations, or generated instruction meaning;
+- workflow activation, approval, delegation, or required review policy;
+- the hard invariants above, or guidance propagated into sibling projects.
+
+Check the resulting behavior and contract diff in `workflows/`, templates,
+manifests, scripts, and owning guidance. A path match alone does not activate
+the flow. Typo/link corrections, reflow, tests of unchanged behavior, and
+internal refactors preserving these contracts are maintenance. Record the
+classification and evidence; any listed contract change activates the full
+flow even if most of the diff is maintenance. Continuity-only updates remain
+outside it unless they continue an active workflow artifact.
+
+Independent review means a fresh reviewer that did not make the change: the
+installed Verifier role unless the user names another. When a listed condition
+matches and the workflow or its review is not run, say so and record it; an
+unrecorded skip is a process failure, not a judgment call.
+
 ## Working method
 
 - Keep changes scoped to the requested behavior and its necessary cleanup.
@@ -83,3 +109,10 @@ The full regression suite is the primary gate. Guidance changes also require
 path, import, byte-budget, and internal-consistency checks. Line targets are
 readability warnings, not CI gates. Report skipped host-capability checks and
 unverified external behavior explicitly.
+
+Every implementation, including maintenance outside the full workflow, needs
+implementer verification and one fresh independent review before local
+completion. Delegate it to the installed Verifier (`mb_verifier` in Codex,
+`mb-verifier` in Claude), unless the user names another reviewer. Only the user
+may waive review for a specific change; record the waiver without calling it
+passed. This requirement does not activate the full workflow by itself.

CLAUDE.md

@@ -5,3 +5,7 @@
 Use Claude Code's current official loading and configuration documentation when
 changing project starter guidance or generated adapters. Keep provider-specific
 tool mechanics here; shared policy belongs in `AGENTS.md`.
+
+The installed Verifier role is the generated `mb-verifier` subagent. When a
+project also defines its own `verifier`, name which one satisfies independent
+review before relying on it.

CONTINUITY.md

@@ -12,6 +12,12 @@ is read only when a task needs it.
 
 ## Snapshot
 
+- 2026-09-08 [USER+CODE] PR size policy: 500-line target, 1,000-line review gate;
+  counting and exceptions live in each Git contract and PR template.
+
+- 2026-09-07 [USER+CODE] Codex-first calibration: custom provider roots and
+  maintenance/review policy (D025). Source findings, verification and recorded
+  process deviation: `docs/provider-calibration-2026-09-07.md`.
 - 2026-08-14 [USER+CODE] Sibling-only ownership replaces the workspace router
   (D005, D017, D021): the parent has optional inert `MACHINE.md` but no live
   `AGENTS.md`, `CLAUDE.md`, or `_templates/`. Machine-bootstrap and every project
@@ -52,6 +58,10 @@ is read only when a task needs it.
   project work. Standalone Verifier selection activates only independent review.
 - 2026-08-13 [USER] Every implementation defaults to implementer verification
   plus one fresh independent review; only the user may waive it per change.
+- 2026-08-19 [USER+CODE] Workflow activation must be stated as checkable
+  conditions, the independent reviewer is named rather than implied, an
+  unrecorded skip is a process failure, and this repository applies the
+  workflow to itself (D024).
 - 2026-08-13 [USER] Dependency versions come from current official sources.
   Prefer the latest compatible stable release, preserve package-manager/range
   policy, update tracked lockfiles, and explain older or prerelease choices.
@@ -119,25 +129,28 @@ Milestones — detail in `docs/continuity/2026-07.md`:
 - 2026-08-14 [USER] D023 ACTIVE: document agent-assisted setup as a normal
   interface. Natural-language requests select the target and outcome; audited
   scripts remain the execution and verification layer.
+- 2026-08-19 [USER+CODE] D024 ACTIVE: workflow triggers are checkable conditions, not
+  self-assessed judgment; the satisfying reviewer is named; skips are recorded;
+  and machine-bootstrap is in scope for its own workflow. Provider adapters own
+  harness mechanics; README and shared reviewer guidance name provider roles.
+
+- 2026-09-07 [USER+CODE] D025 ACTIVE: Codex desktop is the primary documented
+  entry; Claude retains native loading. Workflow triggers name changed contracts;
+  maintenance keeps fresh review and existing user authorization carries forward.
 
 ## Working Set
 
 - `AGENTS.md`, `CLAUDE.md`, `README.md`, `INIT.md`, `CONTINUITY.md`
 - `.github/{pull_request_template.md,workflows/bootstrap.yml}`
-- `machine-templates/`
-- `project-templates/`
+- `machine-templates/`, `project-templates/`
 - `docs/{engineering/git-workflow.md,guidance-loading-smoke.md,continuity/}`
-- `scripts/{init-workspace,init-project,test-bootstrap}.mjs`
-- `scripts/{install-skills,install-workflows}.mjs`
+- `scripts/{init-workspace,init-project,test-bootstrap,install-skills,install-workflows}.mjs`
 - `scripts/lib/{fs-safety,portable-path,skill-*,workflow-*}.mjs`
 - `skills.json`, `workflows/`
 
 ## Next
 
 - Keep scratch optional and disposable; promote durable work into its own
   sibling repository with project guidance.
-- Add a private remote only with explicit user authorization.
-
-## Open Questions
-
-- 2026-07-27 [USER] UNCONFIRMED which private remote will host this repository.
+- Impeccable 4.0.2 restored with explicit user authorization and a recoverable
+  4.0.4 backup; retain the pin until a freshly reviewed upgrade recommendation.

INIT.md

@@ -67,3 +67,11 @@ access does not load sibling instructions.
 Use `--skip-skills` or `--skip-workflows` only when the user explicitly wants
 that shared layer left untouched. Installing `product-delivery` makes its roles
 available but does not activate the workflow for ordinary work.
+
+Codex desktop is the primary interactive entry; use the task prompts in
+`README.md`. CLI profiles configure new CLI sessions only. Verify the selected
+provider roots: workflow adapters and Claude skill links honor
+`CLAUDE_CONFIG_DIR`; Codex adapters and duplicate-skill checks honor `CODEX_HOME`.
+Canonical shared skills remain under `~/.agents/skills/`. Use the expanded
+default/custom-root and nested-loading checks in `docs/guidance-loading-smoke.md`
+when establishing runtime support. Report unrun scenarios explicitly.

README.md

@@ -174,6 +174,22 @@ Verifier activates only independent verification for the supplied change; it
 does not retroactively create missing upstream gates or artifacts. Ordinary
 work creates neither by default.
 
+For this repository, `AGENTS.md` names the activating contracts: installation
+ownership and recovery, acquisition integrity, provider formats/discovery,
+workflow policy, hard invariants, and propagation to siblings. Mechanical
+maintenance that preserves those contracts stays outside the full flow. Every
+implementation still receives self-verification and fresh independent review
+before local completion. Record the classification rather than judging a task
+by its apparent size. Existing project-owned starters are never synchronized
+when these defaults change.
+
+The Git contracts and PR templates use a 500-line target and a 1,000-line
+review gate, measured as additions plus deletions. Changes over 1,000 require a
+split or an explicit reviewer exception; generated/lockfile/rename/binary
+changes are reported separately. See `docs/engineering/git-workflow.md` for
+counting, exceptions, and review requirements. These gates are guidance for
+both providers, not an automated CI size limit.
+
 ### The three roles
 
 | Role | Owns | Claude agent | Codex agent |
@@ -244,6 +260,45 @@ it does not read or write `settings.json` in the Claude configuration root or
 
 ### Launching a role
 
+#### Codex desktop (primary workspace)
+
+Open a task in the target repository, then state the outcome in ordinary
+language. Root guidance routes routine work; inspect the nearest scoped guide
+before editing a subtree. Use a fresh task starting in that scope when relying
+on automatic nested instruction discovery.
+
+For ordinary implementation:
+
+> Implement the requested change within the existing contract. Run the affected
+> checks, then delegate a fresh independent review to `mb_verifier`. Report the
+> evidence and unresolved findings. Keep changes local.
+
+For a review without implementation:
+
+> Delegate review of the current changes to `mb_verifier`. Inspect the actual
+> diff and checks; report findings without editing or publishing. Missing full
+> workflow artifacts are a limitation only where that workflow was required.
+
+For the complete discovery-to-delivery workflow:
+
+> Use the complete `product-delivery` workflow for this task. Read its installed
+> contract, begin Product Partner discovery, and follow its separate brief and
+> plan approval gates. Keep the approved artifacts available for role handoffs.
+
+These are task instructions, not an app profile selector. The CLI profile
+commands below configure a primary CLI session; do not assume they select the
+role of an existing desktop task. Custom agents are delegated specialists.
+Codex currently supports delegation explicitly requested by the user or by
+applicable project/skill instructions. Leave model and reasoning settings
+inherited unless the user chooses otherwise; bootstrap adapters pin neither.
+
+Confirm `mb_product_partner`, `mb_delivery_lead`, and `mb_verifier` are available
+in a fresh task after installation. If the harness cannot expose an installed
+role, report that limit and request a replacement reviewer or explicit waiver
+when review is required. A new user-owned task is not needed for each subagent.
+
+#### Claude Code and Codex CLI
+
 Launching Product Partner or Delivery Lead activates the complete workflow.
 Launching the Verifier activates only its independent verification portion for
 the supplied change.
@@ -280,6 +335,10 @@ profile because it is not a primary-session role.
 Start a new session after installation so the provider rediscovers the
 definitions.
 
+Claude retains its native `--agent` entry and `@AGENTS.md` shared-guidance
+adapter. Its lazy nested `CLAUDE.md` loading differs from Codex's startup guide
+chain; use the provider-specific checks in `docs/guidance-loading-smoke.md`.
+
 ### Updating a workflow
 
 Edit the canonical contract or template in `workflows/`, bump
@@ -308,6 +367,15 @@ not weaken exact user approval, scope-change escalation, or honest verification.
 
 ## Updating
 
+Shared skill content lives in `~/.agents/skills/`, which Codex discovers
+directly. Claude links live under `$CLAUDE_CONFIG_DIR/skills/` when set, or
+`~/.claude/skills/` otherwise. Checks for redundant Codex-specific copies use
+`$CODEX_HOME/skills/` when set, or `~/.codex/skills/` otherwise. Changing a
+provider configuration root does not relocate canonical shared skills. Relative
+override paths resolve from the command's working directory; empty overrides
+use the defaults, matching workflow installation. Inactive default provider
+directories and unrelated entries remain untouched.
+
 The installer adds only missing skills and rejects content that differs from
 `skills.json`. To update a skill, review the upstream change at its repository,
 then revise its exact `sourceRevision`, `sourcePath` when needed, expected
@@ -344,3 +412,12 @@ provider roots.
 
 Manual provider loading checks live in
 `docs/guidance-loading-smoke.md`. Static tests are not runtime loading evidence.
+
+Provider contracts checked against official documentation on 2026-09-07:
+[Codex instructions](https://developers.openai.com/codex/guides/agents-md),
+[Codex skills](https://developers.openai.com/codex/skills),
+[Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents),
+[Claude memory](https://code.claude.com/docs/en/memory), and
+[Claude configuration directories](https://code.claude.com/docs/en/claude-directory).
+These sources establish supported contracts, not successful loading on every
+installed provider version.

docs/engineering/git-workflow.md

@@ -35,6 +35,38 @@ Keep commits coherent and reviewable. Inspect the complete staged diff and run
 the relevant local checks before committing. Never bypass hooks unless the user
 explicitly authorizes the exception.
 
+## PR size
+
+Plan PR boundaries before a large implementation. Each PR should deliver one
+coherent behavior change and pass its checks independently. Keep related code,
+tests, and necessary documentation together; separate unrelated refactors.
+
+Count additions plus deletions in the proposed PR diff against its actual base
+using the merge base, not the sum of individual commits. For stacked PRs, use
+the declared parent branch. Include handwritten code, tests, and documentation.
+Report generated output, lockfiles, pure renames, and binary files separately
+with exact paths and reasons; exclude them from the numeric threshold but still
+review them. Count edits within renamed files. Unknown or mixed-content files
+remain counted; do not classify handwritten changes as generated to fit a limit.
+
+| Counted changed lines | Required action |
+| :--- | :--- |
+| Up to 500 | Normal target; keep the PR focused |
+| 501–1,000 | Explain in the PR body why keeping the change together improves review |
+| Over 1,000 | Split it, or obtain a documented exception from the fresh independent reviewer before calling it ready or merging |
+
+For an exception, record the counted size, excluded paths, why a safe split is
+not useful, how the change can be reviewed, and the reviewer's explicit
+acceptance for the reviewed head. The author cannot self-approve. A material
+scope change or changed head requires renewed review and exception confirmation.
+An exception does not waive tests, independent review, or publication authority.
+If independent review is user-waived, only the user can explicitly grant the
+size exception; the review waiver alone is insufficient.
+
+These are review-policy gates, not an automated CI size check. Start with the
+500/1,000 defaults; any project-specific adjustment belongs in its owning Git
+contract with rationale, rather than an ad hoc per-PR threshold change.
+
 ## Pull requests and review
 
 Use `.github/pull_request_template.md`. A PR title should match the intended
@@ -46,8 +78,10 @@ Before opening or updating a PR:
 1. Confirm worktree, branch, base, and exact changed paths.
 2. Run focused owner checks and affected consumer checks.
 3. Run `git diff --check` and inspect the complete diff.
-4. Complete implementer self-review and one fresh independent review unless the
-   user explicitly waives it for this change.
+4. Complete implementer self-review, then one fresh independent review by a
+   reviewer that did not make the change — the installed Verifier role unless
+   the user names another. Only the user may waive that review for a change.
+   `AGENTS.md` also requires this before local completion, including maintenance.
 5. Update affected guidance, engineering, and continuity owners.
 
 Before merge, confirm the PR head is the exact reviewed and verified commit.