overlay-scoring-skeleton 0.1.0__tar.gz

overlay_scoring_skeleton-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shinichi Suwa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

overlay_scoring_skeleton-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: overlay-scoring-skeleton
+Version: 0.1.0
+Summary: Starter template + canonical overlay engine for rules-as-data readiness/scoring definitions: flat items with a fixed one-level id separator, safely extensible via add/strengthen overlays.
+Author: Shinichi Suwa
+License: MIT License
+        
+        Copyright (c) 2026 Shinichi Suwa
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/suwa-sh/overlay-scoring-skeleton
+Project-URL: Issues, https://github.com/suwa-sh/overlay-scoring-skeleton/issues
+Keywords: overlay,scoring,readiness,rules-as-data,extensible,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema[format-nongpl]<5.0,>=4.21
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest<10.0,>=8.0; extra == "dev"
+Dynamic: license-file
+
+# overlay-scoring-skeleton
+
+rules-as-data な **readiness / scoring 定義**を、組織ごとに**安全に拡張**するための overlay エンジンと定義スキーマの起点テンプレートです。
+
+> readiness / scoring 定義 = チェック項目・閾値・マトリクスなどを、コードではなく YAML データとして書いた評価フレームワークのことです。
+
+## 提供する価値
+
+- **拡張モデルを再実装しなくてよい**: 「項目を追加する / 閾値を厳しくする」だけを許し、既存項目の上書き・削除・緩和は機械的に拒否する overlay の仕組みが最初から入っています。組織は base 定義を fork せずに自社ルールを重ねられます。
+- **定義が壊れにくい**: 項目のグループ分けを自由なタグ命名ではなく **id の構造 (1 階層固定)** で表すため、命名ミスで表示や集計が崩れません。不正な拡張 (未宣言フィールドの変更、閾値の緩和、存在しないグループへの追加) は検証時に弾かれます。
+- **明細データを自由に持てる**: 各項目は評価に使う数値のほかに、任意の入れ子データ (RACI セル、条件分岐、参照 id など) をそのまま保持できます。エンジンはこれらを解釈せず素通しします。
+- **一貫性**: 複数の readiness/scoring OSS が同じ拡張モデル・同じ検証規則を共有できます。
+
+## データモデル
+
+定義は単一のフラットな `items` リストです。id で 1 階層のグループを表します。
+
+- `<group>` (区切り文字なし) = **グループヘッダ**。合否閾値や SLA などグループ単位の数値を持ちます。
+- `<group>.<leaf>` (区切り文字 1 個) = **リーフ**。明細フィールドと任意の入れ子データを持ちます。
+
+区切り文字は既定で `.` です (`separator` で変更可)。区切りなしのリーフ (ungrouped leaf) は許されません。
+
+```yaml
+version: 1
+name: my-framework
+separator: "."
+extension_points:
+  - {group: "L*", allow: add}                                          # L* グループにリーフを追加してよい
+  - {group: "L*", level: group, field: revise, allow: strengthen, direction: higher}
+items:
+  - {id: "L1", label: 基礎層, pass: 1.0, revise: 0.5}   # グループヘッダ (数値はここ)
+  - {id: "L1.Q1", text: 判断基準は文書化されているか, weight: 1.0}   # リーフ
+```
+
+拡張 (overlay) は `add` と `strengthen` の 2 操作だけです。
+
+```yaml
+extends: my-framework
+add:
+  - {id: "L1.Q9", text: 自社固有の追加質問, weight: 1.0}
+strengthen:
+  "L1": {revise: 0.8}   # 0.5 -> 0.8 (higher = より厳しい。緩和は拒否される)
+```
+
+## インストール
+
+ライブラリとして使う場合は PyPI から入れます。
+
+```bash
+pip install overlay-scoring-skeleton
+```
+
+導入すると、利用側は使っているエンジンのバージョンを取得できます。
+
+```python
+import overlay_scoring
+print(overlay_scoring.__version__)
+```
+
+## Quick start
+
+このリポを clone して開発・テストする場合は、依存を入れてテストを実行します。
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install ".[dev]"
+./.venv/bin/python -m pytest tests/ -q     # 26 tests
+```
+
+エンジンはライブラリとして使います。
+
+```python
+from overlay_scoring import load_yaml, apply_overlays, group_items, validate_definition
+
+base = load_yaml("definitions/example-four-layer.yaml")
+assert validate_definition(base) == []                       # base の構造整合を確認
+
+result = apply_overlays(base, ["examples/overlays/sample-four-layer.yaml"])
+if not result.ok:
+    raise SystemExit([f"{v.path}: {v.message}" for v in result.violations])
+
+groups = group_items(result.merged)                          # 順序を保ったまま group 化
+for gid, g in groups.items():
+    header, leaves = g["header"], g["leaves"]
+    ...                                                       # スコアリングは利用側で実装
+```
+
+## 想定ワークフロー (準備 → 実行 → 解釈)
+
+新しい readiness/scoring OSS を作る流れです。
+
+1. **準備 — 定義を書く**: このリポを clone し、`definitions/` に自分のフレームワークを 1 ファイル書きます。グループヘッダに閾値を、リーフに明細を置き、`extension_points` で「どのグループに追加してよいか / どの数値をどちら向きに厳格化してよいか」を宣言します。`schemas/definition.schema.json` で形を検証できます。
+2. **実行 — overlay を適用する**: 導入組織は `add` / `strengthen` だけの overlay を書きます。`apply_overlays(base, [overlay, ...])` が違反を検証しながら重ね、最初の違反で止めて `MergeResult` を返します。
+3. **解釈 — merged を読む**: `group_items(merged)` でフラットな items を「グループ → ヘッダ + リーフ」に順序保持で畳み込み、ヘッダの数値としきい値、リーフの明細を使ってスコアや判定を出します (このスコアリング部分が各リポ固有の実装です)。
+
+## 検証される拡張ルール
+
+- リーフの追加はその `<group>` プレフィックスが実在するときだけ許可 (タイプミスを検出)。
+- id 衝突・既存項目の上書き・削除は拒否。
+- `strengthen` は宣言済みの数値フィールドのみ、宣言した方向 (`higher` / `lower`) にのみ許可。緩和・非数値・宣言外フィールドは拒否。
+- 複数 overlay は順に適用し、最初に違反した overlay で停止します。
+
+## リポ構成
+
+| パス | 役割 |
+|---|---|
+| `src/overlay_scoring/overlay.py` | overlay エンジン (canonical 実装) |
+| `schemas/definition.schema.json` | 定義スキーマ |
+| `definitions/example-*.yaml` | 移行済みサンプル定義 (round-trip fixture) |
+| `examples/overlays/*.yaml` | overlay サンプル |
+| `tests/` | エンジンの全境界条件テスト |
+| `docs/01_architecture.md` | 構造 (C4) とデータモデル |
+| `docs/migration-map.md` | 既存フレームワークをこのモデルへ移す対応表 |

overlay_scoring_skeleton-0.1.0/README.md

@@ -0,0 +1,113 @@
+# overlay-scoring-skeleton
+
+rules-as-data な **readiness / scoring 定義**を、組織ごとに**安全に拡張**するための overlay エンジンと定義スキーマの起点テンプレートです。
+
+> readiness / scoring 定義 = チェック項目・閾値・マトリクスなどを、コードではなく YAML データとして書いた評価フレームワークのことです。
+
+## 提供する価値
+
+- **拡張モデルを再実装しなくてよい**: 「項目を追加する / 閾値を厳しくする」だけを許し、既存項目の上書き・削除・緩和は機械的に拒否する overlay の仕組みが最初から入っています。組織は base 定義を fork せずに自社ルールを重ねられます。
+- **定義が壊れにくい**: 項目のグループ分けを自由なタグ命名ではなく **id の構造 (1 階層固定)** で表すため、命名ミスで表示や集計が崩れません。不正な拡張 (未宣言フィールドの変更、閾値の緩和、存在しないグループへの追加) は検証時に弾かれます。
+- **明細データを自由に持てる**: 各項目は評価に使う数値のほかに、任意の入れ子データ (RACI セル、条件分岐、参照 id など) をそのまま保持できます。エンジンはこれらを解釈せず素通しします。
+- **一貫性**: 複数の readiness/scoring OSS が同じ拡張モデル・同じ検証規則を共有できます。
+
+## データモデル
+
+定義は単一のフラットな `items` リストです。id で 1 階層のグループを表します。
+
+- `<group>` (区切り文字なし) = **グループヘッダ**。合否閾値や SLA などグループ単位の数値を持ちます。
+- `<group>.<leaf>` (区切り文字 1 個) = **リーフ**。明細フィールドと任意の入れ子データを持ちます。
+
+区切り文字は既定で `.` です (`separator` で変更可)。区切りなしのリーフ (ungrouped leaf) は許されません。
+
+```yaml
+version: 1
+name: my-framework
+separator: "."
+extension_points:
+  - {group: "L*", allow: add}                                          # L* グループにリーフを追加してよい
+  - {group: "L*", level: group, field: revise, allow: strengthen, direction: higher}
+items:
+  - {id: "L1", label: 基礎層, pass: 1.0, revise: 0.5}   # グループヘッダ (数値はここ)
+  - {id: "L1.Q1", text: 判断基準は文書化されているか, weight: 1.0}   # リーフ
+```
+
+拡張 (overlay) は `add` と `strengthen` の 2 操作だけです。
+
+```yaml
+extends: my-framework
+add:
+  - {id: "L1.Q9", text: 自社固有の追加質問, weight: 1.0}
+strengthen:
+  "L1": {revise: 0.8}   # 0.5 -> 0.8 (higher = より厳しい。緩和は拒否される)
+```
+
+## インストール
+
+ライブラリとして使う場合は PyPI から入れます。
+
+```bash
+pip install overlay-scoring-skeleton
+```
+
+導入すると、利用側は使っているエンジンのバージョンを取得できます。
+
+```python
+import overlay_scoring
+print(overlay_scoring.__version__)
+```
+
+## Quick start
+
+このリポを clone して開発・テストする場合は、依存を入れてテストを実行します。
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install ".[dev]"
+./.venv/bin/python -m pytest tests/ -q     # 26 tests
+```
+
+エンジンはライブラリとして使います。
+
+```python
+from overlay_scoring import load_yaml, apply_overlays, group_items, validate_definition
+
+base = load_yaml("definitions/example-four-layer.yaml")
+assert validate_definition(base) == []                       # base の構造整合を確認
+
+result = apply_overlays(base, ["examples/overlays/sample-four-layer.yaml"])
+if not result.ok:
+    raise SystemExit([f"{v.path}: {v.message}" for v in result.violations])
+
+groups = group_items(result.merged)                          # 順序を保ったまま group 化
+for gid, g in groups.items():
+    header, leaves = g["header"], g["leaves"]
+    ...                                                       # スコアリングは利用側で実装
+```
+
+## 想定ワークフロー (準備 → 実行 → 解釈)
+
+新しい readiness/scoring OSS を作る流れです。
+
+1. **準備 — 定義を書く**: このリポを clone し、`definitions/` に自分のフレームワークを 1 ファイル書きます。グループヘッダに閾値を、リーフに明細を置き、`extension_points` で「どのグループに追加してよいか / どの数値をどちら向きに厳格化してよいか」を宣言します。`schemas/definition.schema.json` で形を検証できます。
+2. **実行 — overlay を適用する**: 導入組織は `add` / `strengthen` だけの overlay を書きます。`apply_overlays(base, [overlay, ...])` が違反を検証しながら重ね、最初の違反で止めて `MergeResult` を返します。
+3. **解釈 — merged を読む**: `group_items(merged)` でフラットな items を「グループ → ヘッダ + リーフ」に順序保持で畳み込み、ヘッダの数値としきい値、リーフの明細を使ってスコアや判定を出します (このスコアリング部分が各リポ固有の実装です)。
+
+## 検証される拡張ルール
+
+- リーフの追加はその `<group>` プレフィックスが実在するときだけ許可 (タイプミスを検出)。
+- id 衝突・既存項目の上書き・削除は拒否。
+- `strengthen` は宣言済みの数値フィールドのみ、宣言した方向 (`higher` / `lower`) にのみ許可。緩和・非数値・宣言外フィールドは拒否。
+- 複数 overlay は順に適用し、最初に違反した overlay で停止します。
+
+## リポ構成
+
+| パス | 役割 |
+|---|---|
+| `src/overlay_scoring/overlay.py` | overlay エンジン (canonical 実装) |
+| `schemas/definition.schema.json` | 定義スキーマ |
+| `definitions/example-*.yaml` | 移行済みサンプル定義 (round-trip fixture) |
+| `examples/overlays/*.yaml` | overlay サンプル |
+| `tests/` | エンジンの全境界条件テスト |
+| `docs/01_architecture.md` | 構造 (C4) とデータモデル |
+| `docs/migration-map.md` | 既存フレームワークをこのモデルへ移す対応表 |

overlay_scoring_skeleton-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "overlay-scoring-skeleton"
+version = "0.1.0"
+description = "Starter template + canonical overlay engine for rules-as-data readiness/scoring definitions: flat items with a fixed one-level id separator, safely extensible via add/strengthen overlays."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Shinichi Suwa" }]
+keywords = [
+    "overlay",
+    "scoring",
+    "readiness",
+    "rules-as-data",
+    "extensible",
+    "yaml",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    # [format-nongpl] extra brings rfc3339-validator etc so "format": "date-time"
+    # is actually validated (bare jsonschema treats it as a no-op).
+    "jsonschema[format-nongpl]>=4.21,<5.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0,<10.0"]
+
+[project.urls]
+Homepage = "https://github.com/suwa-sh/overlay-scoring-skeleton"
+Issues = "https://github.com/suwa-sh/overlay-scoring-skeleton/issues"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]

overlay_scoring_skeleton-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

overlay_scoring_skeleton-0.1.0/src/overlay_scoring/__init__.py

@@ -0,0 +1,35 @@
+"""Canonical overlay engine for readiness / scoring definitions."""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("overlay-scoring-skeleton")
+except PackageNotFoundError:  # not installed (e.g. running from a source checkout)
+    __version__ = "0.0.0.dev0"
+
+from .overlay import (
+    MergeResult,
+    MergeViolation,
+    apply_overlay,
+    apply_overlays,
+    group_items,
+    group_of,
+    is_leaf,
+    load_yaml,
+    separator_of,
+    validate_definition,
+)
+
+__all__ = [
+    "__version__",
+    "MergeResult",
+    "MergeViolation",
+    "apply_overlay",
+    "apply_overlays",
+    "group_items",
+    "group_of",
+    "is_leaf",
+    "load_yaml",
+    "separator_of",
+    "validate_definition",
+]

overlay_scoring_skeleton-0.1.0/src/overlay_scoring/overlay.py

@@ -0,0 +1,380 @@
+"""Canonical overlay engine for readiness / scoring definitions.
+
+A *definition* is a single flat ``items`` list. Every item has an ``id`` that is
+either a **group header** (no separator, e.g. ``L1``) or a **leaf**
+(exactly one separator, e.g. ``L1.Q1``). The separator (default ``.``) is fixed
+to one level: there are no ungrouped leaves and no deeper nesting.
+
+A leaf's group prefix must reference an existing header. Group headers may carry
+group-level numeric fields (thresholds, SLAs); leaves carry item fields plus any
+*opaque* nested payload (``cells`` / ``when`` / ``recommended`` / ``injects`` ...)
+that the engine never interprets.
+
+The base declares its ``extension_points``. An overlay may only:
+
+- ``add``        : append a new item (fresh ``id``) to a group the base allows.
+- ``strengthen`` : move a declared numeric field toward the stricter direction.
+
+The stricter direction is declared per field (``direction: lower`` for SLA hours,
+``direction: higher`` for pass thresholds). Everything else (overwrite, delete,
+weaken, unknown id, out-of-scope field) is a violation and rejected.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+DEFAULT_SEPARATOR = "."
+
+
+@dataclass
+class MergeViolation:
+    """A single rule-violation detected while applying an overlay."""
+
+    path: str
+    kind: str
+    message: str
+
+
+@dataclass
+class MergeResult:
+    """Outcome of applying overlays to a base definition."""
+
+    merged: dict
+    applied: list[str] = field(default_factory=list)
+    violations: list[MergeViolation] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.violations
+
+
+def load_yaml(path: str | Path) -> dict:
+    """Load a YAML file into a dict. Raises on syntax errors."""
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+# --- id helpers -------------------------------------------------------------
+
+def separator_of(defn: dict) -> str:
+    return defn.get("separator", DEFAULT_SEPARATOR)
+
+
+def is_leaf(item_id: str, sep: str) -> bool:
+    return sep in item_id
+
+
+def group_of(item_id: str, sep: str) -> str:
+    """The group a header/leaf belongs to (the header's own id, or a leaf's prefix)."""
+    return item_id.split(sep, 1)[0] if sep in item_id else item_id
+
+
+def _depth_ok(item_id: str, sep: str) -> bool:
+    """Fixed one level: an id has at most one separator."""
+    return item_id.count(sep) <= 1
+
+
+def _match_group(selector: str, group_id: str) -> bool:
+    """Group selector: exact id, prefix family ('L*'), or '*' (all)."""
+    if selector == "*":
+        return True
+    if selector.endswith("*"):
+        return group_id.startswith(selector[:-1])
+    return selector == group_id
+
+
+# --- extension points -------------------------------------------------------
+
+@dataclass
+class StrengthenSpec:
+    group_sel: str
+    on: str  # "group" | "leaf"
+    field: str
+    direction: str  # "lower" | "higher"
+
+
+def _parse_extension_points(base: dict) -> tuple[list[str], list[StrengthenSpec]]:
+    """Return (add_selectors, strengthen_specs) declared by the base."""
+    add_selectors: list[str] = []
+    strengthen_specs: list[StrengthenSpec] = []
+    for ep in base.get("extension_points", []):
+        if not isinstance(ep, dict):
+            continue
+        allow = ep.get("allow")
+        group_sel = ep.get("group", "*")
+        if allow == "add":
+            add_selectors.append(group_sel)
+        elif allow == "strengthen":
+            on = ep.get("level", "leaf")   # 'level' (not 'on'): 'on' is a YAML 1.1 boolean keyword
+            if on not in {"group", "leaf"}:
+                on = "leaf"
+            direction = ep.get("direction", "lower")
+            if direction not in {"lower", "higher"}:
+                direction = "lower"  # ambiguous -> fail safe to lower (stricter = shorter)
+            fld = ep.get("field")
+            if fld:
+                strengthen_specs.append(StrengthenSpec(group_sel, on, fld, direction))
+    return add_selectors, strengthen_specs
+
+
+# --- add --------------------------------------------------------------------
+
+def _apply_add(
+    merged: dict,
+    new_items: list,
+    add_selectors: list[str],
+    sep: str,
+    violations: list[MergeViolation],
+) -> None:
+    """Append new items in listed order. Leaf prefixes may reference headers
+    added earlier in the same overlay (base + prior adds)."""
+    if not isinstance(new_items, list):
+        violations.append(
+            MergeViolation(path="add", kind="invalid_overlay", message="'add' must be a list of items")
+        )
+        return
+    items = merged.setdefault("items", [])
+    existing_ids = {x.get("id") for x in items if isinstance(x, dict)}
+    header_ids = {x["id"] for x in items if isinstance(x, dict) and "id" in x and not is_leaf(x["id"], sep)}
+
+    for item in new_items:
+        if not isinstance(item, dict) or "id" not in item:
+            violations.append(
+                MergeViolation(path="add", kind="invalid_overlay", message="each added item needs an 'id'")
+            )
+            continue
+        new_id = item["id"]
+        if not _depth_ok(new_id, sep):
+            violations.append(
+                MergeViolation(
+                    path=f"add[{new_id}]",
+                    kind="invalid_overlay",
+                    message=f"id '{new_id}' has more than one '{sep}' (only one nesting level is allowed)",
+                )
+            )
+            continue
+        if new_id in existing_ids:
+            violations.append(
+                MergeViolation(
+                    path=f"add[{new_id}]",
+                    kind="id_collision",
+                    message=f"added id '{new_id}' collides with an existing item (overwrite is not allowed)",
+                )
+            )
+            continue
+        grp = group_of(new_id, sep)
+        if not any(_match_group(sel, grp) for sel in add_selectors):
+            violations.append(
+                MergeViolation(
+                    path=f"add[{new_id}]",
+                    kind="unsupported_op",
+                    message=f"group '{grp}' is not an add-able extension point of this definition",
+                )
+            )
+            continue
+        if is_leaf(new_id, sep) and grp not in header_ids:
+            violations.append(
+                MergeViolation(
+                    path=f"add[{new_id}]",
+                    kind="unknown_group",
+                    message=f"leaf '{new_id}' references group '{grp}' which does not exist",
+                )
+            )
+            continue
+        items.append(deepcopy(item))
+        existing_ids.add(new_id)
+        if not is_leaf(new_id, sep):
+            header_ids.add(new_id)
+
+
+# --- strengthen -------------------------------------------------------------
+
+def _strengthen_one(
+    target: dict, fld: str, new_val, direction: str, path: str
+) -> MergeViolation | None:
+    """Apply one stricter-direction field update, or return a violation.
+
+    strengthen targets are numeric. The new value must be numeric even when the
+    base value is absent, so a non-numeric value cannot slip in through an unset base.
+    """
+    try:
+        new_f = float(new_val)
+    except (TypeError, ValueError):
+        return MergeViolation(path=path, kind="invalid_overlay", message=f"strengthen value for '{fld}' must be numeric")
+    old = target.get(fld)
+    if old is None:
+        target[fld] = new_val
+        return None
+    try:
+        old_f = float(old)
+    except (TypeError, ValueError):
+        return MergeViolation(path=path, kind="invalid_overlay", message=f"base value for '{fld}' is not numeric; cannot strengthen")
+    weakened = new_f > old_f if direction == "lower" else new_f < old_f
+    if weakened:
+        return MergeViolation(
+            path=path,
+            kind="weakening_rejected",
+            message=f"strengthen would weaken '{fld}' from {old} to {new_val} (stricter direction is '{direction}')",
+        )
+    target[fld] = new_val
+    return None
+
+
+def _apply_strengthen(
+    merged: dict,
+    item_map: dict,
+    strengthen_specs: list[StrengthenSpec],
+    sep: str,
+    violations: list[MergeViolation],
+) -> None:
+    if not isinstance(item_map, dict):
+        violations.append(
+            MergeViolation(path="strengthen", kind="invalid_overlay", message="'strengthen' must be a mapping of id -> fields")
+        )
+        return
+    index = {x.get("id"): x for x in merged.get("items", []) if isinstance(x, dict)}
+    for item_id, fields in item_map.items():
+        if item_id not in index:
+            violations.append(
+                MergeViolation(path=f"strengthen[{item_id}]", kind="unknown_id", message=f"id '{item_id}' is not in the definition")
+            )
+            continue
+        if not isinstance(fields, dict):
+            violations.append(
+                MergeViolation(path=f"strengthen[{item_id}]", kind="invalid_overlay", message="strengthen target must be a mapping of field -> value")
+            )
+            continue
+        on = "leaf" if is_leaf(item_id, sep) else "group"
+        grp = group_of(item_id, sep)
+        target = index[item_id]
+        for fld, new_val in fields.items():
+            spec = next(
+                (s for s in strengthen_specs if s.on == on and s.field == fld and _match_group(s.group_sel, grp)),
+                None,
+            )
+            if spec is None:
+                violations.append(
+                    MergeViolation(
+                        path=f"strengthen[{item_id}].{fld}",
+                        kind="unsupported_op",
+                        message=f"field '{fld}' is not a declared strengthen-able {on} field for group '{grp}'",
+                    )
+                )
+                continue
+            v = _strengthen_one(target, fld, new_val, spec.direction, f"strengthen[{item_id}].{fld}")
+            if v is not None:
+                violations.append(v)
+
+
+# --- validation & apply -----------------------------------------------------
+
+def validate_definition(defn: dict) -> list[MergeViolation]:
+    """Structural checks on a base definition (independent of any overlay)."""
+    violations: list[MergeViolation] = []
+    sep = separator_of(defn)
+    items = defn.get("items", [])
+    if not isinstance(items, list):
+        return [MergeViolation(path="items", kind="invalid_definition", message="'items' must be a list")]
+    seen: set[str] = set()
+    header_ids: set[str] = set()
+    for it in items:
+        if not isinstance(it, dict) or "id" not in it:
+            violations.append(MergeViolation(path="items", kind="invalid_definition", message="each item needs an 'id'"))
+            continue
+        iid = it["id"]
+        if iid in seen:
+            violations.append(MergeViolation(path=f"items[{iid}]", kind="id_collision", message=f"duplicate id '{iid}'"))
+        seen.add(iid)
+        if not _depth_ok(iid, sep):
+            violations.append(MergeViolation(path=f"items[{iid}]", kind="invalid_definition", message=f"id '{iid}' has more than one '{sep}'"))
+        if not is_leaf(iid, sep):
+            header_ids.add(iid)
+    for it in items:
+        if isinstance(it, dict) and "id" in it and is_leaf(it["id"], sep):
+            grp = group_of(it["id"], sep)
+            if grp not in header_ids:
+                violations.append(
+                    MergeViolation(path=f"items[{it['id']}]", kind="unknown_group", message=f"leaf '{it['id']}' references missing group header '{grp}'")
+                )
+    return violations
+
+
+def apply_overlay(base: dict, overlay: dict) -> MergeResult:
+    """Apply a single overlay onto ``base`` and return the merged definition."""
+    violations: list[MergeViolation] = []
+
+    if overlay.get("extends") != base.get("name"):
+        violations.append(
+            MergeViolation(
+                path="extends",
+                kind="extends_mismatch",
+                message=f"overlay extends '{overlay.get('extends')}' does not match base name '{base.get('name')}'",
+            )
+        )
+        return MergeResult(merged=deepcopy(base), violations=violations)
+
+    sep = separator_of(base)
+    add_selectors, strengthen_specs = _parse_extension_points(base)
+    merged = deepcopy(base)
+
+    if "add" in overlay:
+        _apply_add(merged, overlay["add"], add_selectors, sep, violations)
+    if "strengthen" in overlay:
+        _apply_strengthen(merged, overlay["strengthen"], strengthen_specs, sep, violations)
+
+    for key in overlay:
+        if key in {"version", "extends", "add", "strengthen"}:
+            continue
+        violations.append(
+            MergeViolation(
+                path=key,
+                kind="unsupported_op",
+                message=f"overlay top-level key '{key}' is not supported (use add / strengthen)",
+            )
+        )
+
+    return MergeResult(merged=merged, violations=violations)
+
+
+def apply_overlays(base: dict, overlay_paths: list[str | Path]) -> MergeResult:
+    """Apply multiple overlays in order, stopping at the first that violates."""
+    current = deepcopy(base)
+    applied: list[str] = []
+    all_violations: list[MergeViolation] = []
+    for path in overlay_paths:
+        overlay = load_yaml(path)
+        result = apply_overlay(current, overlay)
+        all_violations.extend(result.violations)
+        if result.violations:
+            return MergeResult(merged=result.merged, applied=applied, violations=all_violations)
+        current = result.merged
+        applied.append(str(path))
+    return MergeResult(merged=current, applied=applied, violations=all_violations)
+
+
+# --- projection helper (for consumers) --------------------------------------
+
+def group_items(defn: dict) -> dict[str, dict]:
+    """Regroup the flat ``items`` list into an ordered {group_id: {...}} map.
+
+    Each entry is ``{"header": <header item or None>, "leaves": [<leaf items>]}``,
+    preserving source order both across groups and within each group's leaves.
+    Consumers use this instead of re-reading a nested structure.
+    """
+    sep = separator_of(defn)
+    groups: dict[str, dict] = {}
+    for it in defn.get("items", []):
+        if not isinstance(it, dict) or "id" not in it:
+            continue
+        grp = group_of(it["id"], sep)
+        g = groups.setdefault(grp, {"header": None, "leaves": []})
+        if is_leaf(it["id"], sep):
+            g["leaves"].append(it)
+        else:
+            g["header"] = it
+    return groups

overlay_scoring_skeleton-0.1.0/src/overlay_scoring_skeleton.egg-info/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: overlay-scoring-skeleton
+Version: 0.1.0
+Summary: Starter template + canonical overlay engine for rules-as-data readiness/scoring definitions: flat items with a fixed one-level id separator, safely extensible via add/strengthen overlays.
+Author: Shinichi Suwa
+License: MIT License
+        
+        Copyright (c) 2026 Shinichi Suwa
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/suwa-sh/overlay-scoring-skeleton
+Project-URL: Issues, https://github.com/suwa-sh/overlay-scoring-skeleton/issues
+Keywords: overlay,scoring,readiness,rules-as-data,extensible,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema[format-nongpl]<5.0,>=4.21
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest<10.0,>=8.0; extra == "dev"
+Dynamic: license-file
+
+# overlay-scoring-skeleton
+
+rules-as-data な **readiness / scoring 定義**を、組織ごとに**安全に拡張**するための overlay エンジンと定義スキーマの起点テンプレートです。
+
+> readiness / scoring 定義 = チェック項目・閾値・マトリクスなどを、コードではなく YAML データとして書いた評価フレームワークのことです。
+
+## 提供する価値
+
+- **拡張モデルを再実装しなくてよい**: 「項目を追加する / 閾値を厳しくする」だけを許し、既存項目の上書き・削除・緩和は機械的に拒否する overlay の仕組みが最初から入っています。組織は base 定義を fork せずに自社ルールを重ねられます。
+- **定義が壊れにくい**: 項目のグループ分けを自由なタグ命名ではなく **id の構造 (1 階層固定)** で表すため、命名ミスで表示や集計が崩れません。不正な拡張 (未宣言フィールドの変更、閾値の緩和、存在しないグループへの追加) は検証時に弾かれます。
+- **明細データを自由に持てる**: 各項目は評価に使う数値のほかに、任意の入れ子データ (RACI セル、条件分岐、参照 id など) をそのまま保持できます。エンジンはこれらを解釈せず素通しします。
+- **一貫性**: 複数の readiness/scoring OSS が同じ拡張モデル・同じ検証規則を共有できます。
+
+## データモデル
+
+定義は単一のフラットな `items` リストです。id で 1 階層のグループを表します。
+
+- `<group>` (区切り文字なし) = **グループヘッダ**。合否閾値や SLA などグループ単位の数値を持ちます。
+- `<group>.<leaf>` (区切り文字 1 個) = **リーフ**。明細フィールドと任意の入れ子データを持ちます。
+
+区切り文字は既定で `.` です (`separator` で変更可)。区切りなしのリーフ (ungrouped leaf) は許されません。
+
+```yaml
+version: 1
+name: my-framework
+separator: "."
+extension_points:
+  - {group: "L*", allow: add}                                          # L* グループにリーフを追加してよい
+  - {group: "L*", level: group, field: revise, allow: strengthen, direction: higher}
+items:
+  - {id: "L1", label: 基礎層, pass: 1.0, revise: 0.5}   # グループヘッダ (数値はここ)
+  - {id: "L1.Q1", text: 判断基準は文書化されているか, weight: 1.0}   # リーフ
+```
+
+拡張 (overlay) は `add` と `strengthen` の 2 操作だけです。
+
+```yaml
+extends: my-framework
+add:
+  - {id: "L1.Q9", text: 自社固有の追加質問, weight: 1.0}
+strengthen:
+  "L1": {revise: 0.8}   # 0.5 -> 0.8 (higher = より厳しい。緩和は拒否される)
+```
+
+## インストール
+
+ライブラリとして使う場合は PyPI から入れます。
+
+```bash
+pip install overlay-scoring-skeleton
+```
+
+導入すると、利用側は使っているエンジンのバージョンを取得できます。
+
+```python
+import overlay_scoring
+print(overlay_scoring.__version__)
+```
+
+## Quick start
+
+このリポを clone して開発・テストする場合は、依存を入れてテストを実行します。
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install ".[dev]"
+./.venv/bin/python -m pytest tests/ -q     # 26 tests
+```
+
+エンジンはライブラリとして使います。
+
+```python
+from overlay_scoring import load_yaml, apply_overlays, group_items, validate_definition
+
+base = load_yaml("definitions/example-four-layer.yaml")
+assert validate_definition(base) == []                       # base の構造整合を確認
+
+result = apply_overlays(base, ["examples/overlays/sample-four-layer.yaml"])
+if not result.ok:
+    raise SystemExit([f"{v.path}: {v.message}" for v in result.violations])
+
+groups = group_items(result.merged)                          # 順序を保ったまま group 化
+for gid, g in groups.items():
+    header, leaves = g["header"], g["leaves"]
+    ...                                                       # スコアリングは利用側で実装
+```
+
+## 想定ワークフロー (準備 → 実行 → 解釈)
+
+新しい readiness/scoring OSS を作る流れです。
+
+1. **準備 — 定義を書く**: このリポを clone し、`definitions/` に自分のフレームワークを 1 ファイル書きます。グループヘッダに閾値を、リーフに明細を置き、`extension_points` で「どのグループに追加してよいか / どの数値をどちら向きに厳格化してよいか」を宣言します。`schemas/definition.schema.json` で形を検証できます。
+2. **実行 — overlay を適用する**: 導入組織は `add` / `strengthen` だけの overlay を書きます。`apply_overlays(base, [overlay, ...])` が違反を検証しながら重ね、最初の違反で止めて `MergeResult` を返します。
+3. **解釈 — merged を読む**: `group_items(merged)` でフラットな items を「グループ → ヘッダ + リーフ」に順序保持で畳み込み、ヘッダの数値としきい値、リーフの明細を使ってスコアや判定を出します (このスコアリング部分が各リポ固有の実装です)。
+
+## 検証される拡張ルール
+
+- リーフの追加はその `<group>` プレフィックスが実在するときだけ許可 (タイプミスを検出)。
+- id 衝突・既存項目の上書き・削除は拒否。
+- `strengthen` は宣言済みの数値フィールドのみ、宣言した方向 (`higher` / `lower`) にのみ許可。緩和・非数値・宣言外フィールドは拒否。
+- 複数 overlay は順に適用し、最初に違反した overlay で停止します。
+
+## リポ構成
+
+| パス | 役割 |
+|---|---|
+| `src/overlay_scoring/overlay.py` | overlay エンジン (canonical 実装) |
+| `schemas/definition.schema.json` | 定義スキーマ |
+| `definitions/example-*.yaml` | 移行済みサンプル定義 (round-trip fixture) |
+| `examples/overlays/*.yaml` | overlay サンプル |
+| `tests/` | エンジンの全境界条件テスト |
+| `docs/01_architecture.md` | 構造 (C4) とデータモデル |
+| `docs/migration-map.md` | 既存フレームワークをこのモデルへ移す対応表 |

overlay_scoring_skeleton-0.1.0/src/overlay_scoring_skeleton.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/overlay_scoring/__init__.py
+src/overlay_scoring/overlay.py
+src/overlay_scoring_skeleton.egg-info/PKG-INFO
+src/overlay_scoring_skeleton.egg-info/SOURCES.txt
+src/overlay_scoring_skeleton.egg-info/dependency_links.txt
+src/overlay_scoring_skeleton.egg-info/requires.txt
+src/overlay_scoring_skeleton.egg-info/top_level.txt
+tests/test_overlay.py

overlay_scoring_skeleton-0.1.0/src/overlay_scoring_skeleton.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

overlay_scoring_skeleton-0.1.0/src/overlay_scoring_skeleton.egg-info/requires.txt

@@ -0,0 +1,5 @@
+jsonschema[format-nongpl]<5.0,>=4.21
+pyyaml>=6.0
+
+[dev]
+pytest<10.0,>=8.0

overlay_scoring_skeleton-0.1.0/src/overlay_scoring_skeleton.egg-info/top_level.txt

@@ -0,0 +1 @@
+overlay_scoring

overlay_scoring_skeleton-0.1.0/tests/test_overlay.py

@@ -0,0 +1,254 @@
+"""Tests for the canonical overlay engine.
+
+Covers add / strengthen (leaf + group, group-scoped), every boundary condition,
+source-order preservation, opaque-payload preservation, and a round-trip against
+two real migrated definitions (aidr four-layer + siir dpa-clauses).
+"""
+
+from copy import deepcopy
+from pathlib import Path
+
+from overlay_scoring import (
+    apply_overlay,
+    apply_overlays,
+    group_items,
+    load_yaml,
+    validate_definition,
+)
+
+DEFS = Path(__file__).resolve().parents[1] / "definitions"
+OVERLAYS = Path(__file__).resolve().parents[1] / "examples" / "overlays"
+
+
+def four_layer() -> dict:
+    return load_yaml(DEFS / "example-four-layer.yaml")
+
+
+def dpa() -> dict:
+    return load_yaml(DEFS / "example-dpa-clauses.yaml")
+
+
+def _ids(defn: dict) -> list[str]:
+    return [it["id"] for it in defn["items"]]
+
+
+# --- base integrity ---------------------------------------------------------
+
+def test_base_definitions_validate():
+    assert validate_definition(four_layer()) == []
+    assert validate_definition(dpa()) == []
+
+
+def test_definition_with_orphan_leaf_is_rejected():
+    defn = {"version": 1, "name": "x", "items": [{"id": "A.child"}]}
+    kinds = {v.kind for v in validate_definition(defn)}
+    assert "unknown_group" in kinds
+
+
+def test_definition_with_duplicate_id_is_rejected():
+    defn = {"version": 1, "name": "x", "items": [{"id": "A"}, {"id": "A"}]}
+    kinds = {v.kind for v in validate_definition(defn)}
+    assert "id_collision" in kinds
+
+
+# --- add --------------------------------------------------------------------
+
+def test_add_leaf_to_existing_group():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "add": [{"id": "L1.Q5", "text": "extra", "weight": 1.0}]}
+    r = apply_overlay(four_layer(), ov)
+    assert r.ok, r.violations
+    assert "L1.Q5" in _ids(r.merged)
+
+
+def test_add_leaf_with_unknown_group_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "add": [{"id": "LZ.Q1", "text": "x", "weight": 1.0}]}
+    r = apply_overlay(four_layer(), ov)
+    # LZ matches selector "L*" but there is no LZ header
+    assert not r.ok
+    assert {v.kind for v in r.violations} == {"unknown_group"}
+
+
+def test_add_to_ungoverned_group_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "add": [{"id": "XYZ.q", "text": "x"}]}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"unsupported_op"}
+
+
+def test_add_id_collision_with_base_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "add": [{"id": "L1.Q1", "text": "dup", "weight": 1.0}]}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"id_collision"}
+
+
+def test_add_id_collision_within_same_overlay_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "add": [{"id": "L1.NEW", "text": "a", "weight": 1.0},
+                  {"id": "L1.NEW", "text": "b", "weight": 1.0}]}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"id_collision"}
+
+
+def test_add_new_group_header_then_leaf_in_same_overlay():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "add": [{"id": "L5", "name": "extra_layer", "pass": 1.0, "revise": 0.7},
+                  {"id": "L5.Q1", "text": "q", "weight": 1.0}]}
+    r = apply_overlay(four_layer(), ov)
+    assert r.ok, r.violations
+    assert "L5" in _ids(r.merged) and "L5.Q1" in _ids(r.merged)
+
+
+def test_add_id_with_two_separators_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "add": [{"id": "L1.Q1.deep", "text": "x", "weight": 1.0}]}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"invalid_overlay"}
+
+
+def test_add_item_without_id_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness", "add": [{"text": "no id"}]}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"invalid_overlay"}
+
+
+# --- strengthen -------------------------------------------------------------
+
+def test_strengthen_group_field_higher_is_accepted():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "strengthen": {"L4": {"revise": 0.8}}}
+    r = apply_overlay(four_layer(), ov)
+    assert r.ok, r.violations
+    l4 = next(i for i in r.merged["items"] if i["id"] == "L4")
+    assert l4["revise"] == 0.8
+
+
+def test_strengthen_group_field_equal_is_accepted():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "strengthen": {"L4": {"revise": 0.6}}}  # base is 0.6
+    r = apply_overlay(four_layer(), ov)
+    assert r.ok, r.violations
+
+
+def test_strengthen_group_field_weakening_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "strengthen": {"L4": {"revise": 0.4}}}  # 0.6 -> 0.4 is weaker
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"weakening_rejected"}
+
+
+def test_strengthen_leaf_field_lower_is_accepted():
+    ov = {"extends": "shared-infra-dpa-clauses",
+          "strengthen": {"clauses.DPA03": {"sla_confirmed_hours": 48}}}
+    r = apply_overlay(dpa(), ov)
+    assert r.ok, r.violations
+    c = next(i for i in r.merged["items"] if i["id"] == "clauses.DPA03")
+    assert c["sla_confirmed_hours"] == 48
+
+
+def test_strengthen_leaf_field_weakening_is_rejected():
+    ov = {"extends": "shared-infra-dpa-clauses",
+          "strengthen": {"clauses.DPA03": {"sla_hours": 48}}}  # 24 -> 48 is weaker (lower is stricter)
+    r = apply_overlay(dpa(), ov)
+    assert {v.kind for v in r.violations} == {"weakening_rejected"}
+
+
+def test_strengthen_non_numeric_is_rejected():
+    ov = {"extends": "shared-infra-dpa-clauses",
+          "strengthen": {"clauses.DPA03": {"sla_hours": "soon"}}}
+    r = apply_overlay(dpa(), ov)
+    assert {v.kind for v in r.violations} == {"invalid_overlay"}
+
+
+def test_strengthen_undeclared_field_is_rejected():
+    # weight is a leaf field but not declared strengthen-able in four-layer
+    ov = {"extends": "four-layer-delegation-readiness",
+          "strengthen": {"L1.Q1": {"weight": 2.0}}}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"unsupported_op"}
+
+
+def test_strengthen_unknown_id_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness",
+          "strengthen": {"L9": {"revise": 0.9}}}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"unknown_id"}
+
+
+# --- top-level / extends ----------------------------------------------------
+
+def test_extends_mismatch_is_rejected():
+    ov = {"extends": "wrong-name", "add": []}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"extends_mismatch"}
+
+
+def test_unsupported_top_level_key_is_rejected():
+    ov = {"extends": "four-layer-delegation-readiness", "delete": ["L1"]}
+    r = apply_overlay(four_layer(), ov)
+    assert {v.kind for v in r.violations} == {"unsupported_op"}
+
+
+# --- multi-overlay ----------------------------------------------------------
+
+def test_apply_overlays_stops_at_first_bad(tmp_path):
+    good = tmp_path / "good.yaml"
+    bad = tmp_path / "bad.yaml"
+    after = tmp_path / "after.yaml"
+    good.write_text("extends: four-layer-delegation-readiness\nadd:\n  - {id: 'L1.G1', text: g, weight: 1.0}\n")
+    bad.write_text("extends: four-layer-delegation-readiness\nstrengthen:\n  L4: {revise: 0.1}\n")
+    after.write_text("extends: four-layer-delegation-readiness\nadd:\n  - {id: 'L1.G2', text: g, weight: 1.0}\n")
+    r = apply_overlays(four_layer(), [good, bad, after])
+    assert not r.ok
+    assert r.applied == [str(good)]           # good applied, stopped before 'after'
+    assert "L1.G1" in _ids(r.merged)
+    assert "L1.G2" not in _ids(r.merged)
+
+
+# --- structural guarantees --------------------------------------------------
+
+def test_source_order_and_opaque_payload_preserved():
+    base = four_layer()
+    ov = load_yaml(OVERLAYS / "sample-four-layer.yaml")
+    r = apply_overlay(base, ov)
+    assert r.ok, r.violations
+    groups = group_items(r.merged)
+    # group order preserved
+    assert list(groups.keys()) == ["L1", "L2", "L3", "L4", "efficacy"]
+    # added leaves appended to their group, base leaves kept in order
+    l1_leaves = [i["id"] for i in groups["L1"]["leaves"]]
+    assert l1_leaves == ["L1.Q1", "L1.Q2", "L1.Q3", "L1.Q4", "L1.ACME_Q5"]
+    # opaque payload on the header survives untouched
+    assert groups["L1"]["header"]["case_evidence"][0]["confidence"] == "observed_fact"
+
+
+def test_engine_never_mutates_base():
+    base = four_layer()
+    snapshot = deepcopy(base)
+    apply_overlay(base, {"extends": "four-layer-delegation-readiness",
+                         "add": [{"id": "L1.Z", "text": "z", "weight": 1.0}]})
+    assert base == snapshot
+
+
+# --- round-trip against both real migrated definitions -----------------------
+
+def test_roundtrip_four_layer_sample_overlay():
+    r = apply_overlay(four_layer(), load_yaml(OVERLAYS / "sample-four-layer.yaml"))
+    assert r.ok, r.violations
+    ids = _ids(r.merged)
+    assert "L1.ACME_Q5" in ids and "L4.ACME_Q6" in ids
+    l4 = next(i for i in r.merged["items"] if i["id"] == "L4")
+    assert l4["revise"] == 0.8
+
+
+def test_roundtrip_dpa_sample_overlay():
+    r = apply_overlay(dpa(), load_yaml(OVERLAYS / "sample-dpa-clauses.yaml"))
+    assert r.ok, r.violations
+    ids = _ids(r.merged)
+    assert "clauses.ACME01" in ids
+    dpa03 = next(i for i in r.merged["items"] if i["id"] == "clauses.DPA03")
+    assert dpa03["sla_confirmed_hours"] == 48
+    assert dpa03["sla_hours"] == 24                 # untouched
+    assert dpa03["title"] == "委託先→委託元 漏えい通知SLA"   # opaque payload preserved