code-foundry 1.36.4 → 1.37.0

package/.github/CONTRIBUTING.md

@@ -12,6 +12,10 @@ Quick links: [Code of Conduct](./CODE_OF_CONDUCT.md) · [Security Policy](./SECU
 
 [Agent contract](#agent-operating-contract) · [Branches](#branching-model) · [Setup](#before-you-start) · [Validation](#local-validation) · [Internal](#internal-contribution-workflow) · [External](#external-contribution-workflow) · [Pull requests](#pull-request-standards) · [Reviews](#review-and-merge-protocol) · [Security](#security-and-emergencies)
 
+<!-- /code-foundry-managed: config-aware-policy -->
+
+<!-- code-foundry-managed: agent-operating-contract -->
+
 ## Agent operating contract
 
 Agents must follow these rules before changing code:
@@ -32,6 +36,8 @@ 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: agent-operating-contract -->
+
 <!-- code-foundry-managed: pull-request-policy -->
 
 ### Pull request readiness (mandatory)
@@ -57,6 +63,8 @@ This repository uses the `direct` workflow. Topic pull requests target `main`.
 
 <!-- /code-foundry-managed: pull-request-policy -->
 
+<!-- code-foundry-managed: branching-model -->
+
 ## Branching model
 
 ```text
@@ -75,6 +83,10 @@ docs/*  test/*  refactor/*         │
 
 The Git workflow is `direct`: topic branches **squash** directly into `main`, and the Release Please version PR **squashes** into `main` (`release_merge_strategy: squash`). Release automation never defaults to a merge method and never merges with `--admin`; `code-foundry doctor` and `code-foundry sync` fail closed on any other release merge strategy. This repository has one protected integration and release branch: `main`.
 
+<!-- /code-foundry-managed: branching-model -->
+
+<!-- code-foundry-managed: before-you-start -->
+
 ## Before you start
 
 ### Toolchain
@@ -97,6 +109,10 @@ git switch -c feat/short-description
 
 If the worktree is dirty, stop and understand the existing changes before switching branches or editing overlapping files.
 
+<!-- /code-foundry-managed: before-you-start -->
+
+<!-- code-foundry-managed: local-validation -->
+
 ## Local validation
 
 The repository runtime detects supported tools and skips checks that do not apply:
@@ -112,6 +128,10 @@ Security and dependency audits run through the GitHub Security workflow.
 
 Run the checks relevant to the change. For a release or security-sensitive change, run the complete set. Record the commands and results in the pull request.
 
+<!-- /code-foundry-managed: local-validation -->
+
+<!-- code-foundry-managed: internal-contribution-workflow -->
+
 ## Internal contribution workflow
 
 For maintainers, trusted contributors, and automation agents:
@@ -134,6 +154,10 @@ For maintainers, trusted contributors, and automation agents:
 9. Address review feedback and failed checks on the same branch.
 10. Merge with a squash after required checks pass and the change is ready; feature PRs land on `main` with squash merges.
 
+<!-- /code-foundry-managed: internal-contribution-workflow -->
+
+<!-- code-foundry-managed: internal-agent-handoff -->
+
 ### Internal agent handoff
 
 Every agent handoff should state:
@@ -147,6 +171,10 @@ Risks: known limitations or follow-up work
 Branch/PR: branch name and pull request link
 ```
 
+<!-- /code-foundry-managed: internal-agent-handoff -->
+
+<!-- code-foundry-managed: external-contribution-workflow -->
+
 ## External contribution workflow
 
 For contributors who do not have direct write access:
@@ -163,6 +191,10 @@ For contributors who do not have direct write access:
 
 External contributors should never need repository secrets or production access to validate a normal change.
 
+<!-- /code-foundry-managed: external-contribution-workflow -->
+
+<!-- code-foundry-managed: pull-request-standards -->
+
 ## Pull request standards
 
 Every pull request should make these questions easy to answer:
@@ -176,6 +208,10 @@ Every pull request should make these questions easy to answer:
 
 Keep pull requests focused and reviewable. Include screenshots or recordings for user-facing changes. Link related issues and use `Closes #123` when appropriate. Complete the [pull request template](./PULL_REQUEST_TEMPLATE.md).
 
+<!-- /code-foundry-managed: pull-request-standards -->
+
+<!-- code-foundry-managed: workflow-and-check-behavior -->
+
 ## Workflow and check behavior
 
 | Event                                              | Expected automation                                                                   |
@@ -199,6 +235,10 @@ Use Conventional Commits so the release automation can determine the next versio
 
 Security checks can be skipped when repository visibility or the GitHub plan does not support a feature. A skipped optional check must not be configured as a required status check.
 
+<!-- /code-foundry-managed: workflow-and-check-behavior -->
+
+<!-- code-foundry-managed: review-and-merge-protocol -->
+
 ## Review and merge protocol
 
 | Change                    | Target | Merge method                      | Merge gate                              |
@@ -208,6 +248,10 @@ Security checks can be skipped when repository visibility or the GitHub plan doe
 
 Reviewers focus on correctness, security, maintainability, test coverage, operational impact, and compatibility. Authors remain responsible for responding to feedback and verifying the final commit.
 
+<!-- /code-foundry-managed: review-and-merge-protocol -->
+
+<!-- code-foundry-managed: security-and-emergencies -->
+
 ## Security and emergencies
 
 Report vulnerabilities privately using [SECURITY.md](./SECURITY.md), never in a public issue or pull request.
@@ -221,3 +265,5 @@ For an urgent production or security issue:
 5. Record follow-up work, remediation, and rollback information.
 
 CI bypasses are for documented infrastructure emergencies only and require a follow-up fix. Never use a bypass to hide a code or test failure.
+
+<!-- /code-foundry-managed: security-and-emergencies -->

package/.github/SECURITY.md

@@ -11,6 +11,10 @@ The latest commit on `main` receives security patches.
 | `main`           | ✅        |
 | Feature branches | ❌        |
 
+<!-- /code-foundry-managed: config-aware-policy -->
+
+<!-- code-foundry-managed: reporting-a-vulnerability -->
+
 ## Reporting a Vulnerability
 
 Do not open a public GitHub issue for a security vulnerability. Report it privately through the repository's Security tab, GitHub security advisory flow, or the private contact method listed on the repository page.
@@ -19,6 +23,12 @@ Include the affected version or commit, impact, reproduction steps, relevant log
 
 Maintainers will acknowledge receipt, provide an assessment timeline, coordinate a fix, and agree with the reporter on responsible disclosure. Public disclosure should occur only after a fix or mitigation is available.
 
+<!-- /code-foundry-managed: reporting-a-vulnerability -->
+
+<!-- code-foundry-managed: scope -->
+
 ## Scope
 
 This policy covers the code, configuration, dependencies, workflows, and generated artifacts maintained in this repository. Review `Security / Dependency Audit` results for supported ecosystems. Never commit credentials, tokens, private keys, or sensitive environment files. Report accidental secret exposure privately and rotate the credential immediately.
+
+<!-- /code-foundry-managed: scope -->

package/AGENTS.md

@@ -6,6 +6,10 @@ These instructions are the repository-level operating contract for coding agents
 
 They complement `CONTRIBUTING.md`. More specific instructions in nested `AGENTS.md` files and project documentation take precedence for their directory.
 
+<!-- /code-foundry-managed: config-aware-policy -->
+
+<!-- code-foundry-managed: mission -->
+
 ## Mission
 
 - Keep formatting, linting, type checking, builds, tests, and coverage reproducible locally and in CI.
@@ -17,6 +21,10 @@ They complement `CONTRIBUTING.md`. More specific instructions in nested `AGENTS.
 
 This repository may contain TypeScript, Rust, Python, or any combination of them. Detect the active stack from the files present; do not assume every check applies.
 
+<!-- /code-foundry-managed: mission -->
+
+<!-- code-foundry-managed: contributing-back -->
+
 ## Contributing back
 
 Consumers are encouraged to help improve this open-source project. Open a small,
@@ -26,6 +34,10 @@ changes, create an issue first so the proposal can be discussed and scoped.
 Contributions should help make the tool as performant, reliable, and helpful as
 possible for everyone.
 
+<!-- /code-foundry-managed: contributing-back -->
+
+<!-- code-foundry-managed: read-before-acting -->
+
 ## Read before acting
 
 Before editing:
@@ -45,6 +57,10 @@ Before editing:
 
 If the worktree is dirty, preserve existing changes and avoid overlapping edits until their ownership is clear.
 
+<!-- /code-foundry-managed: read-before-acting -->
+
+<!-- code-foundry-managed: priorities -->
+
 ## Priorities
 
 When instructions conflict, use this order:
@@ -57,6 +73,10 @@ When instructions conflict, use this order:
 
 Ask for clarification when a missing decision would materially change the implementation. Otherwise make the smallest reasonable assumption and document it.
 
+<!-- /code-foundry-managed: priorities -->
+
+<!-- code-foundry-managed: safety-boundaries -->
+
 ## Safety boundaries
 
 - Do not discard, reset, overwrite, or rewrite user-owned changes.
@@ -68,6 +88,10 @@ Ask for clarification when a missing decision would materially change the implem
 - Do not claim completion while required validation, review, deployment, or user decisions remain pending.
 - Publishing, committing, or opening a pull request requires explicit task scope or user authorization.
 
+<!-- /code-foundry-managed: safety-boundaries -->
+
+<!-- code-foundry-managed: standard-workflow -->
+
 ## Standard workflow
 
 1. Restate the desired outcome and identify the files or systems in scope.
@@ -82,6 +106,10 @@ Ask for clarification when a missing decision would materially change the implem
 
 For normal feature work, branch from `main` and target pull requests at `main`. Treat `main` as the protected release branch. Follow `.github/CONTRIBUTING.md` for the complete internal and external contribution flow.
 
+<!-- /code-foundry-managed: standard-workflow -->
+
+<!-- code-foundry-managed: git-workflow-and-merging -->
+
 ## Git workflow and merging
 
 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`.
@@ -103,6 +131,8 @@ them:
 - Keep pull requests focused; merge with the canonical method only after
   required checks pass.
 
+<!-- /code-foundry-managed: git-workflow-and-merging -->
+
 <!-- code-foundry-managed: pull-request-policy -->
 
 ## Code Foundry workflow policy (mandatory)
@@ -130,6 +160,8 @@ This repository uses the `direct` workflow. Topic pull requests target `main`.
 
 <!-- /code-foundry-managed: pull-request-policy -->
 
+<!-- code-foundry-managed: toolchain-and-dependencies -->
+
 ## Toolchain and dependencies
 
 - Follow `toolchain: auto` in `.github/code-foundry.yml`; use native tools by
@@ -145,6 +177,10 @@ This repository uses the `direct` workflow. Topic pull requests target `main`.
 - Do not mix package managers or regenerate lockfiles as a side effect.
 - Keep dependency additions narrowly scoped and explain security, licensing, and runtime impact.
 
+<!-- /code-foundry-managed: toolchain-and-dependencies -->
+
+<!-- code-foundry-managed: validation -->
+
 ## Validation
 
 Use the shared scripts when present. They detect supported tools and skip inapplicable checks:
@@ -175,6 +211,10 @@ At minimum:
 
 If a check cannot run, state the exact reason. A skipped check is not a passing check.
 
+<!-- /code-foundry-managed: validation -->
+
+<!-- code-foundry-managed: tests-and-coverage -->
+
 ## Tests and coverage
 
 - Add or update tests for behavior changes and regressions.
@@ -183,6 +223,10 @@ If a check cannot run, state the exact reason. A skipped check is not a passing
 - Keep test data deterministic and remove secrets from logs and fixtures.
 - Use the narrowest test command while iterating, then run the affected package or workspace suite.
 
+<!-- /code-foundry-managed: tests-and-coverage -->
+
+<!-- code-foundry-managed: github-workflows-and-configuration -->
+
 ## GitHub workflows and configuration
 
 - Keep workflows concise, independently runnable, and safe to re-run.
@@ -196,6 +240,10 @@ If a check cannot run, state the exact reason. A skipped check is not a passing
 - 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.
 
+<!-- /code-foundry-managed: github-workflows-and-configuration -->
+
+<!-- code-foundry-managed: documentation-and-generated-files -->
+
 ## Documentation and generated files
 
 - Update documentation when behavior, setup, configuration, commands, or operational procedures change.
@@ -203,6 +251,10 @@ If a check cannot run, state the exact reason. A skipped check is not a passing
 - Do not commit build output, caches, coverage output, dependency directories, generated credentials, or temporary files.
 - Preserve formatting and line-ending conventions from `.editorconfig` and `.gitattributes`.
 
+<!-- /code-foundry-managed: documentation-and-generated-files -->
+
+<!-- code-foundry-managed: completion-report -->
+
 ## Completion report
 
 End every agent task with:
@@ -217,3 +269,5 @@ Branch/PR:
 ```
 
 Use exact command names and outcomes. Mention external changes separately from local changes, and distinguish completed work from recommendations.
+
+<!-- /code-foundry-managed: completion-report -->

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.37.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.36.4...v1.37.0) (2026-09-30)
+
+
+### Features
+
+* preserve repository-owned sections of managed policy documents ([#668](https://github.com/0xPlayerOne/code-foundry/issues/668)) ([26e9f4b](https://github.com/0xPlayerOne/code-foundry/commit/26e9f4bfeaca8b01087626bafbfc5090d891530f)), closes [#667](https://github.com/0xPlayerOne/code-foundry/issues/667)
+
 ## [1.36.4](https://github.com/0xPlayerOne/code-foundry/compare/v1.36.3...v1.36.4) (2026-09-29)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.36.4",
+  "version": "1.37.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/sync.mjs

@@ -299,15 +299,21 @@ function synchronize(options) {
     }
     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)
-          }
+      if (isLegacyManagedDoc(file, existing)) {
+        // Ancient scaffolds predate managed blocks entirely; fall through to
+        // the full overwrite so they migrate to the marked layout.
+      } else if (configAwarePolicyFiles.has(file)) {
+        // Refresh managed blocks in place and keep every unmarked line. A
+        // whole-file overwrite here would silently delete repository-owned
+        // sections of the policy documents (issue #667).
+        const merged = refreshManagedPolicyDocument(existing, content.toString('utf8'))
+        if (merged !== existing) {
+          changed.push(file)
+          writeOrReport(destination, merged, dryRun)
         }
         continue
+      } else {
+        continue
       }
     }
     if (!existsSync(destination) || !buffersEqual(content, readFileSync(destination))) {
@@ -1375,91 +1381,103 @@ function isLegacyManagedDoc(file, content) {
   return false
 }
 
+const MANAGED_BLOCK_PATTERN =
+  /<!-- code-foundry-managed: ([A-Za-z0-9_-]+) -->[\s\S]*?<!-- \/code-foundry-managed: \1 -->/g
+const MANAGED_MARKER_LINE = /^[ \t]*<!-- \/?code-foundry-managed: [A-Za-z0-9_-]+ -->[ \t]*\r?\n/gm
+
+/** @param {string} id */
+function managedBlockPattern(id) {
+  const start = `<!-- code-foundry-managed: ${id} -->`
+  const end = `<!-- /code-foundry-managed: ${id} -->`
+  return new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`, 'g')
+}
+
 /**
- * Config-aware policy documents are generated contracts: a normal sync must
- * 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
+ * Remove managed marker lines that do not belong to a complete block. The
+ * pre-block templates carried a single unclosed `config-aware-policy` marker
+ * as an ownership flag; that residue (and any hand-mangled leftover marker)
+ * is migration noise, not content, and would otherwise break block matching.
+ * Markers inside complete blocks are kept.
  * @param {string} content
+ * @returns {string}
  */
-function isManagedConfigPolicy(file, content) {
-  if (!configAwarePolicyFiles.has(file)) return false
-  if (content.includes('<!-- code-foundry-managed: config-aware-policy -->')) return true
-  if (file === 'AGENTS.md') {
-    return (
-      content.startsWith('# Agent Instructions\n') &&
-      content.includes(
-        'These instructions are the repository-level operating contract for coding agents'
-      ) &&
-      content.includes('They complement `CONTRIBUTING.md`.')
-    )
-  }
-  if (file === '.github/CONTRIBUTING.md') {
-    return (
-      content.startsWith('# Contributing\n') &&
-      content.includes(
-        'This guide is the operating contract for humans and automation contributing to this repository.'
-      ) &&
-      content.includes('[Agent contract](#agent-operating-contract)')
-    )
-  }
-  return (
-    content.startsWith('# Security Policy\n') &&
-    content.includes('## Reporting a Vulnerability') &&
-    content.includes(
-      'This policy covers the code, configuration, dependencies, workflows, and generated artifacts maintained in this repository.'
-    )
-  )
-}
-
-/** @param {string} target @param {string[]} args */
-function git(target, args) {
-  spawnSync('git', args, { cwd: target, stdio: 'ignore' })
+function stripUnpairedManagedMarkers(content) {
+  const spans = [...content.matchAll(MANAGED_BLOCK_PATTERN)].map((match) => [
+    match.index,
+    match.index + match[0].length,
+  ])
+  if (!spans.length) return content.replace(MANAGED_MARKER_LINE, '')
+  let out = ''
+  let cursor = 0
+  for (const match of content.matchAll(MANAGED_MARKER_LINE)) {
+    const index = match.index
+    if (spans.some(([from, to]) => index >= from && index < to)) continue
+    out += content.slice(cursor, index)
+    cursor = index + match[0].length
+  }
+  return out + content.slice(cursor)
 }
 
 /**
- * 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.
+ * Refresh the managed policy blocks in a policy document against a rendered
+ * baseline while preserving every unmarked line (issue #667). Blocks the
+ * document already carries are replaced with the baseline content in place,
+ * so config-driven prose (branch topology, validation tiers) always follows
+ * the repository configuration. Missing blocks migrate in place when their
+ * baseline content is present verbatim — documents rendered by the pre-block
+ * templates carried the same prose unmarked — and are appended at the end
+ * otherwise, so hand-edited generated regions and consumer-owned sections
+ * are never silently deleted.
  * @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)]
+function refreshManagedPolicyDocument(existing, baseline) {
+  const blocks = [...baseline.matchAll(MANAGED_BLOCK_PATTERN)]
   if (!blocks.length) return existing
 
   let merged = existing
+  /** @type {Set<string>} */
+  const present = new Set()
   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) ?? []
+    const occurrences = [...merged.matchAll(managedBlockPattern(id))]
     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
+      merged = merged.replace(managedBlockPattern(id), () => match[0])
+      present.add(id)
     }
-    if (merged.includes(start) || merged.includes(end)) {
-      throw new Error(`Managed policy block is incomplete in consumer document: ${id}`)
+  }
+
+  merged = stripUnpairedManagedMarkers(merged)
+
+  for (const match of blocks) {
+    if (present.has(match[1])) continue
+    const start = `<!-- code-foundry-managed: ${match[1]} -->`
+    const end = `<!-- /code-foundry-managed: ${match[1]} -->`
+    const inner = match[0]
+      .slice(start.length, match[0].length - end.length)
+      .replace(/^\n+/, '')
+      .replace(/\n+$/, '')
+    if (inner && merged.includes(inner)) {
+      // Wrap the legacy unmarked region in place; the replacer function keeps
+      // `$` sequences in the prose from being treated as substitution patterns.
+      merged = merged.replace(inner, () => match[0])
+      continue
     }
     const separator = merged.endsWith('\n\n') ? '' : merged.endsWith('\n') ? '\n' : '\n\n'
-    merged = `${merged}${separator}${block}\n`
+    merged = `${merged}${separator}${match[0]}\n`
   }
   return merged
 }
 
+/** @param {string} target @param {string[]} args */
+function git(target, args) {
+  spawnSync('git', args, { cwd: target, stdio: 'ignore' })
+}
+
 /** @param {string} file @param {Buffer|string} content @param {boolean} dryRun */
 function writeOrReport(file, content, dryRun) {
   if (dryRun) {