project-tiny-context-harness 0.2.48 → 0.2.50

package/README.md

@@ -115,7 +115,7 @@ npm ci
 npm run smoke:quickstart
 npm run preview:pack
 cd /path/to/your/test-repo
-npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.42.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.50.tgz
 npx --no-install sdlc-harness init --adopt
 make validate-context
 ```
@@ -228,8 +228,9 @@ Use `npx --no-install sdlc-harness ...` only when you explicitly want the alread
 | Development engineer Skill | `<harnessRoot>/skills/context_development_engineer/SKILL.md` | Handles explicit development-engineering requests and writes durable engineering conclusions to `project_context/**`. |
 | Full project context export Skill | `<harnessRoot>/skills/context_full_project_export/SKILL.md` | Handles explicit full-project or code-level export requests and uses `export-context --all`, `--full` or `--code` to create temporary artifacts under `tmp/sdlc/context-exports/**`. |
 | Project-local Skills | `<harnessRoot>/skills/<role>/SKILL.md` | Optional local product/design/development Skills created by the project, such as `product_plan`, `uiux_design` or `development_engineer`. They supersede package-managed default Skills when more specific, are not overwritten by `sync`, and should keep front matter trigger keywords aligned with the project `AGENTS.md` role-trigger rule. |
-| Managed file sync | `make sdlc-sync` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness sync` | Refreshes package-managed guidance, default Skills, Makefile include, context templates, tools and workflow YAML. It does not perform semantic Context generation. |
-| Upgrade | `make sdlc-upgrade` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade` | Runs safe migrations and `sync`, including Schema v4 Context graph manifest creation when missing. |
+| Managed file sync | `make sdlc-sync` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness sync` | Refreshes package-managed guidance, default Skills, Makefile include, context templates, tools and workflow YAML. It does not run migrations or perform semantic Context generation; when migration work is pending it refuses to write and tells you to run `upgrade`. |
+| Upgrade | `make sdlc-upgrade` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade` | Default command after updating the npm package. Builds an upgrade plan, applies `safe_pending` migrations, runs `sync` and `doctor`, and exits non-zero when manual or blocked follow-up remains. |
+| Upgrade check | `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --check [--json]` | Checks the upgrade plan without writing files. Reports `safe_pending`, `manual_required` and `blocked`; exits non-zero when any work remains. |
 | Combined project export | `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --all [--check]` | Creates both default temporary exports under `tmp/sdlc/context-exports/**`. |
 | Project Context export | `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --full [--output tmp/sdlc/context-exports/name.md] [--check]` | Creates a temporary Context summary artifact. It is not Context and must not be registered in `project_context/context.toml`. |
 | Code implementation export | `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --code [--output tmp/sdlc/context-exports/name.md] [--check]` | Creates a temporary single-file code implementation artifact. It is not Context and must not be registered in `project_context/context.toml`. |
@@ -370,11 +371,39 @@ $EDITOR <harnessRoot>/skills/uiux_design/SKILL.md
 
 When a project-local Skill and a package-managed default Skill both apply, agents should use the more specific project-local Skill first. The local Skill should keep durable conclusions in `project_context/**` and `DESIGN.md`. Its front matter `description` should stay aligned with the matching default `context_*` Skill and the project `AGENTS.md` role-trigger rule; update both the local Skill and agent guidance when adding or narrowing product/design/development trigger terms. `sync` does not merge Skill overrides and does not overwrite separate project-local Skills. Existing `<harnessRoot>/pjsdlc_managed/override_skills/*.md` files should be migrated into standalone project-local Skills before running `sync`.
 
-## Sync And Upgrade Boundary
-
-`sync` is intentionally narrow. It refreshes managed files and never generates project semantics.
-
-`upgrade` performs safe package migrations and `sync`. The former migration command has been removed because existing users have completed migration.
+## Sync And Upgrade Boundary
+
+`sync` is intentionally narrow. It refreshes managed files and never generates project semantics. `sync` does not run migrations; if it detects `safe_pending`, `manual_required` or `blocked` migration work, it refuses to write and points the user to `upgrade`.
+
+After updating the package, run `sdlc-harness upgrade`. Use `sync` only when release notes say the update is `sync-only`.
+
+`upgrade` first builds an upgrade plan, applies only `safe_pending` migrations, then runs `sync` and `doctor`. If `manual_required` or `blocked` items remain, the command exits non-zero and prints follow-up. `upgrade --check` performs the same planning step without writing files; `upgrade --check --json` is intended for release checks and CI.
+
+Release update modes:
+
+| Update mode | What to run | Meaning |
+|---|---|---|
+| `sync-only` | `sdlc-harness sync` | The release changes only package-managed assets. No migrations are required. |
+| `upgrade-required` | `sdlc-harness upgrade` | The release includes safe mechanical migrations and managed asset refresh. |
+| `manual-required` | `sdlc-harness upgrade`, then manual follow-up | The release includes items that cannot be mechanically changed without user intent. |
+
+Migration statuses:
+
+| Status | Meaning |
+|---|---|
+| `safe_pending` | A known Harness schema, config or path convention can be migrated mechanically. |
+| `manual_required` | The path is in migration scope, but the Harness cannot prove the right semantic role or user intent. |
+| `blocked` | A target conflict or overwrite risk prevents a safe write. |
+
+Examples:
+
+- `project_context/modules/main.md` -> `project_context/areas/main.md` is safe when the target does not already exist.
+- Missing `project_context/context.toml` can receive a conservative baseline manifest.
+- `project_context/areas/main/verification.md` can be registered as `verification` by path convention.
+- `project_context/areas/payment/api.md` without a manifest role is `manual_required`; the Harness does not guess whether it is an area, contract, foundation or implementation index.
+- If the target already exists, the migration is `blocked` and no file is overwritten.
+
+The former migration command has been removed because existing users have completed that migration path.
 
 ## Common Commands
 
@@ -382,13 +411,15 @@ When a project-local Skill and a package-managed default Skill both apply, agent
 npx --yes --package project-tiny-context-harness@latest sdlc-harness init
 npx --yes --package project-tiny-context-harness@latest sdlc-harness init --adopt
 npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --all
-npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --full
-npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --code
-make sdlc-sync
-make sdlc-upgrade
-npx --yes --package project-tiny-context-harness@latest sdlc-harness validate-context
-npx --yes --package project-tiny-context-harness@latest sdlc-harness doctor
-make sdlc-doctor
+npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --full
+npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --code
+make sdlc-sync
+make sdlc-upgrade
+npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --check
+npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --check --json
+npx --yes --package project-tiny-context-harness@latest sdlc-harness validate-context
+npx --yes --package project-tiny-context-harness@latest sdlc-harness doctor
+make sdlc-doctor
 make validate-context
 make validate-harness
 ```

package/assets/README.md

@@ -94,7 +94,7 @@ That smoke packs the local workspace, installs it into a disposable repo, runs `
 ```sh
 npm run preview:pack
 cd /path/to/your/test-repo
-npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.42.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.50.tgz
 npx --no-install sdlc-harness init --adopt
 make validate-context
 ```
@@ -287,23 +287,60 @@ Use `npx --no-install sdlc-harness ...` only when you explicitly want the alread
 
 ## Core Commands
 
-| Command | Purpose |
-|---|---|
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness init` | Non-destructively installs Minimal Context Harness into the current project. |
-| `make sdlc-sync` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness sync` | Refreshes managed guidance, default Skills, Makefile include, tools and templates. It does not generate project semantics. |
-| `make sdlc-upgrade` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade` | Runs safe package migrations and `sync`, including Schema v4 Context graph manifest creation when missing. |
+| Command | Purpose |
+|---|---|
+| `npx --yes --package project-tiny-context-harness@latest sdlc-harness init` | Non-destructively installs Minimal Context Harness into the current project. |
+| `make sdlc-sync` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness sync` | Refreshes managed guidance, default Skills, Makefile include, tools and templates. It does not run migrations or generate project semantics; when migration work is pending it refuses to write and tells you to run `upgrade`. |
+| `make sdlc-upgrade` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade` | Default command after updating the npm package. Builds an upgrade plan, applies `safe_pending` migrations, runs `sync` and `doctor`, and exits non-zero when manual or blocked follow-up remains. |
+| `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --check [--json]` | Checks the upgrade plan without writing files. Reports `safe_pending`, `manual_required` and `blocked`; exits non-zero when any work remains. |
 | `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --all [--check]` | Creates both default temporary exports under `tmp/sdlc/context-exports/**`. |
 | `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --full [--output tmp/sdlc/context-exports/name.md] [--check]` | Creates a temporary project Context summary Markdown artifact. |
 | `npx --yes --package project-tiny-context-harness@latest sdlc-harness export-context --code [--output tmp/sdlc/context-exports/name.md] [--check]` | Creates a temporary single-file code implementation Markdown artifact. |
-| `npx --yes --package project-tiny-context-harness@latest sdlc-harness validate-context` | Checks minimum project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
+| `npx --yes --package project-tiny-context-harness@latest sdlc-harness validate-context` | Checks minimum project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
 | `make validate-context` | Makefile wrapper for `validate-context`. |
 | `make validate-harness` | Compatibility alias for `validate-context` in vNext projects. |
-| `sdlc-harness package sync-source` | Maintainer-only command to sync source workspace assets into `packages/sdlc-harness/assets/**`. |
-| `sdlc-harness package check-source` | Maintainer-only drift check for package canonical assets. |
-
-## Minimal Context Files
-
-`project_context/global.md` is the first file a fresh agent should read. It contains:
+| `sdlc-harness package sync-source` | Maintainer-only command to sync source workspace assets into `packages/sdlc-harness/assets/**`. |
+| `sdlc-harness package check-source` | Maintainer-only drift check for package canonical assets. |
+
+## Updating Existing Projects
+
+After updating the package, run `sdlc-harness upgrade`. Use `sync` only when release notes say the update is `sync-only`; sync does not run migrations.
+
+```sh
+npm install -D project-tiny-context-harness@latest
+npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --check
+npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade
+```
+
+Release notes and release readiness use this update mode vocabulary:
+
+| Update mode | What to run | Meaning |
+|---|---|---|
+| `sync-only` | `sdlc-harness sync` | The release changes only package-managed assets. No migrations are required. |
+| `upgrade-required` | `sdlc-harness upgrade` | The release includes safe mechanical migrations and managed asset refresh. |
+| `manual-required` | `sdlc-harness upgrade`, then manual follow-up | The release includes items that cannot be mechanically changed without user intent. |
+
+`upgrade --check` prints the plan without writing files. The plan groups work as:
+
+| Status | Meaning |
+|---|---|
+| `safe_pending` | The Harness can prove the change is inside a known Harness-owned schema, config or path convention and can apply it mechanically. |
+| `manual_required` | The file is in migration scope, but the Harness cannot prove the right semantic role or user intent. It prints the path and follow-up. |
+| `blocked` | A safe target cannot be written, usually because the destination already exists or another conflict would require overwriting user content. |
+
+`upgrade` promises to refresh package-managed assets, apply known safe migrations, avoid overwriting user custom content, expose manual-required migration scope, and run `doctor` / `validate-context` style diagnostics so remaining problems are visible. It does not automatically understand the user's project semantics, decide every Context role, repair project-local Skills, invent business verification paths, update product/deployment facts or turn an old project into the current best-practice shape.
+
+Examples:
+
+- `project_context/modules/main.md` -> `project_context/areas/main.md` is a safe mechanical migration when the target does not already exist.
+- A missing `project_context/context.toml` can receive a conservative baseline manifest.
+- `project_context/areas/main/verification.md` can be registered as a `verification` role by path convention.
+- `project_context/areas/payment/api.md` without a manifest role is reported as `manual_required`; the Harness does not guess whether it is an area, contract, foundation or implementation index.
+- If `project_context/areas/main.md` already exists while `project_context/modules/main.md` still exists, the migration is `blocked` and no file is overwritten.
+
+## Minimal Context Files
+
+`project_context/global.md` is the first file a fresh agent should read. It contains:
 
 - project goal
 - non-goals / boundaries

package/assets/make/sdlc-harness.mk

@@ -6,8 +6,8 @@ SDLC_HARNESS ?= $(if $(wildcard packages/sdlc-harness/dist/cli.js),node packages
 help:
 	@echo "Minimal Context Harness commands"
 	@echo "  make sdlc-doctor         Diagnose Harness root, core package and schema version"
-	@echo "  make sdlc-sync           Refresh managed guidance, Context templates, default Skills and tools"
-	@echo "  make sdlc-upgrade        Run safe upgrade migrations and refresh managed assets"
+	@echo "  make sdlc-sync           Refresh managed assets; refuses when upgrade migrations are pending"
+	@echo "  make sdlc-upgrade        Run safe upgrade migrations, sync managed assets and doctor"
 	@echo "  make validate-context    Check whether project_context/** supports context recovery"
 	@echo "  make validate-harness    Compatibility alias for validate-context"
 	@echo "  make test-all            Run the project regression suite after replacing this placeholder"

package/assets/skills/context_development_engineer/SKILL.md

@@ -39,15 +39,16 @@ Project-specific engineering rules belong in a separate project-local Skill unde
    - 对候选点说明当前重复 / 耦合证据、抽象后的边界、收益、风险和是否值得现在做。
    - 默认只实施高收益、低风险、语义稳定的候选项。
    - 不为一次性代码、不稳定语义或纯粹好看的架构做抽象。
-13. 需要沉淀长期事实时，只更新 `project_context/**`：
-   - 全局工程取舍、跨产品域索引或当前状态写入 `global.md`。
-   - 产品域 API、数据契约、关键约束、入口和风险写入对应 area / subdomain Context。
-   - 跨域接口语义写入 `context_role: contract` 或 manifest role 为 `contract` 的 Context；关键重复验证路径写入 `verification`；关键部署、运行拓扑或云端初始化路径写入 `deployment`；代码入口索引用 `implementation-index`；底层理论源用 `foundation`；历史归档索引用 `archive`。
-   - 新 context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
-   - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
-14. 实现收尾时做 `Contract Conformance` 和 Context drift check：确认代码没有引入未沉淀的长期事实，且 Context 没有退化成普通实现摘要；交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和验证入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。
-15. Context 只能声明验证 / 部署关键路径或验收信号，不能伪造“测试已通过”或“部署已成功”。
-16. Verification / Deployment Role Context 只记录长期可复用的重复执行路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload。
+13. 当人工流程呈现重复、确定性、容易漏步骤或顺序影响正确性时，主动评估是否应沉淀为 repo-local tool/script。脚本应放在 owning module 的工具目录并配测试；可恢复的执行入口、参数约束和适用边界写入对应 verification / deployment Context。Skill 只记录这类脚本化机会识别原则，不承载具体模块命令、provider id、artifact 路径或一次性运行结果。
+14. 需要沉淀长期事实时，只更新 `project_context/**`：
+   - 全局工程取舍、跨产品域索引或当前状态写入 `global.md`。
+   - 产品域 API、数据契约、关键约束、入口和风险写入对应 area / subdomain Context。
+   - 跨域接口语义写入 `context_role: contract` 或 manifest role 为 `contract` 的 Context；关键重复验证路径写入 `verification`；关键部署、运行拓扑或云端初始化路径写入 `deployment`；代码入口索引用 `implementation-index`；底层理论源用 `foundation`；历史归档索引用 `archive`。
+   - 新 context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
+   - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
+15. 实现收尾时做 `Contract Conformance` 和 Context drift check：确认代码没有引入未沉淀的长期事实，且 Context 没有退化成普通实现摘要；交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和验证入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。
+16. Context 只能声明验证 / 部署关键路径或验收信号，不能伪造“测试已通过”或“部署已成功”。
+17. Verification / Deployment Role Context 只记录长期可复用的重复执行路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload。
 
 ## UI 实现对齐
 

package/dist/commands/index.js

@@ -21,8 +21,9 @@ export function help() {
     console.log(`sdlc-harness commands:
   init [--adopt] [--harness-folder <path>]
                        Initialize/adopt a project; without --harness-folder, choose target agent first
-  sync                 Materialize canonical assets into the workspace
-  upgrade              Run migrations and then sync
+  sync                 Refresh managed assets; refuses when upgrade migrations are pending
+  upgrade [--check] [--json]
+                       Run safe migrations, sync managed assets and doctor
   doctor               Diagnose project configuration and drift
   export-context --full|--code|--all [--output <path>] [--check]
                        Export a temporary Context summary or code implementation Markdown artifact

package/dist/commands/upgrade.d.ts

@@ -1 +1 @@
-export declare function upgrade(): Promise<void>;
+export declare function upgrade(args?: string[]): Promise<void>;

package/dist/commands/upgrade.js

@@ -1,7 +1,62 @@
+import { createUpgradePlan, formatUpgradePlan, hasUpgradePlanWork, updateModeForPlan } from "../lib/migrations.js";
 import { runUpgrade } from "../lib/upgrade.js";
-export async function upgrade() {
+export async function upgrade(args = []) {
+    const options = parseArgs(args);
+    if (options.help) {
+        printHelp();
+        return;
+    }
+    if (options.check) {
+        const plan = await createUpgradePlan(process.cwd());
+        if (options.json) {
+            console.log(JSON.stringify({ mode: updateModeForPlan(plan), ...plan }, null, 2));
+        }
+        else {
+            for (const line of formatUpgradePlan(plan)) {
+                console.log(line);
+            }
+        }
+        if (hasUpgradePlanWork(plan)) {
+            process.exitCode = 1;
+        }
+        return;
+    }
     const report = await runUpgrade(process.cwd());
+    if (options.json) {
+        console.log(JSON.stringify({ lines: report }, null, 2));
+        return;
+    }
     for (const line of report) {
         console.log(line);
     }
 }
+function parseArgs(args) {
+    const options = { check: false, json: false, help: false };
+    for (const arg of args) {
+        if (arg === "--check") {
+            options.check = true;
+        }
+        else if (arg === "--json") {
+            options.json = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            options.help = true;
+        }
+        else {
+            throw new Error(`unknown upgrade argument: ${arg}`);
+        }
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`sdlc-harness upgrade:
+  upgrade              Run safe migrations, sync managed assets and doctor
+  upgrade --check      Print the upgrade plan without writing files
+  upgrade --check --json
+                       Print the upgrade plan as JSON
+
+Update modes:
+  sync-only            No migrations are pending
+  upgrade-required     Safe migrations are pending
+  manual-required      Manual review or blockers are present`);
+}

package/dist/lib/migrations.d.ts

@@ -1,11 +1,39 @@
+export type UpgradePlanItemStatus = "safe_pending" | "manual_required" | "blocked";
+export interface UpgradePlanItem {
+    id: string;
+    introducedIn: string;
+    description: string;
+    scope: string;
+    status: UpgradePlanItemStatus;
+    message: string;
+    path?: string;
+}
+export interface UpgradePlan {
+    safe_pending: UpgradePlanItem[];
+    manual_required: UpgradePlanItem[];
+    blocked: UpgradePlanItem[];
+}
+export type ReleaseUpdateMode = "sync-only" | "upgrade-required" | "manual-required";
 export interface Migration {
-    from: string;
-    to: string;
+    id: string;
+    introducedIn: string;
     description: string;
+    scope: string;
+    risk: "safe" | "manual";
+    manualMessage: string;
+    detect(projectRoot: string, root: string, migrationId: string): Promise<UpgradePlanItem[]>;
+    apply?(projectRoot: string, root: string, report: MigrationReport): Promise<void>;
+    verify(projectRoot: string, root: string): Promise<void>;
 }
-export declare const migrations: Migration[];
 export interface MigrationReport {
     changed: string[];
     skipped: string[];
+    manualRequired: UpgradePlanItem[];
+    blocked: UpgradePlanItem[];
 }
+export declare const migrations: Migration[];
+export declare function createUpgradePlan(projectRoot: string): Promise<UpgradePlan>;
+export declare function hasUpgradePlanWork(plan: UpgradePlan): boolean;
+export declare function updateModeForPlan(plan: UpgradePlan): ReleaseUpdateMode;
+export declare function formatUpgradePlan(plan: UpgradePlan): string[];
 export declare function runMigrations(projectRoot: string): Promise<MigrationReport>;

package/dist/lib/migrations.js

@@ -2,21 +2,135 @@ import path from "node:path";
 import { promises as fs } from "node:fs";
 import { CONTEXT_MANIFEST_PATH, contextManifestFromExistingAreas } from "./context-manifest.js";
 import { architectureContextTemplate, areaContextTemplate, globalContextTemplate, verificationContextTemplate } from "./context-templates.js";
+import { CURRENT_SCHEMA_VERSION } from "./constants.js";
 import { defaultConfig, readConfig } from "./config.js";
 import { createDesignMdIfMissing, DESIGN_MD_PATH } from "./design-md.js";
 import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { harnessConfigPath, harnessRoot } from "./harness-root.js";
 import { stringifyYaml } from "./yaml.js";
-export const migrations = [];
+async function verifyNoop() {
+    return;
+}
+export const migrations = [
+    {
+        id: "schema-v4-config-refresh",
+        introducedIn: "0.2.0",
+        description: "Refresh Harness config core metadata and managed-file list for Schema v4.",
+        scope: "<harnessRoot>/config.yaml",
+        risk: "safe",
+        manualMessage: "Review Harness config manually if custom managed-file paths still drift after upgrade.",
+        detect: detectConfigRefresh,
+        apply: migrateConfig,
+        verify: verifyNoop
+    },
+    {
+        id: "legacy-modules-to-areas",
+        introducedIn: "0.2.0",
+        description: "Move legacy project_context/modules/**/*.md files to project_context/areas/**/*.md.",
+        scope: "project_context/modules/**",
+        risk: "safe",
+        manualMessage: "Resolve target conflicts manually; the Harness will not overwrite existing area Context files.",
+        detect: detectLegacyModulesToAreas,
+        apply: migrateLegacyModulesToAreas,
+        verify: verifyNoop
+    },
+    {
+        id: "context-manifest-baseline",
+        introducedIn: "0.2.0",
+        description: "Create the Schema v4 project_context/context.toml manifest when missing.",
+        scope: "project_context/context.toml and project_context/areas/**",
+        risk: "safe",
+        manualMessage: "Review deep area files without manifest roles and assign explicit context roles when needed.",
+        detect: detectContextManifestBaseline,
+        apply: migrateContextManifest,
+        verify: verifyNoop
+    },
+    {
+        id: "global-context-v4-sections",
+        introducedIn: "0.2.0",
+        description: "Add missing Schema v4 global Context sections and rewrite legacy module links.",
+        scope: "project_context/global.md",
+        risk: "safe",
+        manualMessage: "Review global Context manually if project-specific long-term facts need refinement.",
+        detect: detectGlobalContextSections,
+        apply: migrateGlobalContextSections,
+        verify: verifyNoop
+    },
+    {
+        id: "design-md-baseline",
+        introducedIn: "0.2.0",
+        description: "Create DESIGN.md for existing Harness projects when missing.",
+        scope: "DESIGN.md",
+        risk: "safe",
+        manualMessage: "Review the starter design baseline and replace it with project-specific visual facts when available.",
+        detect: detectDesignMdBaseline,
+        apply: migrateDesignMd,
+        verify: verifyNoop
+    },
+    {
+        id: "deprecated-skill-overrides",
+        introducedIn: "0.2.0",
+        description: "Report deprecated managed skill overrides that must move to standalone project-local Skills.",
+        scope: "<harnessRoot>/pjsdlc_managed/override_skills/**",
+        risk: "manual",
+        manualMessage: "Move override files into standalone project-local Skills before running sync.",
+        detect: detectDeprecatedSkillOverrides,
+        verify: verifyNoop
+    }
+];
+export async function createUpgradePlan(projectRoot) {
+    const root = await harnessRoot(projectRoot);
+    const plan = { safe_pending: [], manual_required: [], blocked: [] };
+    for (const migration of migrations) {
+        for (const item of await migration.detect(projectRoot, root, migration.id)) {
+            plan[item.status].push(item);
+        }
+    }
+    return plan;
+}
+export function hasUpgradePlanWork(plan) {
+    return plan.safe_pending.length > 0 || plan.manual_required.length > 0 || plan.blocked.length > 0;
+}
+export function updateModeForPlan(plan) {
+    if (plan.manual_required.length > 0 || plan.blocked.length > 0) {
+        return "manual-required";
+    }
+    if (plan.safe_pending.length > 0) {
+        return "upgrade-required";
+    }
+    return "sync-only";
+}
+export function formatUpgradePlan(plan) {
+    const lines = [
+        `upgrade plan mode=${updateModeForPlan(plan)} safe_pending=${plan.safe_pending.length} manual_required=${plan.manual_required.length} blocked=${plan.blocked.length}`
+    ];
+    for (const status of ["safe_pending", "manual_required", "blocked"]) {
+        for (const item of plan[status]) {
+            const location = item.path ? ` ${item.path}` : "";
+            lines.push(`${status}: ${item.id}${location} - ${item.message}`);
+        }
+    }
+    return lines;
+}
 export async function runMigrations(projectRoot) {
-    const report = { changed: [], skipped: [] };
+    const report = { changed: [], skipped: [], manualRequired: [], blocked: [] };
     const root = await harnessRoot(projectRoot);
-    await migrateConfig(projectRoot, root, report);
-    await migrateLegacyModulesToAreas(projectRoot, report);
+    const plan = await createUpgradePlan(projectRoot);
+    report.manualRequired.push(...plan.manual_required);
+    report.blocked.push(...plan.blocked);
+    for (const migration of migrations) {
+        if (!migration.apply) {
+            continue;
+        }
+        if (!plan.safe_pending.some((item) => item.id === migration.id)) {
+            report.skipped.push(migration.id);
+            continue;
+        }
+        await migration.apply(projectRoot, root, report);
+        await migration.verify(projectRoot, root);
+    }
     await migrateBaseProjectContext(projectRoot, report);
-    await migrateContextManifest(projectRoot, report);
     await migrateManifestModulePaths(projectRoot, report);
-    await migrateDesignMd(projectRoot, report);
     return report;
 }
 async function migrateBaseProjectContext(projectRoot, report) {
@@ -40,12 +154,30 @@ async function migrateBaseProjectContext(projectRoot, report) {
             report.skipped.push(relative);
         }
     }
-    await migrateGlobalContextSections(projectRoot, report);
 }
-async function migrateGlobalContextSections(projectRoot, report) {
+async function detectGlobalContextSections(projectRoot, _root, migration) {
     const relative = "project_context/global.md";
     const target = path.join(projectRoot, ...relative.split("/"));
     if (!(await pathExists(target))) {
+        return [];
+    }
+    const original = await readText(target);
+    const rewritten = rewriteLegacyModuleReferences(original);
+    const needsSections = !hasHeading(rewritten, "Architecture Context") ||
+        !hasHeading(rewritten, "Context Graph") ||
+        !hasHeading(rewritten, "Context Index");
+    if (!needsSections && rewritten === original) {
+        return [];
+    }
+    return [
+        item(migration, "safe_pending", relative, "Global Context needs Schema v4 sections or legacy module path rewrites.")
+    ];
+}
+async function migrateGlobalContextSections(projectRoot, _root, report) {
+    const relative = "project_context/global.md";
+    const target = path.join(projectRoot, ...relative.split("/"));
+    if (!(await pathExists(target))) {
+        report.skipped.push(relative);
         return;
     }
     const original = await readText(target);
@@ -61,14 +193,31 @@ async function migrateGlobalContextSections(projectRoot, report) {
         additions.push("## Context Index", "", "- See `project_context/context.toml` for the current area and context node list.", "");
     }
     if (additions.length === 0 && rewritten === original) {
+        report.skipped.push(`${relative}#schema-v4-sections`);
         return;
     }
     const next = additions.length === 0 ? rewritten : `${rewritten.replace(/\s*$/, "\n\n")}${additions.join("\n")}`;
     if (await writeTextIfChanged(target, next)) {
         report.changed.push(`${relative}#schema-v4-sections`);
     }
+    else {
+        report.skipped.push(`${relative}#schema-v4-sections`);
+    }
 }
-async function migrateContextManifest(projectRoot, report) {
+async function detectContextManifestBaseline(projectRoot, _root, migration) {
+    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
+    if (await pathExists(manifestPath)) {
+        return [];
+    }
+    const items = [
+        item(migration, "safe_pending", CONTEXT_MANIFEST_PATH, "Context graph manifest is missing and can be created from existing area files.")
+    ];
+    for (const ambiguous of await ambiguousAreaContextFiles(projectRoot)) {
+        items.push(item(migration, "manual_required", ambiguous, "Deep area Context cannot be safely role-classified by path alone; review context.toml after upgrade."));
+    }
+    return items;
+}
+async function migrateContextManifest(projectRoot, _root, report) {
     const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
     if (await pathExists(manifestPath)) {
         report.skipped.push(CONTEXT_MANIFEST_PATH);
@@ -81,7 +230,26 @@ async function migrateContextManifest(projectRoot, report) {
         report.skipped.push(CONTEXT_MANIFEST_PATH);
     }
 }
-async function migrateLegacyModulesToAreas(projectRoot, report) {
+async function detectLegacyModulesToAreas(projectRoot, _root, migration) {
+    const modulesRoot = path.join(projectRoot, "project_context", "modules");
+    const areasRoot = path.join(projectRoot, "project_context", "areas");
+    const moduleFiles = (await listFiles(modulesRoot)).filter((file) => file.endsWith(".md")).sort();
+    const items = [];
+    for (const source of moduleFiles) {
+        const relativeToModules = path.relative(modulesRoot, source);
+        const sourceRelative = `project_context/modules/${relativeToModules.split(path.sep).join("/")}`;
+        const targetRelative = `project_context/areas/${relativeToModules.split(path.sep).join("/")}`;
+        const target = path.join(areasRoot, relativeToModules);
+        if (await pathExists(target)) {
+            items.push(item(migration, "blocked", sourceRelative, `Cannot move to ${targetRelative} because the target already exists.`));
+        }
+        else {
+            items.push(item(migration, "safe_pending", sourceRelative, `Move to ${targetRelative}.`));
+        }
+    }
+    return items;
+}
+async function migrateLegacyModulesToAreas(projectRoot, _root, report) {
     const modulesRoot = path.join(projectRoot, "project_context", "modules");
     const areasRoot = path.join(projectRoot, "project_context", "areas");
     const moduleFiles = (await listFiles(modulesRoot)).filter((file) => file.endsWith(".md")).sort();
@@ -120,7 +288,12 @@ async function migrateManifestModulePaths(projectRoot, report) {
         report.changed.push(`${CONTEXT_MANIFEST_PATH}#areas-paths`);
     }
 }
-async function migrateDesignMd(projectRoot, report) {
+async function detectDesignMdBaseline(projectRoot, _root, migration) {
+    return (await pathExists(path.join(projectRoot, DESIGN_MD_PATH)))
+        ? []
+        : [item(migration, "safe_pending", DESIGN_MD_PATH, "DESIGN.md is missing and can be created with the package baseline.")];
+}
+async function migrateDesignMd(projectRoot, _root, report) {
     if (await createDesignMdIfMissing(projectRoot)) {
         report.changed.push(DESIGN_MD_PATH);
     }
@@ -128,6 +301,26 @@ async function migrateDesignMd(projectRoot, report) {
         report.skipped.push(DESIGN_MD_PATH);
     }
 }
+async function detectConfigRefresh(projectRoot, root, migration) {
+    const relativeConfigPath = await harnessConfigPath(projectRoot);
+    const configPath = path.join(projectRoot, relativeConfigPath);
+    if (!(await pathExists(configPath))) {
+        return [];
+    }
+    const config = await readConfig(projectRoot);
+    const current = defaultConfig(root);
+    const managedMatches = JSON.stringify(config.managed_files) === JSON.stringify(current.managed_files);
+    const neverOverwriteHasDefaults = current.never_overwrite.every((entry) => config.never_overwrite.includes(entry));
+    if (config.core.package === current.core.package &&
+        config.core.schema_version === CURRENT_SCHEMA_VERSION &&
+        managedMatches &&
+        neverOverwriteHasDefaults) {
+        return [];
+    }
+    return [
+        item(migration, "safe_pending", relativeConfigPath, "Harness config needs current package metadata, schema version or managed-file defaults.")
+    ];
+}
 async function migrateConfig(projectRoot, root, report) {
     const relativeConfigPath = await harnessConfigPath(projectRoot);
     const configPath = path.join(projectRoot, relativeConfigPath);
@@ -147,6 +340,52 @@ async function migrateConfig(projectRoot, root, report) {
         report.skipped.push(relativeConfigPath);
     }
 }
+async function detectDeprecatedSkillOverrides(projectRoot, root, migration) {
+    const overrideRoot = path.join(projectRoot, root, "pjsdlc_managed", "override_skills");
+    if (!(await pathExists(overrideRoot))) {
+        return [];
+    }
+    const deprecatedFiles = (await listFiles(overrideRoot))
+        .filter((file) => path.basename(file) !== ".gitkeep")
+        .map((file) => path.relative(projectRoot, file).split(path.sep).join("/"))
+        .sort();
+    return deprecatedFiles.map((file) => item(migration, "manual_required", file, "Skill overrides are no longer supported; move rules into a standalone project-local Skill before relying on sync."));
+}
+async function ambiguousAreaContextFiles(projectRoot) {
+    const areasRoot = path.join(projectRoot, "project_context", "areas");
+    const areaFiles = (await listFiles(areasRoot)).filter((file) => file.endsWith(".md")).sort();
+    const ambiguous = [];
+    for (const file of areaFiles) {
+        const relativeToAreas = path.relative(areasRoot, file).split(path.sep).join("/");
+        if (!relativeToAreas.includes("/")) {
+            continue;
+        }
+        if (inferredRoleContext(relativeToAreas)) {
+            continue;
+        }
+        const base = path.basename(relativeToAreas, ".md").toLowerCase();
+        if (base === "readme" || base === "index") {
+            continue;
+        }
+        ambiguous.push(`project_context/areas/${relativeToAreas}`);
+    }
+    return ambiguous;
+}
+function item(migrationId, status, pathLabel, message) {
+    const migration = migrations.find((entry) => entry.id === migrationId);
+    if (!migration) {
+        throw new Error(`Unknown migration id: ${migrationId}`);
+    }
+    return {
+        id: migration.id,
+        introducedIn: migration.introducedIn,
+        description: migration.description,
+        scope: migration.scope,
+        status,
+        path: pathLabel,
+        message
+    };
+}
 function hasHeading(content, heading) {
     const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     return new RegExp(`^##\\s+${escaped}\\s*$`, "im").test(content);
@@ -156,6 +395,16 @@ function rewriteLegacyModuleReferences(content) {
         .replace(/project_context\/modules\//g, "project_context/areas/")
         .replace(/\(modules\//g, "(areas/");
 }
+function inferredRoleContext(relativeToAreas) {
+    const normalized = relativeToAreas.toLowerCase();
+    if (normalized.endsWith("/verification.md") || normalized === "verification.md") {
+        return "verification";
+    }
+    if (normalized.endsWith("/deployment.md") || normalized === "deployment.md") {
+        return "deployment";
+    }
+    return undefined;
+}
 function ensureManifestDefaultArea(content) {
     if (/^\s*default\s*=\s*true\s*$/im.test(content)) {
         return content;

package/dist/lib/sync-engine.d.ts

@@ -3,5 +3,8 @@ export interface SyncReport {
     skipped: string[];
     blocked: string[];
 }
+export interface SyncOptions {
+    allowPendingMigrations?: boolean;
+}
 export declare function emptySyncReport(): SyncReport;
-export declare function runSync(projectRoot: string): Promise<SyncReport>;
+export declare function runSync(projectRoot: string, options?: SyncOptions): Promise<SyncReport>;

package/dist/lib/sync-engine.js

@@ -6,6 +6,7 @@ import { copyTree, listFiles, pathExists, readText, writeTextIfChanged } from ".
 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 { assertSupportedSchema } from "./schema-guard.js";
+import { createUpgradePlan, formatUpgradePlan, hasUpgradePlanWork } from "./migrations.js";
 export function emptySyncReport() {
     return {
         changed: [],
@@ -13,11 +14,18 @@ export function emptySyncReport() {
         blocked: []
     };
 }
-export async function runSync(projectRoot) {
+export async function runSync(projectRoot, options = {}) {
     await assertSupportedSchema(projectRoot, "sync");
     const root = await harnessRoot(projectRoot);
     const config = await readConfig(projectRoot);
     const report = emptySyncReport();
+    if (!options.allowPendingMigrations) {
+        const upgradePlan = await createUpgradePlan(projectRoot);
+        if (hasUpgradePlanWork(upgradePlan)) {
+            report.blocked.push(`upgrade required before sync: ${formatUpgradePlan(upgradePlan).join(" | ")}`);
+            return report;
+        }
+    }
     await blockDeprecatedSkillOverrides(projectRoot, root, report);
     if (report.blocked.length > 0) {
         return report;

package/dist/lib/upgrade.js

@@ -1,20 +1,30 @@
 import { runDoctor } from "./doctor.js";
-import { runMigrations } from "./migrations.js";
+import { formatUpgradePlan, runMigrations } from "./migrations.js";
 import { assertSupportedSchema } from "./schema-guard.js";
 import { runSync } from "./sync-engine.js";
 export async function runUpgrade(projectRoot) {
     const lines = [];
     await assertSupportedSchema(projectRoot, "upgrade");
     const migrationReport = await runMigrations(projectRoot);
-    lines.push(`migrations changed=${migrationReport.changed.length} skipped=${migrationReport.skipped.length}`);
-    const syncReport = await runSync(projectRoot);
+    lines.push(`migrations changed=${migrationReport.changed.length} skipped=${migrationReport.skipped.length} manual_required=${migrationReport.manualRequired.length} blocked=${migrationReport.blocked.length}`);
+    if (migrationReport.manualRequired.length > 0 || migrationReport.blocked.length > 0) {
+        lines.push(...formatUpgradePlan({
+            safe_pending: [],
+            manual_required: migrationReport.manualRequired,
+            blocked: migrationReport.blocked
+        }).slice(1));
+    }
+    const syncReport = await runSync(projectRoot, { allowPendingMigrations: true });
     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) {
+    if (migrationReport.manualRequired.length > 0 ||
+        migrationReport.blocked.length > 0 ||
+        syncReport.blocked.length > 0 ||
+        doctor.errors.length > 0) {
         throw new Error("upgrade completed with blockers");
     }
     return lines;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-tiny-context-harness",
-  "version": "0.2.48",
+  "version": "0.2.50",
   "description": "Minimal project memory and validation harness for AI coding agents.",
   "license": "MIT",
   "author": "Seven128",