project-tiny-context-harness 0.2.51 → 0.2.53

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.51.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.53.tgz
 npx --no-install sdlc-harness init --adopt
 make validate-context
 ```
@@ -184,7 +184,7 @@ For existing projects:
 npx --yes --package project-tiny-context-harness@latest sdlc-harness init --adopt
 ```
 
-`init` creates `project_context/context.toml`, `project_context/global.md`, `project_context/architecture.md`, `project_context/areas/main.md`, `project_context/areas/main/verification.md`, agent guidance, Context authoring Skills, a full-project export Skill, managed templates/tools, a Makefile include and `.github/workflows/harness.yml`. The generated workflow runs only the selected Harness gate, `validate-context` or `validate-harness`; maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects. It does not create stage work-product trees, lifecycle state or stage skills by default.
+`init` creates `project_context/context.toml`, `project_context/global.md`, `project_context/architecture.md`, `project_context/areas/main.md`, `project_context/areas/main/verification.md`, agent guidance, Context authoring Skills, a full-project export Skill, a Harness upgrade Skill, managed templates/tools, a Makefile include and `.github/workflows/harness.yml`. The generated workflow runs only the selected Harness gate, `validate-context` or `validate-harness`; maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects. It does not create stage work-product trees, lifecycle state or stage skills by default.
 
 ## FAQ
 
@@ -200,7 +200,7 @@ The support assets can live in a tool-specific harness folder such as `.codex`,
 
 **Is this an English-only or Chinese-only tool?**
 
-Neither. Public docs, npm copy and launch posts are English-first so new visitors can evaluate the project quickly. Generated Skills may include multilingual trigger examples, and export defaults may use local-language filenames; those are compatibility details, not a Chinese-only product boundary.
+Neither. Public docs, npm copy, launch posts, CLI help/errors, generated Skill activation and default artifact names must be fully usable in English. Generated Skills may include multilingual trigger examples, but those examples are additive compatibility; every supported non-English trigger needs an equivalent narrow English trigger.
 
 **Does `validate-context` prove the project works?**
 
@@ -227,20 +227,26 @@ Use `npx --no-install sdlc-harness ...` only when you explicitly want the alread
 | UI/UX design Skill | `<harnessRoot>/skills/context_uiux_design/SKILL.md` | Handles explicit UI/UX design requests, writes screen/interaction conclusions to `project_context/**`, updates root `DESIGN.md` visual tokens with Google `@google/design.md`, and includes compact visual-quality calibration for product/page positioning, user needs, information density, brand/product UI and common AI-design anti-patterns. |
 | 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. |
+| Harness upgrade Skill | `<harnessRoot>/skills/context_harness_upgrade/SKILL.md` | Handles explicit Tiny Context / Project Tiny Context Harness upgrade requests such as “upgrade Tiny Context” and “use the Tiny Context upgrade skill to upgrade this project”; it runs `upgrade` first, handles only migration-scoped `manual_required` / `blocked` follow-up, then runs diagnostics. |
+| 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 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 | `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, stops before writes when `blocked` items exist, otherwise applies `safe_pending` migrations, runs `sync` and `doctor`, and exits non-zero when manual follow-up or diagnostics remain. |
 | 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`. |
-| Context validation | `npx --yes --package project-tiny-context-harness@latest sdlc-harness validate-context`, `make validate-context` | Checks required project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
+| Modularity check | `npx --yes --package project-tiny-context-harness@latest sdlc-harness check-modularity --touched [--limit 300] [--fail-on-warning]` | Warns when selected handwritten source files exceed a physical line-count limit; `--file <path>` and `--base <ref>` select explicit files or branch changes. |
+| Context validation | `npx --yes --package project-tiny-context-harness@latest sdlc-harness validate-context`, `make validate-context` | Checks required project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
 | Diagnostics | `make sdlc-doctor` or `npx --yes --package project-tiny-context-harness@latest sdlc-harness doctor` | Reports Harness root, package version, schema version and required Minimal Context paths. |
 | Package source checks | `sdlc-harness package sync-source`, `sdlc-harness package check-source` | Maintainer-only commands for keeping package canonical assets aligned with the source workspace. |
 
-For product, UI/UX and engineering tasks that touch design intent, API/Schema, state/runtime behavior, architecture boundaries or verification design, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. For module design work, the development engineer Skill also compiles `Applicable Module Design`: the relevant principles, minimal design logic and durable rationale that control the current implementation or verification choice. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, validator or gate surfaces.
+For product, UI/UX and engineering tasks that touch design intent, API/Schema, state/runtime behavior, architecture boundaries or verification design, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. For engineering, RFC and implementation work, the existing Task Contract also includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning. For module design work, the development engineer Skill also compiles `Applicable Module Design`: the relevant principles, minimal design logic and durable rationale that control the current implementation or verification choice. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, validator or gate surfaces.
 
-Multilingual trigger phrases and local-language export filenames are compatibility details. Public README, npm and launch copy stay English-first; literal non-English examples are documented only where they explain generated Skill matching or default export filenames.
+`sdlc-harness check-modularity` supports that field by auditing selected handwritten source files for physical line-count risk. It is warning-only by default and is not `validate-context`; teams that want CI enforcement can opt in with `--fail-on-warning`. The command provides file/line facts, while the agent still decides `none`, `required` or `exception` through the development engineer decomposition guidance.
+
+Multilingual trigger phrases are compatibility details. Public README, npm and launch copy stay English-first, and public/package-managed surfaces must remain English-complete; literal non-English examples are documented only where they explain generated Skill matching and must not be the sole activation path.
+
+The Harness upgrade Skill exists so consumer agents have a short, repeatable upgrade procedure for existing projects. It treats `sdlc-harness upgrade` as the default command after package updates, forbids standalone `sync` before upgrade, and limits manual handling to the migration scope reported by the CLI instead of guessing project semantics.
 
 For complex task-contract work, agents may use `plan.md` or an equivalent temporary plan surface as scratch space for `Context Delta`, `Task Contract`, implementation steps and Conformance notes. It is execution cache only: durable facts must be extracted into `project_context/**` or `DESIGN.md`, and temporary plans are not Context, not registered in `context.toml` and not default project assets.
 
@@ -369,7 +375,9 @@ mkdir -p <harnessRoot>/skills/uiux_design
 $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`.
+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`.
+
+Do not customize the package-managed Harness upgrade Skill directly. Project-specific upgrade facts belong in `project_context/**`; recurring project-local procedures belong in separate project-local Skills.
 
 ## Sync And Upgrade Boundary
 
@@ -377,7 +385,7 @@ When a project-local Skill and a package-managed default Skill both apply, agent
 
 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.
+`upgrade` first builds an upgrade plan. If `blocked` items exist, it prints the plan, runs diagnostics and exits non-zero before migrations or internal `sync`. Without blockers, it applies only `safe_pending` migrations, then runs `sync` and `doctor`. If `manual_required` follow-up or diagnostics 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:
 
@@ -393,7 +401,7 @@ Migration statuses:
 |---|---|
 | `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. |
+| `blocked` | A target conflict or overwrite risk prevents a safe write. Blocked items stop upgrade writes until resolved. |
 
 Examples:
 
@@ -401,7 +409,7 @@ Examples:
 - 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.
+- If the target already exists, the migration is `blocked`; `upgrade` stops before migrations or `sync`, and no file is overwritten.
 
 The former migration command has been removed because existing users have completed that migration path.
 
@@ -410,9 +418,11 @@ The former migration command has been removed because existing users have comple
 ```sh
 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 --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-check-modularity
+npx --yes --package project-tiny-context-harness@latest sdlc-harness check-modularity --touched
 make sdlc-sync
 make sdlc-upgrade
 npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --check

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.51.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.53.tgz
 npx --no-install sdlc-harness init --adopt
 make validate-context
 ```
@@ -225,10 +225,11 @@ npx --yes --package project-tiny-context-harness@latest sdlc-harness init --adop
 - `project_context/areas/main.md`
 - `project_context/areas/main/verification.md`
 - `<harnessRoot>/config.yaml`
-- `<harnessRoot>/skills/context_product_plan/SKILL.md`
-- `<harnessRoot>/skills/context_uiux_design/SKILL.md`
-- `<harnessRoot>/skills/context_development_engineer/SKILL.md`
-- `<harnessRoot>/skills/context_full_project_export/SKILL.md`
+- `<harnessRoot>/skills/context_product_plan/SKILL.md`
+- `<harnessRoot>/skills/context_uiux_design/SKILL.md`
+- `<harnessRoot>/skills/context_development_engineer/SKILL.md`
+- `<harnessRoot>/skills/context_full_project_export/SKILL.md`
+- `<harnessRoot>/skills/context_harness_upgrade/SKILL.md`
 - `<harnessRoot>/pjsdlc_managed/context_templates/**`
 - `<harnessRoot>/pjsdlc_managed/make/sdlc-harness.mk`
 - `tools/**`
@@ -253,7 +254,7 @@ The support assets can live in a tool-specific harness folder such as `.codex`,
 
 **Is this an English-only or Chinese-only tool?**
 
-Neither. Public docs, npm copy and launch posts are English-first so new visitors can evaluate the project quickly. Generated Skills may include multilingual trigger examples, and export defaults may use local-language filenames; those are compatibility details, not a Chinese-only product boundary.
+Neither. Public docs, npm copy, launch posts, CLI help/errors, generated Skill activation and default artifact names must be fully usable in English. Generated Skills may include multilingual trigger examples, but those examples are additive compatibility; every supported non-English trigger needs an equivalent narrow English trigger.
 
 **Does `validate-context` prove the project works?**
 
@@ -263,11 +264,13 @@ No. It checks that recovery facts exist and avoids fake test-result claims. Prod
 
 It should stay smaller than a full process. Ordinary bug fixes and local refactors do not update Context unless they produce durable product, architecture, API, state or validation facts.
 
-The default Skills are Minimal Context helpers for explicit product-planning, UI/UX-design, development-engineering and full-project-export requests. Product, screen-flow and durable engineering conclusions go to `project_context/**`; visual identity and design tokens go to root `DESIGN.md`. Export artifacts are temporary files under `tmp/sdlc/context-exports/**`, not Context.
+The default Skills are Minimal Context helpers for explicit product-planning, UI/UX-design, development-engineering, full-project-export and Tiny Context upgrade requests. Product, screen-flow and durable engineering conclusions go to `project_context/**`; visual identity and design tokens go to root `DESIGN.md`. Export artifacts are temporary files under `tmp/sdlc/context-exports/**`, not Context. The Harness upgrade Skill handles requests such as “upgrade Tiny Context” and “use the Tiny Context upgrade skill to upgrade this project” by running `upgrade` first, handling only migration-scoped follow-up, and avoiding standalone `sync` before the upgrade path.
 
-Multilingual trigger phrases and local-language export filenames are compatibility details. Public README, npm and launch copy stay English-first; literal non-English examples are documented only where they explain generated Skill matching or default export filenames.
+Multilingual trigger phrases are compatibility details. Public README, npm and launch copy stay English-first, and public/package-managed surfaces must remain English-complete; literal non-English examples are documented only where they explain generated Skill matching and must not be the sole activation path.
 
-For product, UI/UX and engineering tasks that touch design intent, API/Schema, state/runtime behavior, architecture boundaries or verification design, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. For module design work, the development engineer Skill also compiles `Applicable Module Design`: the relevant principles, minimal design logic and durable rationale that control the current implementation or verification choice. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, validator or gate surfaces.
+For product, UI/UX and engineering tasks that touch design intent, API/Schema, state/runtime behavior, architecture boundaries or verification design, the default Skills compile a short current-task contract before implementation. The contract starts with `Context Delta: none|required`; `required` preserves context-first behavior, while `none` means the task can proceed against existing Context. For engineering, RFC and implementation work, the existing Task Contract also includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning. For module design work, the development engineer Skill also compiles `Applicable Module Design`: the relevant principles, minimal design logic and durable rationale that control the current implementation or verification choice. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, validator or gate surfaces.
+
+`sdlc-harness check-modularity` supports that field by auditing selected handwritten source files for physical line-count risk. It is warning-only by default and is not `validate-context`; teams that want CI enforcement can opt in with `--fail-on-warning`. The command provides file/line facts, while the agent still decides `none`, `required` or `exception` through the development engineer decomposition guidance.
 
 For complex task-contract work, agents may use `plan.md` or an equivalent temporary plan surface as scratch space for `Context Delta`, `Task Contract`, implementation steps and Conformance notes. It is execution cache only: durable facts must be extracted into `project_context/**` or `DESIGN.md`, and temporary plans are not Context, not registered in `context.toml` and not default project assets.
 
@@ -277,7 +280,7 @@ The expected Context Priority Ladder is: read Context first, run the page produc
 
 Managed `AGENTS.md` guidance is intentionally a startup router, not a full manual. It should contain fact-source entry points, hard boundaries, key triggers and shortest validation commands; package consumers default long design reasoning to Context unless they already have a local spec/design convention. In this source workspace, `PROJECT_SPEC.md` holds stable Harness workflow rationale. Role procedures belong in Skills and human usage guidance in README. The recommended 40-70 line range is a soft budget, not a validator gate.
 
-The default `context_*` Skills are package-managed generated files. `sync` overwrites them, so project-specific product/design/development rules should live in separate project-local Skills such as `.codex/skills/product_plan/SKILL.md`, `.codex/skills/uiux_design/SKILL.md` or `.codex/skills/development_engineer/SKILL.md`. When a project-local Skill and a default Skill both apply, agents should use the more specific project-local Skill first while keeping durable conclusions in `project_context/**` and `DESIGN.md`. Keep the project-local Skill front matter `description` triggers aligned with the matching default `context_*` Skill and the project `AGENTS.md` role-trigger rule; if a project adds or narrows product/design/development keywords, update both the local Skill and the agent guidance together.
+The default `context_*` Skills are package-managed generated files. `sync` overwrites them, so project-specific product/design/development rules should live in separate project-local Skills such as `.codex/skills/product_plan/SKILL.md`, `.codex/skills/uiux_design/SKILL.md` or `.codex/skills/development_engineer/SKILL.md`. When a project-local Skill and a default Skill both apply, agents should use the more specific project-local Skill first while keeping durable conclusions in `project_context/**` and `DESIGN.md`. Keep the project-local Skill front matter `description` triggers aligned with the matching default `context_*` Skill and the project `AGENTS.md` role-trigger rule; if a project adds or narrows product/design/development keywords, update both the local Skill and the agent guidance together. The Harness upgrade Skill is also package-managed; customize project semantics in Context, not by editing that generated Skill.
 
 ## CLI Entry Safety
 
@@ -291,11 +294,12 @@ Use `npx --no-install sdlc-harness ...` only when you explicitly want the alread
 |---|---|
 | `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. |
+| `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, stops before writes when `blocked` items exist, otherwise applies `safe_pending` migrations, runs `sync` and `doctor`, and exits non-zero when manual follow-up or diagnostics remain. |
 | `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 check-modularity --touched [--limit 300] [--fail-on-warning]` | Warns when selected handwritten source files exceed a physical line-count limit; `--file <path>` and `--base <ref>` select explicit files or branch changes. |
 | `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. |
@@ -326,9 +330,9 @@ Release notes and release readiness use this update mode vocabulary:
 |---|---|
 | `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. |
+| `blocked` | A safe target cannot be written, usually because the destination already exists or another conflict would require overwriting user content. Blocked items stop upgrade writes until resolved. |
 
-`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.
+`upgrade` promises to refresh package-managed assets, apply known safe migrations when no blocked target conflict exists, 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:
 
@@ -336,7 +340,7 @@ Examples:
 - 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.
+- If `project_context/areas/main.md` already exists while `project_context/modules/main.md` still exists, the migration is `blocked`; `upgrade` stops before migrations or `sync`, and no file is overwritten.
 
 ## Minimal Context Files
 

package/assets/agents/AGENTS_CORE.md

@@ -13,7 +13,7 @@
 1. 先读 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`，再按 graph 读取相关 area / context unit。
 2. 若任务涉及 Web 页面、前端布局、UI/UX、产品模块边界或信息放置，先做页面产品定位检查，再完成变更分类；若 UI 改动涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态，按产品/UIUX Skill 的控件任务框架做轻量检查。
 3. 若任务新增、迁移或整理 Context 文件，先做 role placement scan：area 只代表产品域归属；contract / foundation / subdomain / verification / deployment / implementation-index / decision-rationale 等按读取目的拆成 role Context。
-4. 对产品方案、UI/UX、系统设计、架构边界、API / Schema、模块设计原则、状态或运行语义、验证设计等任务，先把相关模块设计上下文编译进当前任务契约；契约第一段用 `Context Delta: none|required` 声明是否改变长期事实，再写本次 Task Contract。
+4. 对产品方案、UI/UX、系统设计、架构边界、API / Schema、模块设计原则、状态或运行语义、验证设计等任务，先把相关模块设计上下文编译进当前任务契约；契约第一段用 `Context Delta: none|required` 声明是否改变长期事实，再写本次 Task Contract；工程 / RFC / 实现类 Task Contract 同时包含 `Modularity Check: none|required|exception`。
 5. `Context Delta: required` 则 context-first；普通 bug fix、局部样式、局部漂移修复、测试修复或 spike 默认 code-first，但一旦产生长期结论必须回写 Context。
 6. 收尾做 Contract Conformance 和 Context drift check，只报告 `Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；不要把一次性证据、任务契约或实现摘要写入 Context。
 
@@ -29,7 +29,7 @@
 
 1. 新会话或继续工作时，先读取 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`；按其中 default area 和触发条件读取相关 context。
 2. 第一处代码编辑前先做轻量变更分类，不按固定时长计时。若任务涉及 Web 页面、前端布局、UI/UX、产品模块边界或信息应该放在哪个页面 / 模块，先做页面产品定位检查，再完成变更分类：用户在这个页面要完成什么判断，产品必须提供哪些信息 / 动作 / 反馈，哪些信息不应常驻，哪些属于下游消费层 / 运维层 / 详情层 / 其他页面，当前布局和信息密度是否匹配页面任务。若 UI 改动涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态，按产品/UIUX Skill 的控件任务框架做轻量检查，识别既有 Context 是否适用以及是否缺少长期页面/控件契约。多页面或多模块归属不清时，先审查全站或相关页面的信息架构，再收窄到代码模块实现。该检查是判断是否需要 context-first 的输入，不等于必须更新 Context，也不要求独立文档或新的 gate。
-3. 对产品方案、UI/UX、系统设计、架构边界、API / Schema、模块设计原则、状态机或运行语义、验证设计等任务，第一处代码编辑前先编译当前任务契约：用 `Context Delta: none|required` 作为唯一正式长期事实判断点，再写本次 Task Contract，并把命中的模块设计上下文、它控制的当前选择、首选路径和 fallback / degraded path 条件写入任务契约。普通 bug fix、局部样式、小重构、局部漂移修复、测试修复或 spike 不强制编译任务契约。
+3. 对产品方案、UI/UX、系统设计、架构边界、API / Schema、模块设计原则、状态机或运行语义、验证设计等任务，第一处代码编辑前先编译当前任务契约：用 `Context Delta: none|required` 作为唯一正式长期事实判断点，再写本次 Task Contract，并把命中的模块设计上下文、它控制的当前选择、首选路径和 fallback / degraded path 条件写入任务契约；工程 / RFC / 实现类 Task Contract 还应包含 `Modularity Check: none|required|exception`。普通 bug fix、局部样式、小重构、局部漂移修复、测试修复或 spike 不强制编译任务契约。
 4. 当新增、迁移或整理 `project_context/areas/**` 时，做 role placement scan（软约束，不做 gate）：`area` / `domain` 保留产品域归属，`subdomain` 用于产品域内较小 ownership，`contract` 用于 API / schema / event / 跨域接口语义，`foundation` 用于稳定理论 / 词汇 / 背景材料，`verification` / `deployment` 用于可复用执行路径，`implementation-index` 只做代码导航索引，`decision-rationale` 记录稳定设计原因，`archive` 用于非默认读取的历史或外部材料。
 5. 若任务契约声明 `Context Delta: required`，默认走 context-first：第一处代码编辑前先更新相关 `project_context/**`，写入必要且足以指导实现的长期结论，再按 Context 和 Task Contract 对齐实现、验证和收尾。
 6. 普通 bug fix、局部样式、局部实现漂移修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期结论，继续对齐或交付前必须回写 `project_context/**`。
@@ -37,10 +37,10 @@
 8. 当代码形态、搜索结果或相邻实现与 Context 声明冲突时，把差异视为实现漂移、缺失工作或 Context 过期并显式说明；不要用当前代码形态或关键词搜索结果覆盖 Context 已声明的职责、归属或集成意图。
 9. 每个有意义的方案或实现变更收尾时做 Contract Conformance 和 Context drift check：对照 Task Contract 区分实现偏差、契约遗漏或长期事实缺失；实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。交付说明只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`；Conformance 证据属于本次交付，不写入 `project_context/**`。
 10. 长期事实只写入 `project_context/**`；不要默认创建 PRD、tech plan、ADR、implementation doc、review/test/release 文档。
-11. 用户明确要求“产品方案 / 产品经理 / 产品专家”、“设计稿 / UI/UX 设计方案 / 视觉专家”或“开发工程师 / 技术方案 / 开发方案 / 实现 / 实现方案 / 实施计划 / 技术专家 / 多开agent / subagent”这类角色或强产物名时，使用对应 Context authoring Skill，把长期结论写回 `project_context/**`。
-12. 用户明确要求“导出尽可能详细的项目全量上下文 / 全量上下文导出 / full project context export / 当前项目代码实现 / 代码级实现导出”时，使用 `context_full_project_export` Skill；默认优先运行 `sdlc-harness export-context --all` 同时生成项目级 Context 汇总和代码级实现快照；只需要单份产物时再用 `--full` 或 `--code`；导出产物只放 `tmp/sdlc/context-exports/**`，不得放入或注册到 `project_context/**` / `project_context/context.toml`。
+11. 用户明确要求“产品方案 / 产品经理 / 产品专家 / product plan / product manager / product spec”、“设计稿 / UI/UX 设计方案 / 视觉专家 / UX designer / UI designer / visual polish / design system spec”或“开发工程师 / 技术方案 / 开发方案 / 实现 / 实现方案 / 实施计划 / 技术专家 / software engineer / development plan / technical implementation plan / 多开agent / subagent”这类角色或强产物名时，使用对应 Context authoring Skill，把长期结论写回 `project_context/**`。
+12. 用户明确要求“导出尽可能详细的项目全量上下文 / 全量上下文导出 / full project context export / export full project context / 当前项目代码实现 / 代码级实现导出 / code-level implementation export”时，使用 `context_full_project_export` Skill；默认优先运行 `sdlc-harness export-context --all` 同时生成项目级 Context 汇总和代码级实现快照；只需要单份产物时再用 `--full` 或 `--code`；导出产物只放 `tmp/sdlc/context-exports/**`，不得放入或注册到 `project_context/**` / `project_context/context.toml`。用户明确要求“upgrade Tiny Context / update Tiny Context / Project Tiny Context Harness upgrade / 用 Tiny Context upgrade skill 升级这个项目 / 升级 tiny context”时，使用 `context_harness_upgrade` Skill，先走 `upgrade`，不要先单独运行 `sync`。
 13. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling，且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时，默认运行 `npx impeccable detect <target>` 做 Impeccable 视觉审查；没有可扫描目标、命令不可用或扫描失败时，说明原因并继续。Impeccable 不是 `validate-context` gate，也不替代截图检查、项目测试或人工判断。
-14. SDLC / Harness managed surfaces 是生成资产：`AGENTS.md` managed block、`.agent/pjsdlc_managed/**`、`.agent/skills/context_product_plan/**`、`.agent/skills/context_uiux_design/**`、`.agent/skills/context_development_engineer/**` 和 `.agent/skills/context_full_project_export/**` 禁止承载项目特定规则；直接编辑会在 `sync` 时被覆盖或产生漂移。项目本地产品 / UIUX / 开发规则必须新建独立 Skill，例如 `.agent/skills/product_plan/SKILL.md`、`.agent/skills/uiux_design/SKILL.md` 或 `.agent/skills/development_engineer/SKILL.md`；当项目本地 Skill 与默认 Skill 同时适用时，优先使用更具体的项目本地 Skill。项目本地 Skill 的 front matter `description` 触发词应与本文件中的角色触发规则和对应默认 `context_*` Skill 保持一致；新增或收窄关键词时，同步更新本地 Skill 描述和项目级 agent 指引，避免 Skill 触发条件与 SDLC 工作规则漂移。
+14. SDLC / Harness managed surfaces 是生成资产：`AGENTS.md` managed block、`.agent/pjsdlc_managed/**`、`.agent/skills/context_product_plan/**`、`.agent/skills/context_uiux_design/**`、`.agent/skills/context_development_engineer/**`、`.agent/skills/context_full_project_export/**` 和 `.agent/skills/context_harness_upgrade/**` 禁止承载项目特定规则；直接编辑会在 `sync` 时被覆盖或产生漂移。项目本地产品 / UIUX / 开发规则必须新建独立 Skill，例如 `.agent/skills/product_plan/SKILL.md`、`.agent/skills/uiux_design/SKILL.md` 或 `.agent/skills/development_engineer/SKILL.md`；当项目本地 Skill 与默认 Skill 同时适用时，优先使用更具体的项目本地 Skill。项目本地 Skill 的 front matter `description` 触发词应与本文件中的角色触发规则和对应默认 `context_*` Skill 保持一致；新增或收窄关键词时，同步更新本地 Skill 描述和项目级 agent 指引，避免 Skill 触发条件与 SDLC 工作规则漂移。
 15. ADR 降级为 Context 中的 `Design Rationale`；实现说明优先写成代码注释、测试名或模块 Context 中的关键约束。
 16. Harness workflow gate 只运行 `validate-context`，用于检查上下文是否可恢复；不检查 context/code 修改顺序。自动化最多提示 context-first 风险，不做阻断。
 17. 产品质量由项目自己的验证入口证明；Context 只能声明验证 / 部署关键路径，不能伪造“测试已通过”或“部署已成功”。

package/assets/make/sdlc-harness.mk

@@ -1,13 +1,14 @@
 PYTHON ?= python3
 SDLC_HARNESS ?= $(if $(wildcard packages/sdlc-harness/dist/cli.js),node packages/sdlc-harness/dist/cli.js,npx --yes --package project-tiny-context-harness@latest sdlc-harness)
 
-.PHONY: help sdlc-doctor sdlc-sync sdlc-upgrade validate-context validate-harness lint test-current-domain test-all build
+.PHONY: help sdlc-doctor sdlc-sync sdlc-upgrade sdlc-check-modularity validate-context validate-harness lint test-current-domain test-all build
 
 help:
 	@echo "Minimal Context Harness commands"
 	@echo "  make sdlc-doctor         Diagnose Harness root, core package and schema version"
 	@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 sdlc-check-modularity  Warn on oversized touched handwritten source files"
 	@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"
@@ -18,11 +19,14 @@ sdlc-doctor:
 sdlc-sync:
 	$(SDLC_HARNESS) sync
 
-sdlc-upgrade:
-	$(SDLC_HARNESS) upgrade
-
-validate-context:
-	$(SDLC_HARNESS) validate-context
+sdlc-upgrade:
+	$(SDLC_HARNESS) upgrade
+
+sdlc-check-modularity:
+	$(SDLC_HARNESS) check-modularity --touched
+
+validate-context:
+	$(SDLC_HARNESS) validate-context
 
 validate-harness: validate-context
 

package/assets/skills/context_development_engineer/SKILL.md

@@ -33,6 +33,9 @@ Project-specific engineering rules belong in a separate project-local Skill unde
 10. 实现时保持精准修改，优先遵循仓库现有框架、接口、测试和代码风格。
 11. 当用户明确要求 / 允许“多开agent”或使用 subagent，且当前会话存在可用 subagent 工具时，积极把可并行的探索、审查或实现拆分交给 subagent；使用前先复用已有相关 agent，没有合适 agent 或并行度不足时再新开。`wait_agent` 只表示取得结果，不释放资源；subagent 完成、空闲或不再需要时必须调用 `close_agent`，收尾前清理已完成 / 空闲 / 不再需要的 subagent，避免占满后续资源。
 12. 当任务涉及新实现、重构、重复逻辑、模块边界或影响面控制时，先做轻量 abstraction / decomposition scan：
+   - 工程 / RFC / 实现类 Task Contract 包含 `Modularity Check: none|required|exception`；可用 `sdlc-harness check-modularity --file <path> --limit 300` 审计计划编辑文件，用 `sdlc-harness check-modularity --touched --limit 300` 做交付前审计。若项目本地 Skill 定义了不同 limit，使用项目本地值。
+   - 发现超限 touched file 后，不只记录行数；判断本次是否在该文件加入新职责，并回到本节拆分原则选择产品面、hook、model、adapter、component、service / facade 或 verification helper 等边界。避免只按行数机械拆分、但耦合和职责仍留在原处。
+   - 如果本次不拆，`Modularity Check` 取 `exception`，交付说明写 `Modularity: exception documented` 并列出文件、暂不拆原因和后续拆分边界。
    - 查找相似实现、重复逻辑、紧耦合模块或影响面异常扩散点。
    - 当一个业务对象、能力或接口的变更需要跨多个 Context、产品域或实现层同步调整时，将该影响范围视为模块边界复核信号；优先评估是否应通过独立模块、服务、facade 或稳定接口收敛依赖，避免通过手工 manifest 长期复制实现暴露面。
    - 将候选项分为局部重构与长期边界变化，后者按既有 Context-first 规则处理。
@@ -63,6 +66,10 @@ Project-specific engineering rules belong in a separate project-local Skill unde
   - `none`：本次只是按既有 Context / 架构原则落地，不新增长期事实。
   - `required`：说明长期事实类型、应写入的 Context / role、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
 - `Task Contract` 用短列表说明 capability、owner、upstream / downstream、allowed / forbidden dependency、input / output / state / persistence、failure / retry / timeout / degraded / recovery、observability、performance、security、non-goals 和 verification path。
+- 工程 / RFC / 实现类任务的 `Task Contract` 必须包含 `Modularity Check: none|required|exception`：
+  - `none`：没有超限计划 / touched 手写源码文件，或本次没有向超限文件增加新职责。
+  - `required`：拆分是本次验收条件，应按 abstraction / decomposition scan 的职责边界完成。
+  - `exception`：本次触碰超限文件但暂不拆；交付说明必须记录文件、原因和后续拆分边界。
 - `Applicable Module Design` 是高风险任务的前置字段：列出命中的 Context / Skill 来源、适用的 Principles、Design Logic 和 Design Rationale，以及它们控制的当前实现或验证选择。
 - `Principle Decision Gate` 要写明首选执行路径、fallback / degraded path 的进入条件，以及什么证据不能证明本次目标。涉及 capability、metric 或 acceptance claim 时，先声明要证明的 claim，再选择命令或 probe。
 - 对长任务、多模块、多 agent、容易发生 `Context Delta` 调头或多轮验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。

package/assets/skills/context_harness_upgrade/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: context_harness_upgrade
+description: Use when the user asks to upgrade Tiny Context, update Tiny Context, use the Tiny Context upgrade skill to upgrade this project, upgrade project-tiny-context-harness, run sdlc-harness upgrade, run make sdlc-upgrade, Project Tiny Context Harness upgrade, 用 Tiny Context upgrade skill 升级这个项目, 升级 tiny context, 升级tiny context, or 更新 project-tiny-context-harness in a Minimal Context Harness project.
+---
+
+# Context Harness Upgrade
+
+## Package-Managed Boundary
+
+This Skill is generated by `sdlc-harness sync` and owned by the Harness package. Do not edit the generated `context_harness_upgrade` Skill directly.
+
+This Skill handles Harness package upgrade and migration orchestration only. It does not author product facts, refactor business code, replace project tests or prove application quality.
+
+## Purpose
+
+When the user asks to upgrade Tiny Context / Project Tiny Context Harness in an existing project, run the canonical upgrade path, handle only migration-scoped follow-up, and leave durable project semantics to the project Context and user-owned code.
+
+## Workflow
+
+1. Read the project routing and Context entry points before changing files:
+   - `AGENTS.md`
+   - `project_context/global.md`
+   - `project_context/architecture.md`
+   - `project_context/context.toml`
+2. Inspect the working tree with `git status --short`. Do not revert unrelated user changes.
+3. Prefer project wrappers when present:
+   - `make sdlc-upgrade`
+   - `make sdlc-doctor`
+   - `make validate-context`
+4. If no wrapper exists, use the package CLI explicitly:
+   - `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --check`
+   - `npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade`
+   - `npx --yes --package project-tiny-context-harness@latest sdlc-harness doctor`
+5. Do not run standalone `sync` before `upgrade`. `upgrade` is the default path after an npm package update because it plans migrations, applies safe migrations, refreshes managed assets and runs diagnostics.
+6. Do not run standalone `sync` after a successful `upgrade` unless release notes say the update is `sync-only`, the project wrapper did not run sync, or the user explicitly asks for a managed-asset refresh.
+7. If `upgrade --check` or `upgrade` reports only `safe_pending` items and the command succeeds, do not invent additional manual cleanup.
+8. If the report includes `manual_required` or `blocked`, handle only the listed migration scope. Use `project_context/context.toml`, role placement scan and the existing area graph to decide placement. Do not guess product or business semantics.
+9. If the report includes `blocked`, treat it as a write preflight failure: resolve the blocked migration scope and rerun `upgrade` before expecting safe migrations or managed asset sync to have been applied.
+10. Run diagnostics after migration-scoped follow-up:
+   - `make sdlc-doctor` or the CLI `doctor`
+   - `make validate-context`
+11. Report commands run, migration status, diagnostics, files changed and any remaining manual items. Use `Context: no durable project facts changed` unless the upgrade exposed or required a real long-term project fact change.
+
+## Manual Handling Rules
+
+- `manual_required` means the Harness detected a migration-scoped item but cannot safely choose the project meaning. Fix it only when the existing Context or file structure proves the intended placement.
+- `blocked` means the safe target already exists or another conflict prevents a mechanical write. Do not overwrite. Compare source and target, preserve user content and ask for direction if the conflict cannot be resolved from project facts.
+- Deprecated override Skills under `pjsdlc_managed/override_skills/**` should be migrated to standalone project-local Skills only when their content is still relevant. Do not merge them into package-managed default Skills.
+- Ambiguous Context roles should not be guessed from filenames like `api.md`, `notes.md` or `main.md` alone. Register a role only when the manifest, path convention or durable content makes it clear.
+- If `upgrade` creates default `project_context/areas/main.md` or `project_context/areas/main/verification.md` but `project_context/context.toml` already declares real project areas and does not register `main`, remove those generated defaults instead of preserving them as durable project facts. If `main` is registered or contains user-authored facts, do not delete it automatically.
+
+## Boundaries
+
+- Do not restore legacy stage workflow, sprint documents or phase gates.
+- Do not modify application code, product behavior, deployment settings or tests unless the user explicitly asks or a migration report points to a Harness-owned file in that scope.
+- Do not write one-off command output, release logs, diagnostics or temporary migration notes into `project_context/**`.
+- Do not edit package-managed generated surfaces directly in a consumer project unless the change is part of a migration conflict that cannot be resolved another way. Prefer rerunning `upgrade` / `sync` from the package source.

package/dist/commands/check-modularity.d.ts

@@ -0,0 +1 @@
+export declare function checkModularity(args: string[]): Promise<void>;

package/dist/commands/check-modularity.js

@@ -0,0 +1,137 @@
+import { runModularityCheck } from "../lib/modularity.js";
+export async function checkModularity(args) {
+    let parsed;
+    try {
+        parsed = parseArgs(args);
+    }
+    catch (error) {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (parsed.help || (!parsed.touched && !parsed.base && parsed.files.length === 0)) {
+        console.log(helpText());
+        if (!parsed.help) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    try {
+        const report = await runModularityCheck(process.cwd(), {
+            touched: parsed.touched,
+            base: parsed.base,
+            files: parsed.files,
+            limit: parsed.limit
+        });
+        console.log(`check-modularity audited=${report.files.length} warning=${report.warnings.length} limit=${report.limit}`);
+        if (report.files.length === 0) {
+            console.log("No handwritten source files matched the selected scope.");
+        }
+        for (const file of report.files) {
+            const prefix = file.overLimit ? "over-limit" : "ok";
+            console.log(`${prefix}: ${file.relativePath} ${file.lines} lines`);
+        }
+        for (const warning of report.warnings) {
+            console.warn(`warning: ${warning}`);
+        }
+        if (report.warnings.length > 0) {
+            console.warn("warning: over-limit touched files need a split, or final handoff should include `Modularity: exception documented` with file, reason and future boundary.");
+        }
+        if (report.warnings.length > 0 && parsed.failOnWarning) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}
+function parseArgs(args) {
+    const parsed = {
+        touched: false,
+        files: [],
+        limit: 300,
+        failOnWarning: false,
+        help: false
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--touched") {
+            parsed.touched = true;
+            continue;
+        }
+        if (arg === "--fail-on-warning") {
+            parsed.failOnWarning = true;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            parsed.help = true;
+            continue;
+        }
+        if (arg === "--file") {
+            const value = args[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error("check-modularity --file requires a path");
+            }
+            parsed.files.push(value);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--file=")) {
+            const value = arg.slice("--file=".length).trim();
+            if (!value) {
+                throw new Error("check-modularity --file requires a path");
+            }
+            parsed.files.push(value);
+            continue;
+        }
+        if (arg === "--base") {
+            const value = args[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error("check-modularity --base requires a ref");
+            }
+            parsed.base = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--base=")) {
+            const value = arg.slice("--base=".length).trim();
+            if (!value) {
+                throw new Error("check-modularity --base requires a ref");
+            }
+            parsed.base = value;
+            continue;
+        }
+        if (arg === "--limit") {
+            const value = args[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error("check-modularity --limit requires a positive integer");
+            }
+            parsed.limit = parseLimit(value);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--limit=")) {
+            parsed.limit = parseLimit(arg.slice("--limit=".length));
+            continue;
+        }
+        throw new Error(`unknown check-modularity argument: ${arg}`);
+    }
+    return parsed;
+}
+function parseLimit(value) {
+    const limit = Number.parseInt(value, 10);
+    if (!Number.isInteger(limit) || limit <= 0 || String(limit) !== value.trim()) {
+        throw new Error("check-modularity --limit requires a positive integer");
+    }
+    return limit;
+}
+function helpText() {
+    return `sdlc-harness check-modularity:
+  check-modularity --touched [--limit 300] [--fail-on-warning]
+  check-modularity --file <path> [--file <path> ...] [--limit 300] [--fail-on-warning]
+  check-modularity --base <ref> [--limit 300] [--fail-on-warning]
+
+Audits selected handwritten source files for physical line-count risk.
+The default is warning-only; --fail-on-warning lets projects opt into CI enforcement.`;
+}

package/dist/commands/index.js

@@ -1,3 +1,4 @@
+import { checkModularity } from "./check-modularity.js";
 import { doctor } from "./doctor.js";
 import { exportContext } from "./export-context.js";
 import { init } from "./init.js";
@@ -11,6 +12,7 @@ export const commands = {
     sync,
     upgrade,
     doctor,
+    "check-modularity": checkModularity,
     "export-context": exportContext,
     validate,
     "validate-context": (args) => validate(["validate-context", ...args]),
@@ -24,8 +26,10 @@ export function help() {
   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]
+  doctor               Diagnose project configuration and drift
+  check-modularity --touched|--file <path>|--base <ref> [--limit 300] [--fail-on-warning]
+                       Warn when selected handwritten source files exceed a line-count limit
+  export-context --full|--code|--all [--output <path>] [--check]
                        Export a temporary Context summary or code implementation Markdown artifact
   validate <gate>      Run a Harness validation gate (Minimal Context only)
   validate-context     Validate Minimal Context fact-source recoverability

package/dist/commands/upgrade.js

@@ -1,5 +1,5 @@
 import { createUpgradePlan, formatUpgradePlan, hasUpgradePlanWork, updateModeForPlan } from "../lib/migrations.js";
-import { runUpgrade } from "../lib/upgrade.js";
+import { runUpgradeReport } from "../lib/upgrade.js";
 export async function upgrade(args = []) {
     const options = parseArgs(args);
     if (options.help) {
@@ -21,14 +21,20 @@ export async function upgrade(args = []) {
         }
         return;
     }
-    const report = await runUpgrade(process.cwd());
+    const report = await runUpgradeReport(process.cwd());
     if (options.json) {
-        console.log(JSON.stringify({ lines: report }, null, 2));
+        console.log(JSON.stringify(report, null, 2));
+        if (report.blocked) {
+            process.exitCode = 1;
+        }
         return;
     }
-    for (const line of report) {
+    for (const line of report.lines) {
         console.log(line);
     }
+    if (report.blocked) {
+        process.exitCode = 1;
+    }
 }
 function parseArgs(args) {
     const options = { check: false, json: false, help: false };

package/dist/lib/context-export.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { promisify } from "node:util";
 import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { harnessRoot } from "./harness-root.js";
+import { SAFE_EXAMPLE_FILE_NAMES, shouldExcludeRelativePath, shouldIncludeCodeFile, toPosix } from "./source-files.js";
 const execFileAsync = promisify(execFile);
 const EXPORT_HEADER = "Export artifact. Do not reference from project_context/context.toml.";
 const DEFAULT_EXPORT_DIR = "tmp/sdlc/context-exports";
@@ -13,91 +14,6 @@ const MAX_TREE_ENTRIES = 300;
 const MAX_TREE_DEPTH = 4;
 const GIT_LS_MAX_BUFFER = 64 * 1024 * 1024;
 const APPROX_TEXT_TOKEN_LIMIT_CHARS = 8_000_000;
-const EXCLUDED_DIR_NAMES = new Set([
-    ".git",
-    ".artifacts",
-    ".cache",
-    ".next",
-    ".nuxt",
-    ".runtime",
-    ".turbo",
-    "artifacts",
-    "build",
-    "cache",
-    "captures",
-    "coverage",
-    "dist",
-    "logs",
-    "node_modules",
-    "out",
-    "playwright-report",
-    "raw-captures",
-    "reports",
-    "target",
-    "temp",
-    "test-reports",
-    "test-results",
-    "tmp"
-]);
-const SAFE_EXAMPLE_FILE_NAMES = new Set([".env.example", ".env.sample", ".env.template", "example.env", "sample.env"]);
-const EXCLUDED_FILE_PATTERNS = [
-    /^\.env(?:\.|$)/i,
-    /\.log$/i,
-    /\.min\.(?:css|js|mjs)$/i,
-    /(^|[-_.])(secret|secrets|cookie|cookies|credential|credentials|api-key|apikey|access-token|refresh-token|auth-token|private-key)([-_.]|$)/i,
-    /(^|[-_.])(raw-capture|capture-dump|licensed-payload|license-payload|test-report)([-_.]|$)/i,
-    /^(?:package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|poetry\.lock|pipfile\.lock|cargo\.lock)$/i,
-    /full-project-context-\d{8}T\d{6}Z\.md$/i,
-    /当前项目context-\d{8}T\d{6}Z\.md$/i,
-    /当前项目代码实现\.md$/i,
-    /(^|[-_.])(code-level-implementation|context-export|context-bundle)([-_.]|$)/i
-];
-const CODE_FILE_EXTENSIONS = [
-    ".bat",
-    ".cjs",
-    ".cmd",
-    ".go",
-    ".gql",
-    ".graphql",
-    ".js",
-    ".jsx",
-    ".jsonc",
-    ".mjs",
-    ".proto",
-    ".ps1",
-    ".py",
-    ".sh",
-    ".sql",
-    ".toml",
-    ".ts",
-    ".tsx",
-    ".vue",
-    ".yaml",
-    ".yml"
-];
-const CODE_FILE_BASE_NAMES = new Set([
-    ".env.example",
-    ".env.sample",
-    ".env.template",
-    "dockerfile",
-    "makefile",
-    "package.json",
-    "pyproject.toml",
-    "requirements.txt",
-    "setup.cfg",
-    "tsconfig.json"
-]);
-const CONFIG_JSON_NAMES = new Set([
-    "babel.config.json",
-    "biome.json",
-    "composer.json",
-    "deno.json",
-    "eslint.config.json",
-    "jsconfig.json",
-    "package.json",
-    "tsconfig.json",
-    "vite.config.json"
-]);
 const SENSITIVE_ASSIGNMENT_PATTERN = /^(\s*(?:[-*]\s*)?(?:[`"']?[\w.-]*(?:secret|token|cookie|password|api[_-]?key)[\w.-]*[`"']?\s*[:=]\s*))(.+?)\s*$/i;
 export async function runExportContext(projectRoot, options = {}) {
     const requestedModeCount = Number(options.full === true) + Number(options.code === true);
@@ -519,55 +435,6 @@ function buildImplementationGuide(records) {
         "- This file is a temporary implementation snapshot, not durable Context; durable project facts still belong in project_context/**."
     ].join("\n");
 }
-function shouldIncludeCodeFile(relative) {
-    if (shouldExcludeRelativePath(relative)) {
-        return false;
-    }
-    const normalized = toPosix(relative);
-    const lower = normalized.toLowerCase();
-    const base = path.posix.basename(lower);
-    if (CODE_FILE_BASE_NAMES.has(base) || base.startsWith("dockerfile.")) {
-        return true;
-    }
-    if (lower.endsWith(".dockerfile")) {
-        return true;
-    }
-    if (lower.endsWith(".json")) {
-        return isConfigJson(lower);
-    }
-    return CODE_FILE_EXTENSIONS.some((extension) => lower.endsWith(extension));
-}
-function shouldExcludeRelativePath(relative) {
-    const normalized = toPosix(relative);
-    const segments = normalized.split("/");
-    if (segments.some((segment) => EXCLUDED_DIR_NAMES.has(segment))) {
-        return true;
-    }
-    const base = segments[segments.length - 1] ?? "";
-    const lowerBase = base.toLowerCase();
-    return EXCLUDED_FILE_PATTERNS.some((pattern) => {
-        if (SAFE_EXAMPLE_FILE_NAMES.has(lowerBase) && pattern.source.startsWith("^\\.env")) {
-            return false;
-        }
-        return pattern.test(base) || pattern.test(normalized);
-    });
-}
-function isConfigJson(lowerRelative) {
-    const base = path.posix.basename(lowerRelative);
-    return (CONFIG_JSON_NAMES.has(base) ||
-        lowerRelative.endsWith(".schema.json") ||
-        lowerRelative.includes("/schema/") ||
-        lowerRelative.includes("/schemas/") ||
-        lowerRelative.includes("/config/") ||
-        lowerRelative.includes("/configs/") ||
-        lowerRelative.includes("/examples/") ||
-        lowerRelative.includes("/sample/") ||
-        lowerRelative.includes("/samples/") ||
-        base.includes("config") ||
-        base.includes("schema") ||
-        base.includes("example") ||
-        base.includes("sample"));
-}
 function summarizeCodeFile(relative, content, language) {
     const lower = relative.toLowerCase();
     const base = path.posix.basename(relative);
@@ -837,9 +704,6 @@ function timestampForFile(now) {
 function repoRelative(root, file) {
     return toPosix(path.relative(root, file));
 }
-function toPosix(value) {
-    return value.replace(/\\/g, "/");
-}
 function escapeTableCell(value) {
     return value.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
 }

package/dist/lib/migrations.d.ts

@@ -36,4 +36,4 @@ export declare function createUpgradePlan(projectRoot: string): Promise<UpgradeP
 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>;
+export declare function runMigrations(projectRoot: string, existingPlan?: UpgradePlan): Promise<MigrationReport>;

package/dist/lib/migrations.js

@@ -112,12 +112,15 @@ export function formatUpgradePlan(plan) {
     }
     return lines;
 }
-export async function runMigrations(projectRoot) {
+export async function runMigrations(projectRoot, existingPlan) {
     const report = { changed: [], skipped: [], manualRequired: [], blocked: [] };
     const root = await harnessRoot(projectRoot);
-    const plan = await createUpgradePlan(projectRoot);
+    const plan = existingPlan ?? (await createUpgradePlan(projectRoot));
     report.manualRequired.push(...plan.manual_required);
     report.blocked.push(...plan.blocked);
+    if (plan.blocked.length > 0) {
+        return report;
+    }
     for (const migration of migrations) {
         if (!migration.apply) {
             continue;
@@ -137,10 +140,14 @@ async function migrateBaseProjectContext(projectRoot, report) {
     await ensureDir(path.join(projectRoot, "project_context", "areas"));
     const files = [
         ["project_context/global.md", globalContextTemplate()],
-        ["project_context/architecture.md", architectureContextTemplate()],
-        ["project_context/areas/main.md", areaContextTemplate("main")],
-        ["project_context/areas/main/verification.md", verificationContextTemplate("main")]
+        ["project_context/architecture.md", architectureContextTemplate()]
     ];
+    if (await contextManifestReferences(projectRoot, "project_context/areas/main.md")) {
+        files.push(["project_context/areas/main.md", areaContextTemplate("main")]);
+    }
+    if (await contextManifestReferences(projectRoot, "project_context/areas/main/verification.md")) {
+        files.push(["project_context/areas/main/verification.md", verificationContextTemplate("main")]);
+    }
     for (const [relative, content] of files) {
         const target = path.join(projectRoot, ...relative.split("/"));
         if (await pathExists(target)) {
@@ -155,6 +162,13 @@ async function migrateBaseProjectContext(projectRoot, report) {
         }
     }
 }
+async function contextManifestReferences(projectRoot, relative) {
+    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
+    if (!(await pathExists(manifestPath))) {
+        return true;
+    }
+    return manifestReferencesPath(await readText(manifestPath), relative);
+}
 async function detectGlobalContextSections(projectRoot, _root, migration) {
     const relative = "project_context/global.md";
     const target = path.join(projectRoot, ...relative.split("/"));
@@ -427,3 +441,7 @@ function ensureManifestDefaultArea(content) {
     lines.splice(nextTableIndex, 0, "default = true");
     return lines.join("\n");
 }
+function manifestReferencesPath(content, relative) {
+    const escaped = relative.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`^(?:\\s*)(?:context|path)\\s*=\\s*["']${escaped}["']\\s*$`, "im").test(content);
+}

package/dist/lib/modularity.d.ts

@@ -0,0 +1,18 @@
+export interface ModularityCheckOptions {
+    touched?: boolean;
+    base?: string;
+    files?: string[];
+    limit?: number;
+}
+export interface ModularityFileReport {
+    relativePath: string;
+    lines: number;
+    overLimit: boolean;
+}
+export interface ModularityCheckReport {
+    limit: number;
+    files: ModularityFileReport[];
+    warnings: string[];
+}
+export declare function runModularityCheck(projectRoot: string, options: ModularityCheckOptions): Promise<ModularityCheckReport>;
+export declare function countPhysicalLines(content: string): number;

package/dist/lib/modularity.js

@@ -0,0 +1,109 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { shouldIncludeCodeFile, toPosix } from "./source-files.js";
+const execFileAsync = promisify(execFile);
+const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+const GENERATED_FILE_PATTERNS = [
+    /^\s*(?:\/\/|#|--|;)\s*@generated\b/im,
+    /^\s*(?:\/\/|#|--|;)\s*code generated .*do not edit\.?\s*$/im,
+    /^\s*(?:\/\/|#|--|;)\s*do not edit\.?\s*$/im,
+    /^\s*(?:\/\/|#|--|;|<!--)\s*<auto-generated\b/im,
+    /^\s*(?:\/\/|#|--|;)\s*this file was generated\b/im,
+    /^\s*(?:\/\/|#|--|;)\s*generated by\b/im
+];
+export async function runModularityCheck(projectRoot, options) {
+    const limit = options.limit ?? 300;
+    const candidates = new Set();
+    for (const file of options.files ?? []) {
+        candidates.add(normalizeExplicitPath(projectRoot, file));
+    }
+    if (options.touched) {
+        for (const relative of await gitTouchedFiles(projectRoot)) {
+            candidates.add(normalizeGitPath(relative));
+        }
+    }
+    if (options.base) {
+        for (const relative of await gitDiffFiles(projectRoot, options.base)) {
+            candidates.add(normalizeGitPath(relative));
+        }
+    }
+    const files = [];
+    for (const relativePath of [...candidates].sort()) {
+        if (!shouldIncludeCodeFile(relativePath)) {
+            continue;
+        }
+        const absolutePath = path.join(projectRoot, ...relativePath.split("/"));
+        if (!(await isRegularFile(absolutePath)) || (await isLikelyGeneratedFile(absolutePath))) {
+            continue;
+        }
+        const lines = countPhysicalLines(await fs.readFile(absolutePath, "utf8"));
+        files.push({ relativePath, lines, overLimit: lines > limit });
+    }
+    const warnings = files
+        .filter((file) => file.overLimit)
+        .map((file) => `${file.relativePath}: ${file.lines} physical lines exceeds limit ${limit}`);
+    return { limit, files, warnings };
+}
+export function countPhysicalLines(content) {
+    if (content.length === 0) {
+        return 0;
+    }
+    const lines = content.split(/\r\n|\n|\r/);
+    if (lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines.length;
+}
+async function gitTouchedFiles(projectRoot) {
+    const result = await execFileAsync("git", ["-C", projectRoot, "status", "--porcelain", "-z"], {
+        encoding: "utf8",
+        maxBuffer: GIT_MAX_BUFFER
+    });
+    const records = result.stdout.split("\0").filter(Boolean);
+    const files = [];
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        const status = record.slice(0, 2);
+        const relative = record.slice(3);
+        if (relative) {
+            files.push(relative);
+        }
+        if (status.includes("R") || status.includes("C")) {
+            index += 1;
+        }
+    }
+    return files;
+}
+async function gitDiffFiles(projectRoot, base) {
+    const result = await execFileAsync("git", ["-C", projectRoot, "diff", "--name-only", "-z", base, "--"], {
+        encoding: "utf8",
+        maxBuffer: GIT_MAX_BUFFER
+    });
+    return result.stdout.split("\0").filter(Boolean);
+}
+function normalizeExplicitPath(projectRoot, value) {
+    const absolute = path.isAbsolute(value) ? path.resolve(value) : path.resolve(projectRoot, value);
+    const relative = toPosix(path.relative(projectRoot, absolute));
+    if (relative.startsWith("../") || relative === ".." || path.isAbsolute(relative)) {
+        throw new Error(`check-modularity --file must stay inside the project root: ${value}`);
+    }
+    return normalizeGitPath(relative);
+}
+function normalizeGitPath(value) {
+    return toPosix(value).replace(/^\.\//, "");
+}
+async function isRegularFile(target) {
+    try {
+        return (await fs.stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isLikelyGeneratedFile(target) {
+    const content = await fs.readFile(target, "utf8");
+    const sample = content.slice(0, 8192);
+    return GENERATED_FILE_PATTERNS.some((pattern) => pattern.test(sample));
+}

package/dist/lib/source-files.d.ts

@@ -0,0 +1,4 @@
+export declare const SAFE_EXAMPLE_FILE_NAMES: Set<string>;
+export declare function shouldIncludeCodeFile(relative: string): boolean;
+export declare function shouldExcludeRelativePath(relative: string): boolean;
+export declare function toPosix(value: string): string;

package/dist/lib/source-files.js

@@ -0,0 +1,138 @@
+import path from "node:path";
+const EXCLUDED_DIR_NAMES = new Set([
+    ".git",
+    ".artifacts",
+    ".cache",
+    ".next",
+    ".nuxt",
+    ".runtime",
+    ".turbo",
+    "artifacts",
+    "build",
+    "cache",
+    "captures",
+    "coverage",
+    "dist",
+    "logs",
+    "node_modules",
+    "out",
+    "playwright-report",
+    "raw-captures",
+    "reports",
+    "target",
+    "temp",
+    "test-reports",
+    "test-results",
+    "tmp"
+]);
+export const SAFE_EXAMPLE_FILE_NAMES = new Set([".env.example", ".env.sample", ".env.template", "example.env", "sample.env"]);
+const EXCLUDED_FILE_PATTERNS = [
+    /^\.env(?:\.|$)/i,
+    /\.log$/i,
+    /\.min\.(?:css|js|mjs)$/i,
+    /(^|[-_.])(secret|secrets|cookie|cookies|credential|credentials|api-key|apikey|access-token|refresh-token|auth-token|private-key)([-_.]|$)/i,
+    /(^|[-_.])(raw-capture|capture-dump|licensed-payload|license-payload|test-report)([-_.]|$)/i,
+    /^(?:package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|poetry\.lock|pipfile\.lock|cargo\.lock)$/i,
+    /full-project-context-\d{8}T\d{6}Z\.md$/i,
+    /当前项目context-\d{8}T\d{6}Z\.md$/i,
+    /当前项目代码实现\.md$/i,
+    /(^|[-_.])(code-level-implementation|context-export|context-bundle)([-_.]|$)/i
+];
+const CODE_FILE_EXTENSIONS = [
+    ".bat",
+    ".cjs",
+    ".cmd",
+    ".go",
+    ".gql",
+    ".graphql",
+    ".js",
+    ".jsx",
+    ".jsonc",
+    ".mjs",
+    ".proto",
+    ".ps1",
+    ".py",
+    ".sh",
+    ".sql",
+    ".toml",
+    ".ts",
+    ".tsx",
+    ".vue",
+    ".yaml",
+    ".yml"
+];
+const CODE_FILE_BASE_NAMES = new Set([
+    ".env.example",
+    ".env.sample",
+    ".env.template",
+    "dockerfile",
+    "makefile",
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "setup.cfg",
+    "tsconfig.json"
+]);
+const CONFIG_JSON_NAMES = new Set([
+    "babel.config.json",
+    "biome.json",
+    "composer.json",
+    "deno.json",
+    "eslint.config.json",
+    "jsconfig.json",
+    "package.json",
+    "tsconfig.json",
+    "vite.config.json"
+]);
+export function shouldIncludeCodeFile(relative) {
+    if (shouldExcludeRelativePath(relative)) {
+        return false;
+    }
+    const normalized = toPosix(relative);
+    const lower = normalized.toLowerCase();
+    const base = path.posix.basename(lower);
+    if (CODE_FILE_BASE_NAMES.has(base) || base.startsWith("dockerfile.")) {
+        return true;
+    }
+    if (lower.endsWith(".dockerfile")) {
+        return true;
+    }
+    if (lower.endsWith(".json")) {
+        return isConfigJson(lower);
+    }
+    return CODE_FILE_EXTENSIONS.some((extension) => lower.endsWith(extension));
+}
+export function shouldExcludeRelativePath(relative) {
+    const normalized = toPosix(relative);
+    const segments = normalized.split("/");
+    if (segments.some((segment) => EXCLUDED_DIR_NAMES.has(segment))) {
+        return true;
+    }
+    const base = segments[segments.length - 1] ?? "";
+    const lowerBase = base.toLowerCase();
+    return EXCLUDED_FILE_PATTERNS.some((pattern) => {
+        if (SAFE_EXAMPLE_FILE_NAMES.has(lowerBase) && pattern.source.startsWith("^\\.env")) {
+            return false;
+        }
+        return pattern.test(base) || pattern.test(normalized);
+    });
+}
+export function toPosix(value) {
+    return value.replace(/\\/g, "/");
+}
+function isConfigJson(lowerRelative) {
+    const base = path.posix.basename(lowerRelative);
+    return (CONFIG_JSON_NAMES.has(base) ||
+        lowerRelative.endsWith(".schema.json") ||
+        lowerRelative.includes("/schema/") ||
+        lowerRelative.includes("/schemas/") ||
+        lowerRelative.includes("/config/") ||
+        lowerRelative.includes("/configs/") ||
+        lowerRelative.includes("/examples/") ||
+        lowerRelative.includes("/sample/") ||
+        lowerRelative.includes("/samples/") ||
+        base.includes("config") ||
+        base.includes("schema") ||
+        base.includes("example") ||
+        base.includes("sample"));
+}

package/dist/lib/upgrade.d.ts

@@ -1 +1,10 @@
+export interface UpgradeRunReport {
+    lines: string[];
+    blocked: boolean;
+}
+export declare class UpgradeBlockedError extends Error {
+    readonly lines: string[];
+    constructor(lines: string[]);
+}
 export declare function runUpgrade(projectRoot: string): Promise<string[]>;
+export declare function runUpgradeReport(projectRoot: string): Promise<UpgradeRunReport>;

package/dist/lib/upgrade.js

@@ -1,11 +1,33 @@
 import { runDoctor } from "./doctor.js";
-import { formatUpgradePlan, runMigrations } from "./migrations.js";
+import { createUpgradePlan, formatUpgradePlan, runMigrations } from "./migrations.js";
 import { assertSupportedSchema } from "./schema-guard.js";
 import { runSync } from "./sync-engine.js";
+export class UpgradeBlockedError extends Error {
+    lines;
+    constructor(lines) {
+        super("upgrade completed with blockers");
+        this.lines = lines;
+    }
+}
 export async function runUpgrade(projectRoot) {
+    const report = await runUpgradeReport(projectRoot);
+    if (report.blocked) {
+        throw new UpgradeBlockedError(report.lines);
+    }
+    return report.lines;
+}
+export async function runUpgradeReport(projectRoot) {
     const lines = [];
     await assertSupportedSchema(projectRoot, "upgrade");
-    const migrationReport = await runMigrations(projectRoot);
+    const plan = await createUpgradePlan(projectRoot);
+    if (plan.blocked.length > 0) {
+        lines.push(...formatUpgradePlan(plan));
+        lines.push("upgrade blocked: resolve blocked migration items before applying safe migrations or sync.");
+        const doctor = await runDoctor(projectRoot);
+        lines.push(`doctor warnings=${doctor.warnings.length} errors=${doctor.errors.length}`);
+        return { lines, blocked: true };
+    }
+    const migrationReport = await runMigrations(projectRoot, plan);
     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({
@@ -21,11 +43,9 @@ export async function runUpgrade(projectRoot) {
     }
     const doctor = await runDoctor(projectRoot);
     lines.push(`doctor warnings=${doctor.warnings.length} errors=${doctor.errors.length}`);
-    if (migrationReport.manualRequired.length > 0 ||
+    const blocked = 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;
+        doctor.errors.length > 0;
+    return { lines, blocked };
 }

package/package.json

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