code-foundry 1.9.13 → 1.10.0

package/.github/CONTRIBUTING.md

@@ -32,6 +32,27 @@ Agents must not:
 - Change branch protections, secrets, deployments, or external systems unless that action is explicitly in scope.
 - Claim completion when tests, deployment checks, or required reviews are still pending.
 
+<!-- code-foundry-managed: pull-request-policy -->
+
+### Pull request readiness (mandatory)
+
+This repository uses the `direct` workflow. Topic pull requests target `main`.
+
+- Open every ordinary pull request as a draft. Use `gh pr create --draft` or
+  set `draft: true` in the GitHub API; never create a ready ordinary pull
+  request as a shortcut.
+- Keep ordinary pull requests in draft while making commits. The generated
+  Draft Guard resets a ready ordinary pull request to draft on creation,
+  reopening, or a new commit, and runner-heavy validation starts only after an
+  explicit `ready_for_review` transition.
+- Run local validation and finish review preparation before marking an ordinary
+  pull request ready. After any later commit, mark it ready again only after
+  the current head is ready for review.
+- Release Please version pull requests are managed by the Code Foundry release
+  workflow; do not manually change their draft state unless the workflow asks.
+
+<!-- /code-foundry-managed: pull-request-policy -->
+
 ## Branching model
 
 ```text
@@ -162,7 +183,7 @@ Keep pull requests focused and reviewable. Include screenshots or recordings for
 | Push to a working branch                           | Draft PR workflow                                                                     |
 | Push to `main`                                     | Release workflow; canonical validation already ran on the merged PR                   |
 
-Draft pull requests do not start validation. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head. Converting it to draft runs only the lightweight cancellation control.
+Draft pull requests do not start validation. The lightweight Draft Guard also converts ordinary pull requests opened, reopened, or updated while ready back to draft; it never checks out pull-request code and it excludes Release Please version heads, whose release workflow owns their state. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head. Converting it to draft runs only the lightweight cancellation control.
 
 Pull-request validation keys concurrency by event and pull-request head, so a newer update cancels its superseded run. Scheduled and manual audits use a separate caller pinned to the protected default branch; this prevents caller-selected runtime code from executing with default-branch cache access. Both callers use the mode-aware orchestrator, which fans out only the required jobs and concludes with the stable aggregate gate.
 

package/.github/workflows/draft-enforcement_self-ci.yml

@@ -0,0 +1,79 @@
+name: Code Foundry Draft Guard
+
+on:
+  # This workflow runs from the trusted base branch and only reads pull-request
+  # metadata before changing draft state. It never checks out or executes PR code.
+  pull_request_target:
+    branches: [main, staging]
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+permissions:
+  pull-requests: write
+
+concurrency:
+  group: code-foundry-draft-guard-${{ github.repository }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  enforce:
+    name: Draft Guard / Enforce
+    if: vars.CI_BILLING_PAUSED != 'true'
+    runs-on: ubuntu-slim
+    timeout-minutes: 5
+    steps:
+      - name: Keep ordinary pull requests in draft
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          EVENT_UPDATED_AT: ${{ github.event.pull_request.updated_at }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          if [ -z "$EVENT_HEAD_SHA" ] || [ -z "$EVENT_UPDATED_AT" ] || [ -z "$PR_NUMBER" ]; then
+            echo '::error title=Draft guard cannot verify event freshness::The pull-request event did not include the required immutable metadata.'
+            exit 1
+          fi
+
+          read -r draft head_ref head_sha updated_at < <(
+            gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" \
+              --jq '[.draft, .head.ref, .head.sha, .updated_at] | @tsv'
+          )
+          if [ -z "$draft" ] || [ -z "$head_ref" ] || [ -z "$head_sha" ] || [ -z "$updated_at" ]; then
+            echo '::error title=Draft guard cannot verify current state::The GitHub API response did not include the required pull-request metadata.'
+            exit 1
+          fi
+
+          # Release Please owns the state of generated version PRs. Its release
+          # workflow deliberately resets and readies these PRs before merging.
+          case "$head_ref" in
+            release-please--branches--main|release-please--branches--main--*)
+              echo "Release Please head $head_ref is managed by the release workflow; leaving its draft state unchanged."
+              exit 0
+              ;;
+          esac
+
+          # A newer state transition or commit superseded this event. Do not
+          # undo a user's later explicit readiness decision with a stale event.
+          if [ "$head_sha" != "$EVENT_HEAD_SHA" ] || [ "$updated_at" != "$EVENT_UPDATED_AT" ]; then
+            echo 'A newer pull-request state or head commit superseded this draft-guard event; leaving the current state unchanged.'
+            exit 0
+          fi
+
+          if [ "$draft" = true ]; then
+            echo "Pull request #$PR_NUMBER is already a draft; no validation state change is needed."
+            exit 0
+          fi
+          if [ "$draft" != false ]; then
+            echo "::error title=Draft guard cannot verify current state::Unexpected draft value: $draft"
+            exit 1
+          fi
+
+          gh api \
+            --method PATCH \
+            "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" \
+            -F draft=true \
+            --silent >/dev/null
+          echo "Converted ordinary pull request #$PR_NUMBER to draft; runner-heavy validation waits for ready_for_review."

package/.oxfmtrc.json

@@ -3,5 +3,5 @@
   "singleQuote": true,
   "trailingComma": "es5",
   "printWidth": 100,
-  "ignorePatterns": ["CHANGELOG.md", ".github/.code-foundry", ".github/actions/"]
+  "ignorePatterns": ["CHANGELOG.md", ".github/.code-foundry", ".github/actions/", "plugin.json"]
 }

package/AGENTS.md

@@ -94,6 +94,29 @@ them:
 - Keep pull requests focused; merge with the canonical method only after
   required checks pass.
 
+<!-- code-foundry-managed: pull-request-policy -->
+
+## Code Foundry workflow policy (mandatory)
+
+This repository uses the `direct` workflow. Topic pull requests target `main`.
+
+- Open every ordinary pull request as a draft. Use `gh pr create --draft` or
+  set `draft: true` in the GitHub API; never create a ready ordinary pull
+  request as a shortcut.
+- Keep ordinary pull requests in draft while making commits. The generated
+  Draft Guard resets a ready ordinary pull request to draft on creation,
+  reopening, or a new commit, and runner-heavy validation starts only after an
+  explicit `ready_for_review` transition.
+- Run local validation and finish review preparation before marking an ordinary
+  pull request ready. After any later commit, mark it ready again only after
+  the current head is ready for review.
+- This contract is mandatory for every agent scope. Nested `AGENTS.md` files
+  may add stricter rules but must not weaken or replace it.
+- Release Please version pull requests are managed by the Code Foundry release
+  workflow; do not manually change their draft state unless the workflow asks.
+
+<!-- /code-foundry-managed: pull-request-policy -->
+
 ## Toolchain and dependencies
 
 - Follow `toolchain: auto` in `.github/code-foundry.yml`; use native tools by
@@ -154,7 +177,7 @@ If a check cannot run, state the exact reason. A skipped check is not a passing
 - Use per-workflow concurrency groups that cancel superseded runs while allowing independent workflows to run in parallel.
 - Keep setup language-aware and cache dependency downloads by lockfile; do not cache secrets, `node_modules`, virtual environments, or broad build output without a measured reason.
 - Use least-privilege permissions and pin action versions consistently with the template.
-- Keep CI, Test, Security, CodeQL, Draft PR, Release PR, and Release concerns separated.
+- Keep CI, Test, Security, CodeQL, Draft Guard, Draft PR, Release PR, and Release concerns separated.
 - Security and CodeQL may skip when repository visibility or GitHub plan support does not permit them. Do not make an unavailable check required.
 - Optional Turborepo Remote Caching uses `TURBO_TOKEN` and `TURBO_TEAM`; do not add Vercel deployment behavior just to enable caching.
 - Update branch protection when adding or renaming required job checks; verify the actual GitHub status context.

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.10.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.9.13...v1.10.0) (2026-09-08)
+
+
+### Features
+
+* **ci:** enforce draft pull request readiness ([#530](https://github.com/0xPlayerOne/code-foundry/issues/530)) ([fe62147](https://github.com/0xPlayerOne/code-foundry/commit/fe621477a46b49dee69a4c74c482e815a3e60b8d))
+
 ## [1.9.13](https://github.com/0xPlayerOne/code-foundry/compare/v1.9.12...v1.9.13) (2026-09-08)
 
 

package/README.md

@@ -36,7 +36,7 @@ contract. For normal updates, edit that file and run `npx code-foundry sync`.
 ## What it installs
 
 - Short workflow callers for pull-request validation, protected scheduled/manual
-  audits, Draft PR, Release PR, and Release.
+  audits, Draft Guard, Draft PR, Release PR, and Release.
 - A deterministic performance lane with ordered command support, stable result
   artifacts, and an optional shared Node package budget profile.
 - A small `.githooks/pre-commit` launcher with language-aware formatting and
@@ -75,9 +75,12 @@ The standard workflow triggers are:
 - Draft PR automation for supported feature/fix branches.
 
 Automated feature/fix and staging-promotion pull requests open as drafts.
-Pull-request validation runs on the ready-for-review transition. After later
-commits, convert the PR to draft and mark it ready again so checks attach to
-the current head. Converting a PR to draft runs only the lightweight
+The trusted Draft Guard is a fallback for manually created or reopened ready
+PRs and for new commits to ordinary ready PRs: it converts them to drafts
+without checking out PR code. It verifies the event head and update timestamp
+before changing state, and excludes Release Please version PRs whose release
+workflow owns readiness. Pull-request validation runs only on the
+ready-for-review transition. Converting a PR to draft runs only the lightweight
 cancellation control. Scheduled and manually dispatched audits are unaffected.
 
 Jobs are language-aware and skip irrelevant setup inside the applicable

package/docs/INITIALIZATION.md

@@ -38,7 +38,16 @@ runtime, then run sync.
 
 Sync updates standard Code Foundry files only. It preserves application code,
 authored documentation, existing `.mise.toml` selections, and custom workflows
-such as deployment, search, Slither, or monitoring workflows.
+such as deployment, search, Slither, or monitoring workflows. A missing
+`AGENTS.md` receives the baseline agent contract. If another initializer has
+created an unmarked `AGENTS.md` or `.github/CONTRIBUTING.md`, sync preserves its
+surrounding text and adds or refreshes only the marked Code Foundry policy block;
+this lets later syncs restore mandatory pull-request rules without replacing
+agent-specific instructions. Marked generated policy documents continue to
+receive topology-aware baseline updates, and missing configuration keys are
+added without changing existing values. The Oxfmt baseline also ignores
+`plugin.json`, whose serialization is owned by Release Please; plugin manifest
+semantics remain covered by repository tests rather than a formatter rewrite.
 
 The environment bootstrap enables repository hooks and uses mise only when an
 existing `.mise.toml` is present or `toolchain: mise` is selected. Otherwise it

package/docs/WORKFLOWS.md

@@ -14,10 +14,15 @@ pull_request:
 
 The generated validation caller listens only for `ready_for_review`, so draft
 pull requests register no validation checks and allocate no validation runner.
-After any later update, convert the pull request to draft and mark it ready
-again so required checks attach to the current head. A separate lightweight
-draft-control caller listens for `converted_to_draft` and cancels queued or
-running pull-request workflows without creating skipped validation jobs.
+A separate lightweight Draft Guard runs from the trusted base branch on
+`opened`, `reopened`, and `synchronize`; it converts ordinary ready pull
+requests back to draft without checking out pull-request code. It rechecks the
+current head and update timestamp before mutating state, so a stale event
+cannot undo a later draft or ready transition. Release Please version heads are
+excluded because the release workflow owns their state. A separate draft-control
+caller listens for `converted_to_draft` and cancels queued or running
+pull-request workflows without creating skipped validation jobs. Marking a pull
+request ready again starts validation for the current head.
 
 The separate `validation-audit.yml` caller is pinned to the configured released
 runtime and handles scheduled and manual audits:
@@ -91,15 +96,16 @@ opt in or out without a code change.
 
 ## Standard workflow responsibilities
 
-| Workflow   | Responsibility                                                    |
-| ---------- | ----------------------------------------------------------------- |
-| CI         | Format, lint, type-check, and build                               |
-| Test       | Unit, standardized performance, integration, E2E, and smoke tests |
-| Security   | Profile, audits, and public-only Dependency Review                |
-| CodeQL     | GitHub-native code scanning, kept separate from CI                |
-| Draft PR   | Create/update development pull requests                           |
-| Release PR | Promote `staging` into `main` (staging-release topology only)     |
-| Release    | Release Please, GitHub release, and optional npm publication      |
+| Workflow    | Responsibility                                                    |
+| ----------- | ----------------------------------------------------------------- |
+| CI          | Format, lint, type-check, and build                               |
+| Test        | Unit, standardized performance, integration, E2E, and smoke tests |
+| Security    | Profile, audits, and public-only Dependency Review                |
+| CodeQL      | GitHub-native code scanning, kept separate from CI                |
+| Draft PR    | Create/update development pull requests                           |
+| Draft Guard | Keep ordinary PRs draft until `ready_for_review`                  |
+| Release PR  | Promote `staging` into `main` (staging-release topology only)     |
+| Release     | Release Please, GitHub release, and optional npm publication      |
 
 Use concise job names such as `CI / Format`, `Test / Unit`, and
 `CodeQL / Analyze (Python)`. Per-language CodeQL analyzers (Rust shards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.9.13",
+  "version": "1.10.0",
   "description": "A fast, language-aware repository factory for agent-ready workflows, testing, security, and release automation.",
   "homepage": "https://github.com/0xPlayerOne/code-foundry#readme",
   "bugs": {

package/src/commands/doctor.mjs

@@ -150,9 +150,19 @@ export function doctor(root, options = {}) {
   const validationEnabled =
     includesValue(features, 'validation') ||
     ['ci', 'test', 'security', 'codeql'].some((legacy) => includesValue(features, legacy))
-  for (const name of ['validation', 'draft-control', 'draft-pr', 'release-pr', 'release']) {
+  for (const name of [
+    'validation',
+    'draft-control',
+    'draft-enforcement',
+    'draft-pr',
+    'release-pr',
+    'release',
+  ]) {
     if (name === 'release-pr' && workflow !== 'staging-release') continue
-    const enabled = name === 'draft-control' ? validationEnabled : includesValue(features, name)
+    const enabled =
+      name === 'draft-control' || name === 'draft-enforcement'
+        ? validationEnabled
+        : includesValue(features, name)
     const candidates = [
       join(target, `.github/workflows/${name}.yml`),
       join(target, `.github/workflows/${name}_self-ci.yml`),

package/src/commands/release.mjs

@@ -371,6 +371,7 @@ function deliverReconciliationPullRequest(target, base, head, state, targetSha,
     title,
     '--body',
     body,
+    '--draft',
   ])
   if (created.status !== 0) {
     // A concurrent run may have created the pull request between our list

package/src/commands/sync.mjs

@@ -44,6 +44,7 @@ const standardFiles = [
   '.github/workflows/validation.yml',
   '.github/workflows/validation-audit.yml',
   '.github/workflows/draft-control.yml',
+  '.github/workflows/draft-enforcement.yml',
   '.github/workflows/draft-pr.yml',
   '.github/workflows/release-pr.yml',
   '.github/workflows/release.yml',
@@ -221,10 +222,6 @@ export function syncRepository(options) {
     const sourceFile = sourcePath(source, file)
     if (!existsSync(sourceFile)) throw new Error(`Template file missing: ${file}`)
     const destination = join(target, file)
-    if (!force && protectedFiles.has(file) && existsSync(destination)) {
-      const existing = readFileSync(destination, 'utf8')
-      if (!isLegacyManagedDoc(file, existing) && !isManagedConfigPolicy(file, existing)) continue
-    }
     if (
       (file === 'LICENSE' || file === 'NOTICE') &&
       license === 'preserve' &&
@@ -267,6 +264,19 @@ export function syncRepository(options) {
         mergeIgnorePatternsConfig(content.toString('utf8'), readFileSync(destination, 'utf8'))
       )
     }
+    if (!force && protectedFiles.has(file) && existsSync(destination)) {
+      const existing = readFileSync(destination, 'utf8')
+      if (!isLegacyManagedDoc(file, existing) && !isManagedConfigPolicy(file, existing)) {
+        if (configAwarePolicyFiles.has(file)) {
+          const merged = mergeManagedPolicyBlocks(existing, content.toString('utf8'))
+          if (merged !== existing) {
+            changed.push(file)
+            writeOrReport(destination, merged, dryRun)
+          }
+        }
+        continue
+      }
+    }
     if (!existsSync(destination) || !buffersEqual(content, readFileSync(destination))) {
       changed.push(file)
       writeOrReport(destination, content, dryRun)
@@ -478,7 +488,12 @@ function shouldInclude(file, languages, features, config) {
   // the configuration or the variable enables it and the API key exists.
   if (file === '.github/workflows/opencode-security.yml') return true
   const workflow = file.match(/^\.github\/workflows\/([^/]+)\.yml$/)?.[1]
-  if (workflow === 'draft-control') return true
+  if (workflow === 'draft-control' || workflow === 'draft-enforcement') {
+    return (
+      includesValue(features, 'validation') ||
+      LEGACY_GENERATED_CALLERS.some((legacy) => includesValue(features, legacy))
+    )
+  }
   // The staging promotion caller only exists in the staging-release topology;
   // direct repositories open feature branches into main and need no promotion.
   if (workflow === 'release-pr' && !isStagingRelease(config.git_workflow)) return false
@@ -719,8 +734,16 @@ const DIRECT_DOC_REPLACEMENTS = {
       'This repository uses the `staging-release` workflow: topic branches **squash** into `staging`, a promotion PR **rebases** validated changes into `main` (`merge_strategy: rebase`), and the Release Please version PR **rebases** into `main` (`release_merge_strategy: rebase`). Feature PRs land on `staging` with squash merges; promotion and release PRs land on `main` with rebase merges. Re-align `staging` with `main` after a release when needed.',
       'This repository uses the `direct` workflow: topic branches **squash** directly into `main`, and the Release Please version PR **squashes** into `main` (`release_merge_strategy: squash`). Feature and release PRs land on `main` with squash merges. No integration branch exists; all pull requests target `main`.',
     ],
+    [
+      'This repository uses the `staging-release` workflow. Topic pull requests target `staging`; promotion pull requests target `main`.',
+      'This repository uses the `direct` workflow. Topic pull requests target `main`.',
+    ],
   ],
   '.github/CONTRIBUTING.md': [
+    [
+      'This repository uses the `staging-release` workflow. Topic pull requests target `staging`; promotion pull requests target `main`.',
+      'This repository uses the `direct` workflow. Topic pull requests target `main`.',
+    ],
     [
       '4. Branch from `staging` and target pull requests at `staging`; do not work directly on `main`.',
       '4. Branch from `main` and target pull requests at `main`; do not push directly to `main`.',
@@ -764,8 +787,8 @@ const DIRECT_DOC_REPLACEMENTS = {
       '| Change                    | Target | Merge method                      | Merge gate                              |\n| ------------------------- | ------ | --------------------------------- | --------------------------------------- |\n| Working branch            | `main` | Squash                            | All applicable required checks pass     |\n| Release Please version PR | `main` | Squash (`release_merge_strategy`) | Validation gate and release policy pass |\n',
     ],
     [
-      'Draft pull requests do not start runner-heavy validation. Marking a pull request ready for review starts the applicable validation tier; converting it back to draft cancels in-flight validation, and no replacement starts until it is ready again.',
-      'Draft pull requests do not start validation. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head. Converting it to draft runs only the lightweight cancellation control.',
+      'Draft pull requests do not start runner-heavy validation. The lightweight Draft Guard also converts ordinary pull requests opened, reopened, or updated while ready back to draft; it never checks out pull-request code and it excludes Release Please version heads, whose release workflow owns their state. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head; converting it back to draft cancels in-flight validation, and no replacement starts until it is ready again.',
+      'Draft pull requests do not start validation. The lightweight Draft Guard also converts ordinary pull requests opened, reopened, or updated while ready back to draft; it never checks out pull-request code and it excludes Release Please version heads, whose release workflow owns their state. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head. Converting it to draft runs only the lightweight cancellation control.',
     ],
     ['1. Create a focused branch from `staging`.', '1. Create a focused branch from `main`.'],
   ],
@@ -1116,9 +1139,12 @@ function isLegacyManagedDoc(file, content) {
 
 /**
  * Config-aware policy documents are generated contracts: a normal sync must
- * refresh them after branch-topology or validation-policy edits. The marker
- * owns future copies. Exact scaffold signatures migrate older generated
- * copies without treating arbitrary repository documentation as managed.
+ * refresh generated copies after branch-topology or validation-policy edits.
+ * Unmarked consumer-owned documents receive only the explicitly marked policy
+ * blocks, so another agent's initializer cannot be overwritten. The top-level
+ * marker owns generated copies. Exact scaffold signatures migrate older
+ * generated copies without treating arbitrary repository documentation as
+ * managed.
  * @param {string} file
  * @param {string} content
  */
@@ -1157,6 +1183,45 @@ function git(target, args) {
   spawnSync('git', args, { cwd: target, stdio: 'ignore' })
 }
 
+/**
+ * Merge the marked policy blocks from a rendered baseline into a consumer-owned
+ * policy document. Unmarked AGENTS.md/CONTRIBUTING.md files are commonly
+ * generated by another agent initializer, so sync must add and refresh the
+ * Code Foundry contract without replacing the user's surrounding instructions.
+ * @param {string} existing
+ * @param {string} baseline
+ * @returns {string}
+ */
+function mergeManagedPolicyBlocks(existing, baseline) {
+  const blockPattern =
+    /<!-- code-foundry-managed: ([A-Za-z0-9_-]+) -->[\s\S]*?<!-- \/code-foundry-managed: \1 -->/g
+  const blocks = [...baseline.matchAll(blockPattern)]
+  if (!blocks.length) return existing
+
+  let merged = existing
+  for (const match of blocks) {
+    const id = match[1]
+    const block = match[0]
+    const start = `<!-- code-foundry-managed: ${id} -->`
+    const end = `<!-- /code-foundry-managed: ${id} -->`
+    const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`, 'g')
+    const occurrences = merged.match(pattern) ?? []
+    if (occurrences.length > 1) {
+      throw new Error(`Managed policy block appears more than once in consumer document: ${id}`)
+    }
+    if (occurrences.length === 1) {
+      merged = merged.replace(pattern, block)
+      continue
+    }
+    if (merged.includes(start) || merged.includes(end)) {
+      throw new Error(`Managed policy block is incomplete in consumer document: ${id}`)
+    }
+    const separator = merged.endsWith('\n\n') ? '' : merged.endsWith('\n') ? '\n' : '\n\n'
+    merged = `${merged}${separator}${block}\n`
+  }
+  return merged
+}
+
 /** @param {string} file @param {Buffer|string} content @param {boolean} dryRun */
 function writeOrReport(file, content, dryRun) {
   if (dryRun) {