project-tiny-context-harness 0.2.52 → 0.2.54

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.52.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.54.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, 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.
+`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`, `validate-code-modularity` or the composite `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
 
@@ -230,16 +230,48 @@ Use `npx --no-install sdlc-harness ...` only when you explicitly want the alread
 | 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]` | Reports selected handwritten source files over the physical line-count limit; `--file <path>` and `--base <ref>` select explicit files or branch changes, and config waivers are reported distinctly. |
+| Code modularity validation | `make validate-code-modularity` | Hard gate for touched handwritten source modularity; CI can set `SDLC_MODULARITY_BASE=<ref>` to audit PR/base changes. |
+| Harness validation | `make validate-harness` | Composite gate for `validate-context` and `validate-code-modularity`. |
+| 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.
+
+`sdlc-harness check-modularity` supports that field by auditing selected handwritten source files for physical line-count risk. It is warning-only by default as a report command, while `validate-code-modularity` and `validate-harness` run it as a hard gate. The gate is not `validate-context`: `validate-context` remains pure Context recoverability. When `policy` is `scoped_waivers`, over-limit exceptions must be backed by `<harnessRoot>/config.yaml` `modularity.waivers` entries with `path`, narrow `category`, `reason` and `future_split_boundary`; handoff prose alone is not a machine waiver.
+
+### Modularity Policy
+
+Newly generated Harness configs default to `strict_except_generated`, which enforces the touched/PR handwritten source limit without legacy waivers:
+
+```yaml
+modularity:
+  limit: 300
+  policy: strict_except_generated
+```
+
+Generated and non-source files are still auto-skipped when they match existing lock/build/dist/path exclusions or generated-file headers such as `@generated` / `Code generated ... DO NOT EDIT`. `strict_except_generated` does not allow `modularity.waivers`; any configured waiver fails the modularity gate.
+
+Use `scoped_waivers` when a small number of legacy exceptions must be explicit and time-bounded:
+
+```yaml
+modularity:
+  limit: 300
+  policy: scoped_waivers
+  waivers:
+    - path: src/legacy/big-file.ts
+      category: legacy_migration
+      reason: "Existing legacy module exceeds the hard source size bound."
+      future_split_boundary: "Extract provider adapters and retry policy."
+```
+
+Omitting `policy` behaves the same as `scoped_waivers` for compatibility with existing projects. Allowed waiver categories are `generated`, `third_party_reference`, `legacy_migration`, `aggregate_styles` and `fixture_snapshot`.
 
 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.
 
@@ -382,7 +414,7 @@ Do not customize the package-managed Harness upgrade Skill directly. Project-spe
 
 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:
 
@@ -398,7 +430,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:
 
@@ -406,7 +438,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.
 
@@ -415,9 +447,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
@@ -425,11 +459,12 @@ npx --yes --package project-tiny-context-harness@latest sdlc-harness upgrade --c
 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
-```
-
-`make validate-harness` is a compatibility alias for `validate-context` in vNext projects.
+make validate-context
+make validate-code-modularity
+make validate-harness
+```
+
+`make validate-harness` runs `validate-context` and the hard touched-source modularity gate.
 
 ## Current Boundary
 

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.52.tgz
+npm install -D /path/to/project-tiny-context-harness/tmp/sdlc/source-preview/package/project-tiny-context-harness-0.2.54.tgz
 npx --no-install sdlc-harness init --adopt
 make validate-context
 ```
@@ -236,7 +236,7 @@ npx --yes --package project-tiny-context-harness@latest sdlc-harness init --adop
 - a root `Makefile` include block
 - `.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.
+The generated workflow runs only the selected Harness gate: `validate-context`, `validate-code-modularity` or the composite `validate-harness`. Maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects.
 
 `init` does not create lifecycle state, plan state, stage skills or stage work-product trees by default.
 
@@ -268,9 +268,38 @@ The default Skills are Minimal Context helpers for explicit product-planning, UI
 
 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 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.
+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 as a report command, while `validate-code-modularity` and `validate-harness` run it as a hard gate. The gate is not `validate-context`: `validate-context` remains pure Context recoverability. When `policy` is `scoped_waivers`, over-limit exceptions must be backed by `<harnessRoot>/config.yaml` `modularity.waivers` entries with `path`, narrow `category`, `reason` and `future_split_boundary`; handoff prose alone is not a machine waiver.
+
+### Modularity Policy
+
+Newly generated Harness configs default to `strict_except_generated`, which enforces the touched/PR handwritten source limit without legacy waivers:
+
+```yaml
+modularity:
+  limit: 300
+  policy: strict_except_generated
+```
+
+Generated and non-source files are still auto-skipped when they match existing lock/build/dist/path exclusions or generated-file headers such as `@generated` / `Code generated ... DO NOT EDIT`. `strict_except_generated` does not allow `modularity.waivers`; any configured waiver fails the modularity gate.
+
+Use `scoped_waivers` when a small number of legacy exceptions must be explicit and time-bounded:
+
+```yaml
+modularity:
+  limit: 300
+  policy: scoped_waivers
+  waivers:
+    - path: src/legacy/big-file.ts
+      category: legacy_migration
+      reason: "Existing legacy module exceeds the hard source size bound."
+      future_split_boundary: "Extract provider adapters and retry policy."
+```
+
+Omitting `policy` behaves the same as `scoped_waivers` for compatibility with existing projects. Allowed waiver categories are `generated`, `third_party_reference`, `legacy_migration`, `aggregate_styles` and `fixture_snapshot`.
+
+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.
 
 For Web pages, frontend layout, UI/UX, product module boundaries or decisions about where information belongs, agents should run a lightweight page product-positioning check before deciding whether the change is context-first. The check asks what judgment the user needs to make on the page, what information/actions/feedback the product must provide, what should not be persistent, what belongs in downstream consumption, ops, detail or another page, and whether layout and information density match the page task. If ownership is unclear, inspect the relevant pages and Context first. The check is input to change classification: it does not by itself require a Context update, new document chain or validator gate.
 
@@ -292,14 +321,16 @@ 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]` | Reports selected handwritten source files over the physical line-count limit; `--file <path>` and `--base <ref>` select explicit files or branch changes, and config waivers are reported distinctly. |
 | `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. |
+| `make validate-context` | Makefile wrapper for `validate-context`. |
+| `make validate-code-modularity` | Hard gate for touched handwritten source modularity; CI can set `SDLC_MODULARITY_BASE=<ref>` to audit PR/base changes. |
+| `make validate-harness` | Composite gate for `validate-context` and `validate-code-modularity`. |
 | `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. |
 
@@ -327,9 +358,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:
 
@@ -337,7 +368,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/**`。

package/assets/github/harness.yml

@@ -14,14 +14,17 @@ on:
         default: "validate-context"
         type: choice
         options:
-          - validate-context
-          - validate-harness
-
-jobs:
-  harness:
-    runs-on: ubuntu-latest
-    steps:
+          - validate-context
+          - validate-code-modularity
+          - validate-harness
+
+jobs:
+  harness:
+    runs-on: ubuntu-latest
+    steps:
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v6
         with:
           node-version: "24"
@@ -33,5 +36,6 @@ jobs:
       - name: Run harness gate
         run: make "${HARNESS_GATE}"
         env:
-          HARNESS_GATE: ${{ github.event.inputs.gate || 'validate-context' }}
-# pjsdlc:sdlc-harness:github-workflow:end
+          HARNESS_GATE: ${{ github.event.inputs.gate || 'validate-harness' }}
+          SDLC_MODULARITY_BASE: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || github.event.before || '' }}
+# pjsdlc:sdlc-harness:github-workflow:end

package/assets/make/sdlc-harness.mk

@@ -1,15 +1,18 @@
 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
-
+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)
+SDLC_MODULARITY_SCOPE = $(if $(SDLC_MODULARITY_BASE),--base $(SDLC_MODULARITY_BASE),--touched)
+
+.PHONY: help sdlc-doctor sdlc-sync sdlc-upgrade sdlc-check-modularity validate-context validate-code-modularity 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 validate-code-modularity  Fail on oversized touched handwritten source files"
+	@echo "  make validate-harness    Run validate-context and validate-code-modularity"
 	@echo "  make test-all            Run the project regression suite after replacing this placeholder"
 
 sdlc-doctor:
@@ -18,13 +21,19 @@ sdlc-doctor:
 sdlc-sync:
 	$(SDLC_HARNESS) sync
 
-sdlc-upgrade:
-	$(SDLC_HARNESS) upgrade
-
-validate-context:
-	$(SDLC_HARNESS) validate-context
-
-validate-harness: validate-context
+sdlc-upgrade:
+	$(SDLC_HARNESS) upgrade
+
+sdlc-check-modularity:
+	$(SDLC_HARNESS) check-modularity $(SDLC_MODULARITY_SCOPE)
+
+validate-context:
+	$(SDLC_HARNESS) validate-context
+
+validate-code-modularity:
+	$(SDLC_HARNESS) check-modularity $(SDLC_MODULARITY_SCOPE) --fail-on-warning
+
+validate-harness: validate-context validate-code-modularity
 
 lint:
 	@echo "No project lint command configured yet. Replace this target with your stack-specific lint command."

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` 审计计划编辑文件，用 `make validate-code-modularity` 或 `sdlc-harness check-modularity --touched --limit 300 --fail-on-warning` 做交付前硬审计。若项目本地 Skill 定义了不同 limit，使用项目本地值。
+   - 发现超限 touched file 后，不只记录行数；判断本次是否在该文件加入新职责，并回到本节拆分原则选择产品面、hook、model、adapter、component、service / facade 或 verification helper 等边界。避免只按行数机械拆分、但耦合和职责仍留在原处。
+   - 如果本次不拆，`Modularity Check` 取 `exception`，必须有 `<harnessRoot>/config.yaml` 的 `modularity.waivers` 记录（`path`、收窄 `category`、`reason`、`future_split_boundary`）；交付说明只能补充说明，不是机器豁免。若项目设置 `modularity.policy: strict_except_generated`，legacy waiver 不可用，超限手写源码必须拆分或停止触碰。已豁免历史债也不得继续塞新职责，除非本次任务就是拆分 / 迁移。
    - 查找相似实现、重复逻辑、紧耦合模块或影响面异常扩散点。
    - 当一个业务对象、能力或接口的变更需要跨多个 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`：本次触碰超限文件但暂不拆；只有默认 `modularity.policy: scoped_waivers` 允许此路径，且必须已有或同步新增 `<harnessRoot>/config.yaml` `modularity.waivers` 记录文件、收窄分类、原因和后续拆分边界。若项目设置 `modularity.policy: strict_except_generated`，不得用 legacy waiver 绕过超限手写源码，交付说明只记录本次是否新增职责以及为什么没有拆。
 - `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

@@ -35,10 +35,11 @@ When the user asks to upgrade Tiny Context / Project Tiny Context Harness in an
 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. Run diagnostics after migration-scoped follow-up:
+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`
-10. 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.
+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
 

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,145 @@
+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} waived=${report.waivedWarnings.length}`);
+        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 && file.waived ? "waived" : file.overLimit ? "over-limit" : "ok";
+            console.log(`${prefix}: ${file.relativePath} ${file.lines} lines`);
+        }
+        for (const error of report.errors) {
+            console.error(`error: ${error}`);
+        }
+        for (const warning of report.warnings) {
+            console.warn(`warning: ${warning}`);
+        }
+        for (const waiver of report.waivedWarnings) {
+            console.warn(`waived: ${waiver}`);
+        }
+        if (report.warnings.length > 0) {
+            console.warn("warning: over-limit touched files need a split or, when modularity.policy is scoped_waivers, a valid <harnessRoot>/config.yaml modularity waiver with file, reason and future split boundary.");
+        }
+        if (report.errors.length > 0 || (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.
+Generated configs default to modularity.policy: strict_except_generated; omitted policy is treated as scoped_waivers for compatibility.
+Over-limit files can be waived only through <harnessRoot>/config.yaml modularity.waivers when policy is scoped_waivers.`;
+}

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,9 +12,11 @@ export const commands = {
     sync,
     upgrade,
     doctor,
+    "check-modularity": checkModularity,
     "export-context": exportContext,
     validate,
     "validate-context": (args) => validate(["validate-context", ...args]),
+    "validate-code-modularity": (args) => validate(["validate-code-modularity", ...args]),
     "validate-harness": (args) => validate(["validate-harness", ...args]),
     package: packageSource
 };
@@ -24,11 +27,15 @@ 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]
-                       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
-  validate-harness     Compatibility alias for validate-context
+  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
+  validate-context     Validate Minimal Context fact-source recoverability
+  validate-code-modularity
+                       Enforce touched handwritten source file modularity
+  validate-harness     Run validate-context and validate-code-modularity
   package <subcommand> Maintain package canonical source`);
 }

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 };