agent-project-sdlc 0.1.15 → 0.1.16

package/README.md

@@ -22,8 +22,8 @@ npx sdlc-harness init --adopt
 | Project initialization | `npx sdlc-harness init` | Creates `AGENTS.md`, `<harnessRoot>/state/**`, workflow skills, managed templates/policies, `.docs/**` and a Makefile include. |
 | Existing project adoption | `npx sdlc-harness init --adopt` | Adds Harness non-destructively to an existing repository. |
 | Configurable Harness root | `--harness-folder`, `package.json#sdlcHarness.harnessFolderName`, `sdlc-harness.config.json` | Supports Codex `.codex`, Claude `.claude`, Cursor `.cursor`, Cline `.cline`, Roo `.roo`, Gemini `.gemini` or a custom folder. |
-| Managed file sync | `npx sdlc-harness sync` | Materializes package canonical assets into the configured Harness root while preserving project state, docs and local overrides. |
-| Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects. |
+| Managed file sync | `npx sdlc-harness sync` | Materializes package canonical assets and safely updates package-managed guidance sections inside user-owned Markdown files while preserving project state, docs and local overrides. |
+| Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects, including legacy seed guidance migration. |
 | Diagnostics | `npx sdlc-harness doctor` | Reports Harness root, package version, schema version and key managed paths. |
 | Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks product, design slicing, development, review, test, release, RFC, active plan shape, prompt language contract and generated overview freshness. |
 | Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
@@ -98,6 +98,8 @@ Do not create formal `.docs/07_test/**` test cases or reports before development
 
 `<harnessRoot>/state/memory.md` is only a short cross-stage reminder and navigation surface. It answers what an agent should remember next time and where to find the source. Memory may link to ADRs, PRDs, tech plans or implementation docs; full context, alternatives, tradeoffs and long-term consequences belong in `.docs/05_decisions/` ADRs or other formal `.docs/**` fact sources.
 
+`sync` and `upgrade` also maintain fixed package-managed sections inside user-owned Markdown files: `## Harness Guidance` in `<harnessRoot>/state/memory.md` and `## Harness Maintenance Rules` in `.docs/INDEX.md`. User memory entries, artifact maps and links stay outside those sections and are preserved. Legacy untitled seed guidance is migrated into the titled section to avoid duplicates. `.github/workflows/harness.yml` is updated only when it has `pjsdlc:sdlc-harness:github-workflow:*` markers or exactly matches the old generated workflow; customized workflows without markers are skipped and reported as `customized`.
+
 ## Common Commands
 
 ```sh

package/assets/docs/README.md

@@ -57,8 +57,8 @@ npx sdlc-harness init --adopt
 | 新项目初始化 | `npx sdlc-harness init` | 选择目标 Agent，生成 Harness 根目录、状态文件、workflow skills、模板、策略、`.docs/**` 和 Makefile include |
 | 已有项目接入 | `npx sdlc-harness init --adopt` | 非破坏性接入已有仓库，不覆盖业务代码和已有项目事实源 |
 | 可配置 Harness 根目录 | `--harness-folder`、`package.json#sdlcHarness.harnessFolderName`、`sdlc-harness.config.json` | 支持 `.codex`、`.claude`、`.cursor`、`.cline`、`.roo`、`.gemini` 或自定义目录 |
-| 同步 managed workflow 文件 | `npx sdlc-harness sync` | 从包内 canonical assets 物化 `AGENTS.md` managed block、workflow skills、templates、policies、Makefile 片段和 GitHub workflow |
-| 升级已接入项目 | `npx sdlc-harness upgrade` | 执行迁移并自动 `sync`，保留 state、docs、业务代码和本地 override |
+| 同步 managed workflow 文件 | `npx sdlc-harness sync` | 从包内 canonical assets 物化 `AGENTS.md` managed block、workflow skills、templates、policies、Makefile 片段、GitHub workflow，并安全更新 user-owned Markdown guidance sections |
+| 升级已接入项目 | `npx sdlc-harness upgrade` | 执行迁移并自动 `sync`，保留 state、docs、业务代码和本地 override，同时迁移旧 seed guidance |
 | 接入诊断 | `npx sdlc-harness doctor` | 检查 harness root、版本、schema、关键文件和 managed paths |
 | 阶段 gate | `npx sdlc-harness validate-*`、`make validate-current`、`make validate-harness` | 校验需求、设计切片、开发、Review、测试、发布、RFC、Harness 骨架、提示词语言契约和 overview freshness |
 | 生命周期工作流 | `lifecycle.yaml`、`plan.yaml`、`.docs/**` | 固定 REQUIREMENT_GATHERING、ARCHITECTING、SPRINTING、REVIEWING、TESTING、RELEASING、RFC_RECALIBRATION 等阶段事实链 |
@@ -119,6 +119,8 @@ SPRINTING 的 Definition of Done 包含可运行入口/出口：技术方案或
 
 `<harnessRoot>/state/memory.md` 只做跨阶段快捷提示和导航，回答“下次进来要先记住什么、去哪里找”。memory 可以链接到 ADR、PRD、tech plan 或 implementation doc；完整背景、备选方案、取舍和长期后果放在 `.docs/05_decisions/` ADR 或其它正式 `.docs/**` 事实源里。
 
+`sync` / `upgrade` 会维护用户耦合文件里的固定 package-managed sections：`<harnessRoot>/state/memory.md` 的 `## Harness Guidance` 和 `.docs/INDEX.md` 的 `## Harness Maintenance Rules`。用户自己的 memory 条目、文档产物地图和链接保留在这些标题区块之外；如果旧项目只有早期无标题 seed 文案，升级会把它迁移到固定标题区块，避免重复。`.github/workflows/harness.yml` 只在文件带 `pjsdlc:sdlc-harness:github-workflow:*` marker 或内容等于旧版 generated workflow 时自动更新；自定义且无 marker 的 workflow 会被跳过并报告 `customized`。
+
 ### Workflow skill 如何生效
 
 `<harnessRoot>/skills/<name>/SKILL.md` 是 Harness 的 workflow skill 事实源，也是稳定的 hard file index。它有两种使用方式：

package/assets/github/harness.yml

@@ -1,3 +1,4 @@
+# pjsdlc:sdlc-harness:github-workflow:begin
 name: Harness Gates
 
 on:
@@ -43,3 +44,4 @@ jobs:
         run: make "${HARNESS_GATE}"
         env:
           HARNESS_GATE: ${{ github.event.inputs.gate || 'validate-harness' }}
+# pjsdlc:sdlc-harness:github-workflow:end

package/dist/commands/sync.js

@@ -2,6 +2,9 @@ import { runSync } from "../lib/sync-engine.js";
 export async function sync() {
     const report = await runSync(process.cwd());
     console.log(`sync changed=${report.changed.length} skipped=${report.skipped.length} blocked=${report.blocked.length}`);
+    for (const skipped of report.skipped.filter((line) => line.includes("customized"))) {
+        console.log(`skipped: ${skipped}`);
+    }
     for (const blocked of report.blocked) {
         console.error(`blocked: ${blocked}`);
     }

package/dist/lib/init.js

@@ -3,6 +3,7 @@ import { writeConfigIfMissing } from "./config.js";
 import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
 import { ensureDir, pathExists, writeTextIfChanged } from "./fs.js";
 import { runSync } from "./sync-engine.js";
+import { syncDocsIndexMaintenanceSection, syncMemoryGuidanceSection } from "./user-owned-sections.js";
 const DOC_DIRS = [
     ".docs/00_raw",
     ".docs/01_product",
@@ -55,24 +56,24 @@ async function createProjectState(projectRoot, root, report) {
         ],
         [harnessPath(root, "state", "plan.yaml"), `current_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],
         [harnessPath(root, "state", "plan.draft.yaml"), `next_task_sequence: 1\ntasks: []\n`],
-        [
-            harnessPath(root, "state", "memory.md"),
-            "# Project Memory\n\n短期执行计划写入 plan.yaml；长期稳定知识只在这里记录简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。\n"
-        ]
     ];
     for (const [relative, content] of files) {
         if (await writeTextIfChanged(path.join(projectRoot, relative), content)) {
             report.push(`created ${relative}`);
         }
     }
+    await syncMemoryGuidanceSection(projectRoot, root, {
+        changed: report,
+        skipped: []
+    });
 }
 async function createDocs(projectRoot, report) {
     for (const dir of DOC_DIRS) {
         await ensureDir(path.join(projectRoot, dir));
         await writeTextIfChanged(path.join(projectRoot, dir, ".gitkeep"), "");
     }
-    const index = ".docs/INDEX.md";
-    if (await writeTextIfChanged(path.join(projectRoot, index), "# Documentation Index\n\n本文件是 AI SDLC Harness 的文档路由表。\n")) {
-        report.push(`created ${index}`);
-    }
+    await syncDocsIndexMaintenanceSection(projectRoot, {
+        changed: report,
+        skipped: []
+    });
 }

package/dist/lib/managed-file.d.ts

@@ -10,6 +10,8 @@ export declare const MAKEFILE_BLOCK_START = "# pjsdlc:sdlc-harness:make:begin";
 export declare const MAKEFILE_BLOCK_END = "# pjsdlc:sdlc-harness:make:end";
 export declare const LEGACY_MAKEFILE_BLOCK_START = "# sdlc-harness:make:begin";
 export declare const LEGACY_MAKEFILE_BLOCK_END = "# sdlc-harness:make:end";
+export declare const GITHUB_WORKFLOW_BLOCK_START = "# pjsdlc:sdlc-harness:github-workflow:begin";
+export declare const GITHUB_WORKFLOW_BLOCK_END = "# pjsdlc:sdlc-harness:github-workflow:end";
 export declare const MANAGED_METADATA_START = "<!-- pjsdlc:sdlc-harness-managed";
 export declare const LEGACY_MANAGED_METADATA_START = "<!-- sdlc-harness-managed";
 export declare const MANAGED_METADATA_END = "-->";

package/dist/lib/managed-file.js

@@ -6,6 +6,8 @@ export const MAKEFILE_BLOCK_START = "# pjsdlc:sdlc-harness:make:begin";
 export const MAKEFILE_BLOCK_END = "# pjsdlc:sdlc-harness:make:end";
 export const LEGACY_MAKEFILE_BLOCK_START = "# sdlc-harness:make:begin";
 export const LEGACY_MAKEFILE_BLOCK_END = "# sdlc-harness:make:end";
+export const GITHUB_WORKFLOW_BLOCK_START = "# pjsdlc:sdlc-harness:github-workflow:begin";
+export const GITHUB_WORKFLOW_BLOCK_END = "# pjsdlc:sdlc-harness:github-workflow:end";
 export const MANAGED_METADATA_START = "<!-- pjsdlc:sdlc-harness-managed";
 export const LEGACY_MANAGED_METADATA_START = "<!-- sdlc-harness-managed";
 export const MANAGED_METADATA_END = "-->";

package/dist/lib/migrations.js

@@ -3,6 +3,7 @@ import { readdir, rename, rm } from "node:fs/promises";
 import { defaultConfig, readConfig } from "./config.js";
 import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
+import { syncDocsIndexMaintenanceSection, syncMemoryGuidanceSection } from "./user-owned-sections.js";
 import { parseYaml, stringifyYaml } from "./yaml.js";
 export const CURRENT_SCHEMA_VERSION = "1";
 export const migrations = [];
@@ -27,7 +28,7 @@ export async function runMigrations(projectRoot) {
     await migratePlan(projectRoot, root, report, "plan.draft.yaml", "tasks.draft.yaml", { activePlan: false });
     await removeLegacyGateResults(projectRoot, root, report);
     await removeLegacyCheckpoints(projectRoot, root, report);
-    await ensureMemory(projectRoot, root, report);
+    await ensureUserOwnedGuidanceSections(projectRoot, root, report);
     return report;
 }
 async function migrateConfig(projectRoot, root, report) {
@@ -161,6 +162,9 @@ function migrateManagedFiles(managedFiles, root) {
             migrated.unshift(makefileEntry);
         }
     }
+    if (!seen.has(".github/workflows/harness.yml")) {
+        push({ path: ".github/workflows/harness.yml", strategy: "create-if-missing" });
+    }
     return migrated;
 }
 async function migrateLifecycle(projectRoot, root, report) {
@@ -349,15 +353,7 @@ async function removeLegacyGateResults(projectRoot, root, report) {
     await rm(gateResultsPath, { force: true });
     report.changed.push(relativeGateResultsPath);
 }
-async function ensureMemory(projectRoot, root, report) {
-    const relativeMemoryPath = harnessPath(root, "state", "memory.md");
-    const memoryPath = path.join(projectRoot, relativeMemoryPath);
-    if (await pathExists(memoryPath)) {
-        report.skipped.push(relativeMemoryPath);
-        return;
-    }
-    const content = "# Project Memory\n\n记录跨阶段长期有效知识的简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。\n";
-    if (await writeTextIfChanged(memoryPath, content)) {
-        report.changed.push(relativeMemoryPath);
-    }
+async function ensureUserOwnedGuidanceSections(projectRoot, root, report) {
+    await syncMemoryGuidanceSection(projectRoot, root, report);
+    await syncDocsIndexMaintenanceSection(projectRoot, report);
 }

package/dist/lib/sync-engine.js

@@ -2,8 +2,9 @@ import path from "node:path";
 import { readConfig } from "./config.js";
 import { harnessRoot } from "./harness-root.js";
 import { copyTree, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
-import { AGENTS_BLOCK_MARKERS, MAKEFILE_BLOCK_END, MAKEFILE_BLOCK_MARKERS, MAKEFILE_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from "./managed-file.js";
+import { AGENTS_BLOCK_MARKERS, GITHUB_WORKFLOW_BLOCK_END, GITHUB_WORKFLOW_BLOCK_START, MAKEFILE_BLOCK_END, MAKEFILE_BLOCK_MARKERS, MAKEFILE_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from "./managed-file.js";
 import { packageAssetPath } from "./paths.js";
+import { syncProjectGuidanceSections } from "./user-owned-sections.js";
 import { parseYaml, stringifyYaml } from "./yaml.js";
 export function emptySyncReport() {
     return {
@@ -19,6 +20,7 @@ export async function runSync(projectRoot) {
     for (const managedFile of config.managed_files) {
         await syncManagedFile(projectRoot, root, managedFile, report);
     }
+    await syncProjectGuidanceSections(projectRoot, root, report);
     return report;
 }
 async function syncManagedFile(projectRoot, root, managedFile, report) {
@@ -48,11 +50,7 @@ async function syncManagedFile(projectRoot, root, managedFile, report) {
         return;
     }
     if (managedFile.path === ".github/workflows/harness.yml") {
-        if (await pathExists(destination)) {
-            report.skipped.push(managedFile.path);
-            return;
-        }
-        await syncFile(packageAssetPath("github", "harness.yml"), destination, report, "skip-if-missing");
+        await syncGithubWorkflow(packageAssetPath("github", "harness.yml"), destination, managedFile.path, report);
         return;
     }
     report.skipped.push(managedFile.path);
@@ -368,3 +366,61 @@ async function syncFile(source, destination, report, missingMode) {
         report.skipped.push(destination);
     }
 }
+async function syncGithubWorkflow(source, destination, relativePath, report) {
+    if (!(await pathExists(source))) {
+        report.skipped.push(relativePath);
+        return;
+    }
+    const sourceContent = await readText(source);
+    if (!(await pathExists(destination))) {
+        if (await writeTextIfChanged(destination, sourceContent)) {
+            report.changed.push(relativePath);
+        }
+        else {
+            report.skipped.push(relativePath);
+        }
+        return;
+    }
+    const existing = await readText(destination);
+    const markerState = workflowMarkerState(existing);
+    if (markerState === "invalid") {
+        report.blocked.push(`${relativePath}: incomplete managed workflow markers`);
+        return;
+    }
+    if (markerState === "managed" || normalizeWorkflow(existing) === normalizeWorkflow(stripWorkflowMarkers(sourceContent))) {
+        if (await writeTextIfChanged(destination, sourceContent)) {
+            report.changed.push(relativePath);
+        }
+        else {
+            report.skipped.push(relativePath);
+        }
+        return;
+    }
+    report.skipped.push(`${relativePath}: customized`);
+}
+function workflowMarkerState(content) {
+    const startIndex = content.indexOf(GITHUB_WORKFLOW_BLOCK_START);
+    const endIndex = content.indexOf(GITHUB_WORKFLOW_BLOCK_END);
+    const hasStart = startIndex >= 0;
+    const hasEnd = endIndex >= 0;
+    if (!hasStart && !hasEnd) {
+        return "missing";
+    }
+    if (hasStart !== hasEnd || endIndex < startIndex) {
+        return "invalid";
+    }
+    if (content.indexOf(GITHUB_WORKFLOW_BLOCK_START, startIndex + GITHUB_WORKFLOW_BLOCK_START.length) >= 0 ||
+        content.indexOf(GITHUB_WORKFLOW_BLOCK_END, endIndex + GITHUB_WORKFLOW_BLOCK_END.length) >= 0) {
+        return "invalid";
+    }
+    return "managed";
+}
+function stripWorkflowMarkers(content) {
+    return content
+        .split(/\r?\n/)
+        .filter((line) => line.trim() !== GITHUB_WORKFLOW_BLOCK_START && line.trim() !== GITHUB_WORKFLOW_BLOCK_END)
+        .join("\n");
+}
+function normalizeWorkflow(content) {
+    return content.replace(/\r\n/g, "\n").trim();
+}

package/dist/lib/upgrade.js

@@ -7,6 +7,9 @@ export async function runUpgrade(projectRoot) {
     lines.push(`migrations changed=${migrationReport.changed.length} skipped=${migrationReport.skipped.length}`);
     const syncReport = await runSync(projectRoot);
     lines.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
+    for (const skipped of syncReport.skipped.filter((line) => line.includes("customized"))) {
+        lines.push(`sync skipped: ${skipped}`);
+    }
     const doctor = await runDoctor(projectRoot);
     lines.push(`doctor warnings=${doctor.warnings.length} errors=${doctor.errors.length}`);
     if (syncReport.blocked.length > 0 || doctor.errors.length > 0) {

package/dist/lib/user-owned-sections.d.ts

@@ -0,0 +1,7 @@
+export interface UserOwnedSectionReport {
+    changed: string[];
+    skipped: string[];
+}
+export declare function syncProjectGuidanceSections(projectRoot: string, root: string, report: UserOwnedSectionReport): Promise<void>;
+export declare function syncMemoryGuidanceSection(projectRoot: string, root: string, report: UserOwnedSectionReport): Promise<void>;
+export declare function syncDocsIndexMaintenanceSection(projectRoot: string, report: UserOwnedSectionReport): Promise<void>;

package/dist/lib/user-owned-sections.js

@@ -0,0 +1,105 @@
+import path from "node:path";
+import { pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { harnessPath } from "./harness-root.js";
+const MEMORY_GUIDANCE_HEADING = "## Harness Guidance";
+const DOCS_INDEX_RULES_HEADING = "## Harness Maintenance Rules";
+const LEGACY_MEMORY_PARAGRAPHS = [
+    "短期执行计划写入 plan.yaml；长期稳定知识只在这里记录简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。",
+    "记录跨阶段长期有效知识的简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。",
+    "内容保持简短，详细说明链接到 `.docs/` 下的对应文档。完整决策背景、备选方案、取舍和后果应写入 `.docs/05_decisions/` ADR 或其它正式 `.docs/**` 事实源。"
+];
+const LEGACY_INDEX_MAINTENANCE_SECTION = [
+    "## 维护规则",
+    "",
+    "- 每个新增产物都要从本索引链接。",
+    "- 仍属于产品、架构、实现、测试或 RFC 事实源的过时产物标记为 superseded；短期执行计划和历史发布流水以 git、tag、registry、CI 或外部 release 系统追溯。",
+    "- task/release 的历史动作记录以 git commit、tag 或外部 release 系统为准，不再维护 `<harnessRoot>/archive/` 常规归档。",
+    "- implementation docs 必须对齐真实代码，而不只是原始技术方案。"
+].join("\n");
+export async function syncProjectGuidanceSections(projectRoot, root, report) {
+    await syncMemoryGuidanceSection(projectRoot, root, report);
+    await syncDocsIndexMaintenanceSection(projectRoot, report);
+}
+export async function syncMemoryGuidanceSection(projectRoot, root, report) {
+    const relativePath = harnessPath(root, "state", "memory.md");
+    const targetPath = path.join(projectRoot, relativePath);
+    const existing = (await pathExists(targetPath)) ? await readText(targetPath) : "# Project Memory\n";
+    const next = mergeMarkdownSection(removeLegacyMemoryGuidance(existing), MEMORY_GUIDANCE_HEADING, renderMemoryGuidanceSection(root));
+    await writeSectionIfChanged(targetPath, relativePath, next, report);
+}
+export async function syncDocsIndexMaintenanceSection(projectRoot, report) {
+    const relativePath = ".docs/INDEX.md";
+    const targetPath = path.join(projectRoot, relativePath);
+    const existing = (await pathExists(targetPath))
+        ? await readText(targetPath)
+        : "# Documentation Index\n\n本文件是 AI SDLC Harness 的文档路由表。\n";
+    const next = mergeMarkdownSection(removeLegacyIndexMaintenanceSection(existing), DOCS_INDEX_RULES_HEADING, renderDocsIndexMaintenanceSection());
+    await writeSectionIfChanged(targetPath, relativePath, next, report);
+}
+function renderMemoryGuidanceSection(root) {
+    const planPath = harnessPath(root, "state", "plan.yaml");
+    return [
+        MEMORY_GUIDANCE_HEADING,
+        "",
+        "- 内容保持简短，详细说明链接到 `.docs/` 下的对应文档。",
+        `- 短期执行计划写入 \`${planPath}\`；长期稳定知识只在这里记录简短摘要和链接。`,
+        "- 完整决策背景、备选方案、取舍和后果应写入 `.docs/05_decisions/` ADR 或其它正式 `.docs/**` 事实源。"
+    ].join("\n");
+}
+function renderDocsIndexMaintenanceSection() {
+    return [
+        DOCS_INDEX_RULES_HEADING,
+        "",
+        "- `overview.md` 是 generated artifact，用于浏览和阶段交接；不要手写或局部编辑。",
+        "- Markdown slices 和 `.docs/INDEX.md` 是事实源。",
+        "- 任意 `.docs/<stage>/**/*.md` 新增、修改、拆分、合并或废弃后，运行 `make docs-overview`。",
+        "- 提交或阶段交付前，运行 `make validate-doc-overviews` 或 `make validate-harness` 确认 overview 未过期。",
+        "- 每个新增产物都要从本索引链接；implementation docs 必须对齐真实代码。"
+    ].join("\n");
+}
+function removeLegacyMemoryGuidance(content) {
+    let next = content;
+    for (const paragraph of LEGACY_MEMORY_PARAGRAPHS) {
+        next = next.replace(paragraph, "");
+    }
+    return compactBlankLines(next);
+}
+function removeLegacyIndexMaintenanceSection(content) {
+    return compactBlankLines(content.replace(LEGACY_INDEX_MAINTENANCE_SECTION, ""));
+}
+function mergeMarkdownSection(existing, heading, section) {
+    const normalizedExisting = existing.replace(/\r\n/g, "\n").trimEnd();
+    const normalizedSection = section.trimEnd();
+    if (!normalizedExisting) {
+        return `${normalizedSection}\n`;
+    }
+    const lines = normalizedExisting.split("\n");
+    const startIndex = lines.findIndex((line) => line.trim() === heading);
+    if (startIndex < 0) {
+        return `${normalizedExisting}\n\n${normalizedSection}\n`;
+    }
+    const headingLevel = heading.match(/^#+/)?.[0].length ?? 2;
+    let endIndex = lines.length;
+    for (let index = startIndex + 1; index < lines.length; index += 1) {
+        const match = lines[index].match(/^(#{1,6})\s+/);
+        if (match && match[1].length <= headingLevel) {
+            endIndex = index;
+            break;
+        }
+    }
+    const before = lines.slice(0, startIndex).join("\n").trimEnd();
+    const after = lines.slice(endIndex).join("\n").trimStart();
+    const parts = [before, normalizedSection, after].filter((part) => part.trim());
+    return `${parts.join("\n\n")}\n`;
+}
+async function writeSectionIfChanged(targetPath, relativePath, content, report) {
+    if (await writeTextIfChanged(targetPath, content)) {
+        report.changed.push(relativePath);
+    }
+    else {
+        report.skipped.push(relativePath);
+    }
+}
+function compactBlankLines(content) {
+    return content.replace(/\r\n/g, "\n").replace(/\n{3,}/g, "\n\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {