project-tiny-context-harness 0.2.53 → 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.53.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
 
@@ -235,14 +235,43 @@ Use `npx --no-install sdlc-harness ...` only when you explicitly want the alread
 | 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`. |
-| 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. |
+| 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 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.
+`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.
 
@@ -430,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.53.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.
 
@@ -270,9 +270,36 @@ Multilingual trigger phrases are compatibility details. Public README, npm and l
 
 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.
+`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.
 
@@ -299,10 +326,11 @@ Use `npx --no-install sdlc-harness ...` only when you explicitly want the alread
 | `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 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. |
 

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,8 +1,9 @@
 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 sdlc-check-modularity 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"
@@ -10,7 +11,8 @@ help:
 	@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:
@@ -23,12 +25,15 @@ sdlc-upgrade:
 	$(SDLC_HARNESS) upgrade
 
 sdlc-check-modularity:
-	$(SDLC_HARNESS) check-modularity --touched
+	$(SDLC_HARNESS) check-modularity $(SDLC_MODULARITY_SCOPE)
 
 validate-context:
 	$(SDLC_HARNESS) validate-context
-
-validate-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,9 +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，使用项目本地值。
+   - 工程 / 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`，交付说明写 `Modularity: exception documented` 并列出文件、暂不拆原因和后续拆分边界。
+   - 如果本次不拆，`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 规则处理。
@@ -69,7 +69,7 @@ Project-specific engineering rules belong in a separate project-local Skill unde
 - 工程 / RFC / 实现类任务的 `Task Contract` 必须包含 `Modularity Check: none|required|exception`：
   - `none`：没有超限计划 / touched 手写源码文件，或本次没有向超限文件增加新职责。
   - `required`：拆分是本次验收条件，应按 abstraction / decomposition scan 的职责边界完成。
-  - `exception`：本次触碰超限文件但暂不拆；交付说明必须记录文件、原因和后续拆分边界。
+  - `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/dist/commands/check-modularity.js

@@ -23,21 +23,27 @@ export async function checkModularity(args) {
             files: parsed.files,
             limit: parsed.limit
         });
-        console.log(`check-modularity audited=${report.files.length} warning=${report.warnings.length} limit=${report.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 ? "over-limit" : "ok";
+            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 final handoff should include `Modularity: exception documented` with file, reason and future boundary.");
+            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.warnings.length > 0 && parsed.failOnWarning) {
+        if (report.errors.length > 0 || (report.warnings.length > 0 && parsed.failOnWarning)) {
             process.exitCode = 1;
         }
     }
@@ -133,5 +139,7 @@ function helpText() {
   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.`;
+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

@@ -16,6 +16,7 @@ export const commands = {
     "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
 };
@@ -30,9 +31,11 @@ export function help() {
   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
-  validate-harness     Compatibility alias for validate-context
+                       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/lib/config.js

@@ -9,6 +9,10 @@ export function defaultConfig(root) {
             package: CANONICAL_CORE_PACKAGE,
             schema_version: CURRENT_SCHEMA_VERSION
         },
+        modularity: {
+            limit: 300,
+            policy: "strict_except_generated"
+        },
         managed_files: [
             { path: "AGENTS.md", strategy: "merge-block" },
             { path: "Makefile", strategy: "merge-block" },
@@ -46,6 +50,7 @@ export function normalizeConfig(value, root = ".agent") {
             package: value.core?.package ?? fallback.core.package,
             schema_version: value.core?.schema_version ?? fallback.core.schema_version
         },
+        modularity: value.modularity,
         managed_files: value.managed_files ?? fallback.managed_files,
         never_overwrite: value.never_overwrite ?? fallback.never_overwrite
     };

package/dist/lib/modularity.d.ts

@@ -8,11 +8,20 @@ export interface ModularityFileReport {
     relativePath: string;
     lines: number;
     overLimit: boolean;
+    waived?: ModularityWaiver;
 }
 export interface ModularityCheckReport {
     limit: number;
     files: ModularityFileReport[];
     warnings: string[];
+    waivedWarnings: string[];
+    errors: string[];
+}
+export interface ModularityWaiver {
+    relativePath: string;
+    category: string;
+    reason: string;
+    futureSplitBoundary: string;
 }
 export declare function runModularityCheck(projectRoot: string, options: ModularityCheckOptions): Promise<ModularityCheckReport>;
 export declare function countPhysicalLines(content: string): number;

package/dist/lib/modularity.js

@@ -2,9 +2,13 @@ import { execFile } from "node:child_process";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
+import { readConfig } from "./config.js";
 import { shouldIncludeCodeFile, toPosix } from "./source-files.js";
 const execFileAsync = promisify(execFile);
 const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+const DEFAULT_LINE_LIMIT = 300;
+const DEFAULT_MODULARITY_POLICY = "scoped_waivers";
+const MODULARITY_POLICIES = new Set([DEFAULT_MODULARITY_POLICY, "strict_except_generated"]);
 const GENERATED_FILE_PATTERNS = [
     /^\s*(?:\/\/|#|--|;)\s*@generated\b/im,
     /^\s*(?:\/\/|#|--|;)\s*code generated .*do not edit\.?\s*$/im,
@@ -13,8 +17,18 @@ const GENERATED_FILE_PATTERNS = [
     /^\s*(?:\/\/|#|--|;)\s*this file was generated\b/im,
     /^\s*(?:\/\/|#|--|;)\s*generated by\b/im
 ];
+const WAIVER_CATEGORIES = new Set([
+    "generated",
+    "third_party_reference",
+    "legacy_migration",
+    "aggregate_styles",
+    "fixture_snapshot"
+]);
 export async function runModularityCheck(projectRoot, options) {
-    const limit = options.limit ?? 300;
+    const config = await readConfig(projectRoot);
+    const { limit: configuredLimit, waiverValues, errors: configErrors } = validateModularityConfig(config.modularity);
+    const { waivers, errors: waiverErrors } = validateWaivers(projectRoot, waiverValues);
+    const limit = options.limit ?? configuredLimit ?? DEFAULT_LINE_LIMIT;
     const candidates = new Set();
     for (const file of options.files ?? []) {
         candidates.add(normalizeExplicitPath(projectRoot, file));
@@ -39,12 +53,16 @@ export async function runModularityCheck(projectRoot, options) {
             continue;
         }
         const lines = countPhysicalLines(await fs.readFile(absolutePath, "utf8"));
-        files.push({ relativePath, lines, overLimit: lines > limit });
+        const waiver = waivers.get(relativePath);
+        files.push({ relativePath, lines, overLimit: lines > limit, waived: waiver });
     }
     const warnings = files
-        .filter((file) => file.overLimit)
+        .filter((file) => file.overLimit && !file.waived)
         .map((file) => `${file.relativePath}: ${file.lines} physical lines exceeds limit ${limit}`);
-    return { limit, files, warnings };
+    const waivedWarnings = files
+        .filter((file) => file.overLimit && file.waived)
+        .map((file) => `${file.relativePath}: ${file.lines} physical lines exceeds limit ${limit} but is waived as ${file.waived?.category}`);
+    return { limit, files, warnings, waivedWarnings, errors: [...configErrors, ...waiverErrors] };
 }
 export function countPhysicalLines(content) {
     if (content.length === 0) {
@@ -57,10 +75,19 @@ export function countPhysicalLines(content) {
     return lines.length;
 }
 async function gitTouchedFiles(projectRoot) {
-    const result = await execFileAsync("git", ["-C", projectRoot, "status", "--porcelain", "-z"], {
-        encoding: "utf8",
-        maxBuffer: GIT_MAX_BUFFER
-    });
+    let result;
+    try {
+        result = await execFileAsync("git", ["-C", projectRoot, "status", "--porcelain", "-z"], {
+            encoding: "utf8",
+            maxBuffer: GIT_MAX_BUFFER
+        });
+    }
+    catch (error) {
+        if (isNotGitRepositoryError(error)) {
+            return [];
+        }
+        throw error;
+    }
     const records = result.stdout.split("\0").filter(Boolean);
     const files = [];
     for (let index = 0; index < records.length; index += 1) {
@@ -83,6 +110,13 @@ async function gitDiffFiles(projectRoot, base) {
     });
     return result.stdout.split("\0").filter(Boolean);
 }
+function isNotGitRepositoryError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const stderr = "stderr" in error && typeof error.stderr === "string" ? error.stderr : "";
+    return /not a git repository/i.test(stderr);
+}
 function normalizeExplicitPath(projectRoot, value) {
     const absolute = path.isAbsolute(value) ? path.resolve(value) : path.resolve(projectRoot, value);
     const relative = toPosix(path.relative(projectRoot, absolute));
@@ -94,6 +128,96 @@ function normalizeExplicitPath(projectRoot, value) {
 function normalizeGitPath(value) {
     return toPosix(value).replace(/^\.\//, "");
 }
+function validateModularityConfig(modularity) {
+    const errors = [];
+    if (modularity === undefined) {
+        return { errors };
+    }
+    if (!modularity || typeof modularity !== "object" || Array.isArray(modularity)) {
+        errors.push("<harnessRoot>/config.yaml modularity must be an object");
+        return { errors };
+    }
+    const value = modularity;
+    let limit;
+    let policy = DEFAULT_MODULARITY_POLICY;
+    if (value.limit !== undefined) {
+        if (!Number.isInteger(value.limit) || Number(value.limit) <= 0) {
+            errors.push("<harnessRoot>/config.yaml modularity.limit must be a positive integer");
+        }
+        else {
+            limit = Number(value.limit);
+        }
+    }
+    if (value.policy !== undefined) {
+        if (typeof value.policy !== "string" || !MODULARITY_POLICIES.has(value.policy)) {
+            errors.push("<harnessRoot>/config.yaml modularity.policy must be one of scoped_waivers, strict_except_generated");
+        }
+        else {
+            policy = value.policy;
+        }
+    }
+    if (policy === "strict_except_generated" && value.waivers !== undefined) {
+        errors.push("<harnessRoot>/config.yaml modularity.waivers is not allowed when modularity.policy is strict_except_generated");
+    }
+    return { limit, waiverValues: policy === "scoped_waivers" ? value.waivers : undefined, errors };
+}
+function validateWaivers(projectRoot, waiverValues) {
+    const waivers = new Map();
+    const errors = [];
+    if (waiverValues === undefined) {
+        return { waivers, errors };
+    }
+    if (!Array.isArray(waiverValues)) {
+        errors.push("<harnessRoot>/config.yaml modularity.waivers must be an array");
+        return { waivers, errors };
+    }
+    for (const [index, waiver] of waiverValues.entries()) {
+        const label = `<harnessRoot>/config.yaml modularity.waivers[${index}]`;
+        if (!waiver || typeof waiver !== "object") {
+            errors.push(`${label} must be an object`);
+            continue;
+        }
+        const relativePath = requiredWaiverString(waiver, "path", label, errors);
+        const category = requiredWaiverString(waiver, "category", label, errors);
+        const reason = requiredWaiverString(waiver, "reason", label, errors);
+        const futureSplitBoundary = requiredWaiverString(waiver, "future_split_boundary", label, errors);
+        if (!relativePath || !category || !reason || !futureSplitBoundary) {
+            continue;
+        }
+        if (!WAIVER_CATEGORIES.has(category)) {
+            errors.push(`${label}.category must be one of generated, third_party_reference, legacy_migration, aggregate_styles, fixture_snapshot`);
+            continue;
+        }
+        let normalized;
+        try {
+            normalized = normalizeExplicitPath(projectRoot, relativePath);
+        }
+        catch {
+            errors.push(`${label}.path must stay inside the project root: ${relativePath}`);
+            continue;
+        }
+        const existing = waivers.get(normalized);
+        if (existing) {
+            errors.push(`${label}.path duplicates an existing modularity waiver for ${normalized}`);
+            continue;
+        }
+        waivers.set(normalized, {
+            relativePath: normalized,
+            category,
+            reason,
+            futureSplitBoundary
+        });
+    }
+    return { waivers, errors };
+}
+function requiredWaiverString(waiver, field, label, errors) {
+    const value = waiver[field];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        errors.push(`${label}.${field} must be a non-empty string`);
+        return undefined;
+    }
+    return value.trim();
+}
 async function isRegularFile(target) {
     try {
         return (await fs.stat(target)).isFile();

package/dist/lib/types.d.ts

@@ -3,9 +3,21 @@ export interface HarnessConfig {
         package: string;
         schema_version: string;
     };
+    modularity?: HarnessModularityConfig;
     managed_files: ManagedFile[];
     never_overwrite: string[];
 }
+export interface HarnessModularityConfig {
+    limit?: number;
+    policy?: "scoped_waivers" | "strict_except_generated";
+    waivers?: ModularityWaiverConfig[];
+}
+export interface ModularityWaiverConfig {
+    path?: string;
+    category?: string;
+    reason?: string;
+    future_split_boundary?: string;
+}
 export interface ManagedFile {
     path: string;
     strategy: "merge-block" | "generated" | "generated-compat" | "managed" | "merge-with-local" | "create-if-missing";

package/dist/lib/validators.js

@@ -2,10 +2,12 @@ import path from "node:path";
 import { readConfig } from "./config.js";
 import { harnessPath, harnessRoot } from "./harness-root.js";
 import { listFiles, pathExists, readText } from "./fs.js";
+import { runModularityCheck } from "./modularity.js";
 import { unsupportedSchemaMessage } from "./schema-guard.js";
 const VALIDATORS = {
     "validate-context": validateContext,
-    "validate-harness": validateContext
+    "validate-code-modularity": validateCodeModularity,
+    "validate-harness": validateHarness
 };
 const GLOBAL_REQUIRED_SECTIONS = [
     ...sectionSpecs([
@@ -71,12 +73,43 @@ export async function runValidator(projectRoot, gate) {
         return {
             info: [],
             errors: [
-                `unknown validator: ${gate}. Minimal Context Harness supports validate-context and validate-harness only.`
+                `unknown validator: ${gate}. Minimal Context Harness supports validate-context, validate-code-modularity and validate-harness only.`
             ]
         };
     }
     return validator(projectRoot);
 }
+async function validateHarness(projectRoot) {
+    const contextReport = await validateContext(projectRoot);
+    const modularityReport = await validateCodeModularity(projectRoot);
+    return {
+        info: [...contextReport.info, ...modularityReport.info],
+        errors: [...contextReport.errors, ...modularityReport.errors]
+    };
+}
+async function validateCodeModularity(projectRoot) {
+    const report = await runModularityCheck(projectRoot, { touched: true });
+    const info = [
+        `code modularity audited=${report.files.length} warning=${report.warnings.length} waived=${report.waivedWarnings.length} limit=${report.limit}`
+    ];
+    if (report.files.length === 0) {
+        info.push("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";
+        info.push(`${prefix}: ${file.relativePath} ${file.lines} lines`);
+    }
+    for (const waiver of report.waivedWarnings) {
+        info.push(`waived: ${waiver}`);
+    }
+    if (report.errors.length === 0 && report.warnings.length === 0) {
+        info.push("Code modularity validation passed");
+    }
+    return {
+        info,
+        errors: [...report.errors, ...report.warnings]
+    };
+}
 async function validateContext(projectRoot) {
     const info = [];
     const errors = [];

package/package.json

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