@aipper/aiws-spec 0.0.21 → 0.0.24

package/templates/workspace/manifest.json

@@ -17,6 +17,7 @@
     "REQUIREMENTS.md",
     ".gitignore",
     ".aiws/manifest.json",
+    ".githooks/commit-msg",
     ".githooks/pre-commit",
     ".githooks/pre-push",
     "changes/README.md",
@@ -26,10 +27,11 @@
     ".agents/skills/**",
     "tools/ws_change_check.py",
     "tools/requirements_contract.py",
-    ".claude/commands/aiws-init.md",
-    ".claude/commands/aiws-update.md",
-    ".claude/commands/aiws-validate.md",
-    ".claude/commands/aiws-rollback.md",
+    "tools/ws_tasks_plan.py",
+    ".claude/commands/p-aiws-init.md",
+    ".claude/commands/p-aiws-update.md",
+    ".claude/commands/p-aiws-validate.md",
+    ".claude/commands/p-aiws-rollback.md",
     ".claude/commands/ws-preflight.md",
     ".claude/commands/ws-migrate.md",
     ".claude/commands/ws-dev.md",
@@ -47,10 +49,10 @@
     ".claude/commands/ws-req-contract-sync.md",
     ".claude/commands/ws-req-contract-validate.md",
     ".claude/commands/ws-req-flow-sync.md",
-    ".opencode/command/aiws-init.md",
-    ".opencode/command/aiws-update.md",
-    ".opencode/command/aiws-validate.md",
-    ".opencode/command/aiws-rollback.md",
+    ".opencode/command/p-aiws-init.md",
+    ".opencode/command/p-aiws-update.md",
+    ".opencode/command/p-aiws-validate.md",
+    ".opencode/command/p-aiws-rollback.md",
     ".opencode/command/ws-preflight.md",
     ".opencode/command/ws-migrate.md",
     ".opencode/command/ws-dev.md",
@@ -106,37 +108,39 @@
     ".iflow/commands/ws-req-contract-sync.toml",
     ".iflow/commands/ws-req-contract-validate.toml",
     ".iflow/commands/ws-req-flow-sync.toml",
-    ".claude/commands/aiws-change-archive.md",
-    ".claude/commands/aiws-change-finish.md",
-    ".claude/commands/aiws-change-list.md",
-    ".claude/commands/aiws-change-new.md",
-    ".claude/commands/aiws-change-next.md",
-    ".claude/commands/aiws-change-start.md",
-    ".claude/commands/aiws-change-status.md",
-    ".claude/commands/aiws-change-sync.md",
-    ".claude/commands/aiws-change-templates-init.md",
-    ".claude/commands/aiws-change-templates-which.md",
-    ".claude/commands/aiws-change-validate.md",
-    ".claude/commands/aiws-hooks-install.md",
-    ".claude/commands/aiws-hooks-status.md",
+    ".claude/commands/p-aiws-change-archive.md",
+    ".claude/commands/p-aiws-change-finish.md",
+    ".claude/commands/p-aiws-change-list.md",
+    ".claude/commands/p-aiws-change-new.md",
+    ".claude/commands/p-aiws-change-next.md",
+    ".claude/commands/p-aiws-change-start.md",
+    ".claude/commands/p-aiws-change-status.md",
+    ".claude/commands/p-aiws-change-sync.md",
+    ".claude/commands/p-aiws-change-templates-init.md",
+    ".claude/commands/p-aiws-change-templates-which.md",
+    ".claude/commands/p-aiws-change-validate.md",
+    ".claude/commands/p-aiws-hooks-install.md",
+    ".claude/commands/p-aiws-hooks-status.md",
     ".claude/commands/ws-plan.md",
     ".claude/commands/ws-plan-verify.md",
+    ".claude/commands/ws-handoff.md",
     ".claude/commands/ws-bugfix.md",
-    ".opencode/command/aiws-change-archive.md",
-    ".opencode/command/aiws-change-finish.md",
-    ".opencode/command/aiws-change-list.md",
-    ".opencode/command/aiws-change-new.md",
-    ".opencode/command/aiws-change-next.md",
-    ".opencode/command/aiws-change-start.md",
-    ".opencode/command/aiws-change-status.md",
-    ".opencode/command/aiws-change-sync.md",
-    ".opencode/command/aiws-change-templates-init.md",
-    ".opencode/command/aiws-change-templates-which.md",
-    ".opencode/command/aiws-change-validate.md",
-    ".opencode/command/aiws-hooks-install.md",
-    ".opencode/command/aiws-hooks-status.md",
+    ".opencode/command/p-aiws-change-archive.md",
+    ".opencode/command/p-aiws-change-finish.md",
+    ".opencode/command/p-aiws-change-list.md",
+    ".opencode/command/p-aiws-change-new.md",
+    ".opencode/command/p-aiws-change-next.md",
+    ".opencode/command/p-aiws-change-start.md",
+    ".opencode/command/p-aiws-change-status.md",
+    ".opencode/command/p-aiws-change-sync.md",
+    ".opencode/command/p-aiws-change-templates-init.md",
+    ".opencode/command/p-aiws-change-templates-which.md",
+    ".opencode/command/p-aiws-change-validate.md",
+    ".opencode/command/p-aiws-hooks-install.md",
+    ".opencode/command/p-aiws-hooks-status.md",
     ".opencode/command/ws-plan.md",
-    ".opencode/command/ws-plan-verify.md"
+    ".opencode/command/ws-plan-verify.md",
+    ".opencode/command/ws-handoff.md"
   ],
   "optional": [
     ".iflow/agents/**",
@@ -149,19 +153,15 @@
     "tools/requirements_flow_gen.py",
     "tools/server_test_runner.py",
     "tools/iflow_watchdog.sh",
-    "tools/install_iflow_watchdog_systemd_user.sh"
+    "tools/install_iflow_watchdog_systemd_user.sh",
+    "tools/ws_resolve_sub_target.sh"
   ],
   "update": {
-    "replace_file": [
-      ".aiws/manifest.json",
-      ".githooks/pre-commit",
-      ".githooks/pre-push",
-      "tools/ws_change_check.py",
-      "tools/requirements_contract.py",
+    "remove": [
       ".agents/skills/aiws-init/SKILL.md",
-      ".agents/skills/aiws-rollback/SKILL.md",
       ".agents/skills/aiws-update/SKILL.md",
       ".agents/skills/aiws-validate/SKILL.md",
+      ".agents/skills/aiws-rollback/SKILL.md",
       ".agents/skills/aiws-hooks-install/SKILL.md",
       ".agents/skills/aiws-hooks-status/SKILL.md",
       ".agents/skills/aiws-change-list/SKILL.md",
@@ -175,6 +175,68 @@
       ".agents/skills/aiws-change-archive/SKILL.md",
       ".agents/skills/aiws-change-templates-which/SKILL.md",
       ".agents/skills/aiws-change-templates-init/SKILL.md",
+      ".claude/commands/aiws-init.md",
+      ".claude/commands/aiws-update.md",
+      ".claude/commands/aiws-validate.md",
+      ".claude/commands/aiws-rollback.md",
+      ".claude/commands/aiws-hooks-install.md",
+      ".claude/commands/aiws-hooks-status.md",
+      ".claude/commands/aiws-change-list.md",
+      ".claude/commands/aiws-change-new.md",
+      ".claude/commands/aiws-change-start.md",
+      ".claude/commands/aiws-change-finish.md",
+      ".claude/commands/aiws-change-status.md",
+      ".claude/commands/aiws-change-next.md",
+      ".claude/commands/aiws-change-sync.md",
+      ".claude/commands/aiws-change-validate.md",
+      ".claude/commands/aiws-change-archive.md",
+      ".claude/commands/aiws-change-templates-which.md",
+      ".claude/commands/aiws-change-templates-init.md",
+      ".opencode/command/aiws-init.md",
+      ".opencode/command/aiws-update.md",
+      ".opencode/command/aiws-validate.md",
+      ".opencode/command/aiws-rollback.md",
+      ".opencode/command/aiws-hooks-install.md",
+      ".opencode/command/aiws-hooks-status.md",
+      ".opencode/command/aiws-change-list.md",
+      ".opencode/command/aiws-change-new.md",
+      ".opencode/command/aiws-change-start.md",
+      ".opencode/command/aiws-change-finish.md",
+      ".opencode/command/aiws-change-status.md",
+      ".opencode/command/aiws-change-next.md",
+      ".opencode/command/aiws-change-sync.md",
+      ".opencode/command/aiws-change-validate.md",
+      ".opencode/command/aiws-change-archive.md",
+      ".opencode/command/aiws-change-templates-which.md",
+      ".opencode/command/aiws-change-templates-init.md",
+      ".agents/skills/ws-tasks-plan/SKILL.md"
+    ],
+    "replace_file": [
+      ".aiws/manifest.json",
+      ".githooks/commit-msg",
+      ".githooks/pre-commit",
+      ".githooks/pre-push",
+      "tools/ws_change_check.py",
+      "tools/requirements_contract.py",
+      "tools/ws_tasks_plan.py",
+      "tools/ws_resolve_sub_target.sh",
+      ".agents/skills/p-aiws-init/SKILL.md",
+      ".agents/skills/p-aiws-rollback/SKILL.md",
+      ".agents/skills/p-aiws-update/SKILL.md",
+      ".agents/skills/p-aiws-validate/SKILL.md",
+      ".agents/skills/p-aiws-hooks-install/SKILL.md",
+      ".agents/skills/p-aiws-hooks-status/SKILL.md",
+      ".agents/skills/p-aiws-change-list/SKILL.md",
+      ".agents/skills/p-aiws-change-new/SKILL.md",
+      ".agents/skills/p-aiws-change-start/SKILL.md",
+      ".agents/skills/p-aiws-change-finish/SKILL.md",
+      ".agents/skills/p-aiws-change-status/SKILL.md",
+      ".agents/skills/p-aiws-change-next/SKILL.md",
+      ".agents/skills/p-aiws-change-sync/SKILL.md",
+      ".agents/skills/p-aiws-change-validate/SKILL.md",
+      ".agents/skills/p-aiws-change-archive/SKILL.md",
+      ".agents/skills/p-aiws-change-templates-which/SKILL.md",
+      ".agents/skills/p-aiws-change-templates-init/SKILL.md",
       ".agents/skills/ws-analyze/SKILL.md",
       ".agents/skills/ws-bugfix/SKILL.md",
       ".agents/skills/ws-commit/SKILL.md",
@@ -184,6 +246,8 @@
       ".agents/skills/ws-migrate/SKILL.md",
       ".agents/skills/ws-plan/SKILL.md",
       ".agents/skills/ws-plan-verify/SKILL.md",
+      ".agents/skills/p-tasks-plan/SKILL.md",
+      ".agents/skills/ws-handoff/SKILL.md",
       ".agents/skills/ws-pull/SKILL.md",
       ".agents/skills/ws-push/SKILL.md",
       ".agents/skills/ws-submodule-setup/SKILL.md",
@@ -233,35 +297,35 @@
       ".iflow/commands/ws-req-contract-sync.toml",
       ".iflow/commands/ws-req-contract-validate.toml",
       ".iflow/commands/ws-req-flow-sync.toml",
-      ".claude/commands/aiws-change-archive.md",
-      ".claude/commands/aiws-change-finish.md",
-      ".claude/commands/aiws-change-list.md",
-      ".claude/commands/aiws-change-new.md",
-      ".claude/commands/aiws-change-next.md",
-      ".claude/commands/aiws-change-start.md",
-      ".claude/commands/aiws-change-status.md",
-      ".claude/commands/aiws-change-sync.md",
-      ".claude/commands/aiws-change-templates-init.md",
-      ".claude/commands/aiws-change-templates-which.md",
-      ".claude/commands/aiws-change-validate.md",
-      ".claude/commands/aiws-hooks-install.md",
-      ".claude/commands/aiws-hooks-status.md",
+      ".claude/commands/p-aiws-change-archive.md",
+      ".claude/commands/p-aiws-change-finish.md",
+      ".claude/commands/p-aiws-change-list.md",
+      ".claude/commands/p-aiws-change-new.md",
+      ".claude/commands/p-aiws-change-next.md",
+      ".claude/commands/p-aiws-change-start.md",
+      ".claude/commands/p-aiws-change-status.md",
+      ".claude/commands/p-aiws-change-sync.md",
+      ".claude/commands/p-aiws-change-templates-init.md",
+      ".claude/commands/p-aiws-change-templates-which.md",
+      ".claude/commands/p-aiws-change-validate.md",
+      ".claude/commands/p-aiws-hooks-install.md",
+      ".claude/commands/p-aiws-hooks-status.md",
       ".claude/commands/ws-plan.md",
       ".claude/commands/ws-plan-verify.md",
       ".claude/commands/ws-bugfix.md",
-      ".opencode/command/aiws-change-archive.md",
-      ".opencode/command/aiws-change-finish.md",
-      ".opencode/command/aiws-change-list.md",
-      ".opencode/command/aiws-change-new.md",
-      ".opencode/command/aiws-change-next.md",
-      ".opencode/command/aiws-change-start.md",
-      ".opencode/command/aiws-change-status.md",
-      ".opencode/command/aiws-change-sync.md",
-      ".opencode/command/aiws-change-templates-init.md",
-      ".opencode/command/aiws-change-templates-which.md",
-      ".opencode/command/aiws-change-validate.md",
-      ".opencode/command/aiws-hooks-install.md",
-      ".opencode/command/aiws-hooks-status.md",
+      ".opencode/command/p-aiws-change-archive.md",
+      ".opencode/command/p-aiws-change-finish.md",
+      ".opencode/command/p-aiws-change-list.md",
+      ".opencode/command/p-aiws-change-new.md",
+      ".opencode/command/p-aiws-change-next.md",
+      ".opencode/command/p-aiws-change-start.md",
+      ".opencode/command/p-aiws-change-status.md",
+      ".opencode/command/p-aiws-change-sync.md",
+      ".opencode/command/p-aiws-change-templates-init.md",
+      ".opencode/command/p-aiws-change-templates-which.md",
+      ".opencode/command/p-aiws-change-validate.md",
+      ".opencode/command/p-aiws-hooks-install.md",
+      ".opencode/command/p-aiws-hooks-status.md",
       ".opencode/command/ws-plan.md",
       ".opencode/command/ws-plan-verify.md"
     ],
@@ -281,16 +345,16 @@
       ".gitignore": [
         "gitignore"
       ],
-      ".claude/commands/aiws-init.md": [
+      ".claude/commands/p-aiws-init.md": [
         "claude:aiws-init"
       ],
-      ".claude/commands/aiws-update.md": [
+      ".claude/commands/p-aiws-update.md": [
         "claude:aiws-update"
       ],
-      ".claude/commands/aiws-validate.md": [
+      ".claude/commands/p-aiws-validate.md": [
         "claude:aiws-validate"
       ],
-      ".claude/commands/aiws-rollback.md": [
+      ".claude/commands/p-aiws-rollback.md": [
         "claude:aiws-rollback"
       ],
       ".claude/commands/ws-preflight.md": [
@@ -344,16 +408,16 @@
       ".claude/commands/ws-req-flow-sync.md": [
         "claude:ws-req-flow-sync"
       ],
-      ".opencode/command/aiws-init.md": [
+      ".opencode/command/p-aiws-init.md": [
         "opencode:aiws-init"
       ],
-      ".opencode/command/aiws-update.md": [
+      ".opencode/command/p-aiws-update.md": [
         "opencode:aiws-update"
       ],
-      ".opencode/command/aiws-validate.md": [
+      ".opencode/command/p-aiws-validate.md": [
         "opencode:aiws-validate"
       ],
-      ".opencode/command/aiws-rollback.md": [
+      ".opencode/command/p-aiws-rollback.md": [
         "opencode:aiws-rollback"
       ],
       ".opencode/command/ws-preflight.md": [
@@ -410,43 +474,43 @@
       ".opencode/command/ws-req-flow-sync.md": [
         "opencode:ws-req-flow-sync"
       ],
-      ".claude/commands/aiws-change-archive.md": [
+      ".claude/commands/p-aiws-change-archive.md": [
         "claude:aiws-change-archive"
       ],
-      ".claude/commands/aiws-change-finish.md": [
+      ".claude/commands/p-aiws-change-finish.md": [
         "claude:aiws-change-finish"
       ],
-      ".claude/commands/aiws-change-list.md": [
+      ".claude/commands/p-aiws-change-list.md": [
         "claude:aiws-change-list"
       ],
-      ".claude/commands/aiws-change-new.md": [
+      ".claude/commands/p-aiws-change-new.md": [
         "claude:aiws-change-new"
       ],
-      ".claude/commands/aiws-change-next.md": [
+      ".claude/commands/p-aiws-change-next.md": [
         "claude:aiws-change-next"
       ],
-      ".claude/commands/aiws-change-start.md": [
+      ".claude/commands/p-aiws-change-start.md": [
         "claude:aiws-change-start"
       ],
-      ".claude/commands/aiws-change-status.md": [
+      ".claude/commands/p-aiws-change-status.md": [
         "claude:aiws-change-status"
       ],
-      ".claude/commands/aiws-change-sync.md": [
+      ".claude/commands/p-aiws-change-sync.md": [
         "claude:aiws-change-sync"
       ],
-      ".claude/commands/aiws-change-templates-init.md": [
+      ".claude/commands/p-aiws-change-templates-init.md": [
         "claude:aiws-change-templates-init"
       ],
-      ".claude/commands/aiws-change-templates-which.md": [
+      ".claude/commands/p-aiws-change-templates-which.md": [
         "claude:aiws-change-templates-which"
       ],
-      ".claude/commands/aiws-change-validate.md": [
+      ".claude/commands/p-aiws-change-validate.md": [
         "claude:aiws-change-validate"
       ],
-      ".claude/commands/aiws-hooks-install.md": [
+      ".claude/commands/p-aiws-hooks-install.md": [
         "claude:aiws-hooks-install"
       ],
-      ".claude/commands/aiws-hooks-status.md": [
+      ".claude/commands/p-aiws-hooks-status.md": [
         "claude:aiws-hooks-status"
       ],
       ".claude/commands/ws-plan.md": [
@@ -455,46 +519,49 @@
       ".claude/commands/ws-plan-verify.md": [
         "claude:ws-plan-verify"
       ],
+      ".claude/commands/ws-handoff.md": [
+        "claude:ws-handoff"
+      ],
       ".claude/commands/ws-bugfix.md": [
         "claude:ws-bugfix"
       ],
-      ".opencode/command/aiws-change-archive.md": [
+      ".opencode/command/p-aiws-change-archive.md": [
         "opencode:aiws-change-archive"
       ],
-      ".opencode/command/aiws-change-finish.md": [
+      ".opencode/command/p-aiws-change-finish.md": [
         "opencode:aiws-change-finish"
       ],
-      ".opencode/command/aiws-change-list.md": [
+      ".opencode/command/p-aiws-change-list.md": [
         "opencode:aiws-change-list"
       ],
-      ".opencode/command/aiws-change-new.md": [
+      ".opencode/command/p-aiws-change-new.md": [
         "opencode:aiws-change-new"
       ],
-      ".opencode/command/aiws-change-next.md": [
+      ".opencode/command/p-aiws-change-next.md": [
         "opencode:aiws-change-next"
       ],
-      ".opencode/command/aiws-change-start.md": [
+      ".opencode/command/p-aiws-change-start.md": [
         "opencode:aiws-change-start"
       ],
-      ".opencode/command/aiws-change-status.md": [
+      ".opencode/command/p-aiws-change-status.md": [
         "opencode:aiws-change-status"
       ],
-      ".opencode/command/aiws-change-sync.md": [
+      ".opencode/command/p-aiws-change-sync.md": [
         "opencode:aiws-change-sync"
       ],
-      ".opencode/command/aiws-change-templates-init.md": [
+      ".opencode/command/p-aiws-change-templates-init.md": [
         "opencode:aiws-change-templates-init"
       ],
-      ".opencode/command/aiws-change-templates-which.md": [
+      ".opencode/command/p-aiws-change-templates-which.md": [
         "opencode:aiws-change-templates-which"
       ],
-      ".opencode/command/aiws-change-validate.md": [
+      ".opencode/command/p-aiws-change-validate.md": [
         "opencode:aiws-change-validate"
       ],
-      ".opencode/command/aiws-hooks-install.md": [
+      ".opencode/command/p-aiws-hooks-install.md": [
         "opencode:aiws-hooks-install"
       ],
-      ".opencode/command/aiws-hooks-status.md": [
+      ".opencode/command/p-aiws-hooks-status.md": [
         "opencode:aiws-hooks-status"
       ],
       ".opencode/command/ws-plan.md": [
@@ -502,6 +569,9 @@
       ],
       ".opencode/command/ws-plan-verify.md": [
         "opencode:ws-plan-verify"
+      ],
+      ".opencode/command/ws-handoff.md": [
+        "opencode:ws-handoff"
       ]
     }
   }

package/templates/workspace/tools/ws_change_check.py

@@ -26,6 +26,73 @@ def read_text(path: Path) -> str:
     return path.read_text(encoding="utf-8", errors="replace")
 
 
+def list_submodules_from_gitmodules(root: Path) -> List[Tuple[str, str]]:
+    """Return [(name, sub_path), ...] from .gitmodules, or [] if none."""
+    gm = root / ".gitmodules"
+    if not gm.exists():
+        return []
+    try:
+        res = subprocess.run(
+            ["git", "-C", str(root), "config", "--file", ".gitmodules", "--get-regexp", r"^submodule\..*\.path$"],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+    except Exception:
+        return []
+    if res.returncode != 0:
+        return []
+    subs: List[Tuple[str, str]] = []
+    for raw in (res.stdout or "").splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        idx = line.find(" ")
+        if idx <= 0:
+            continue
+        key = line[:idx].strip()
+        sub_path = line[idx + 1 :].strip()
+        m = re.match(r"^submodule\.(.+)\.path$", key)
+        if not m:
+            continue
+        name = (m.group(1) or "").strip()
+        if name and sub_path:
+            subs.append((name, sub_path))
+    return subs
+
+
+def parse_submodule_targets(path: Path) -> Tuple[Dict[str, Tuple[str, str]], List[str]]:
+    """Parse a submodules.targets file. Returns (parsed_dict, error_messages)."""
+    parsed: Dict[str, Tuple[str, str]] = {}
+    perr: List[str] = []
+    if not path.exists():
+        return parsed, perr
+    text = read_text(path)
+    for i, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = re.split(r"\s+", line)
+        if len(parts) < 2:
+            perr.append(f"{path.name}:{i} invalid line (expected: <path> <target_branch> [remote])")
+            continue
+        sub_path = parts[0].strip()
+        target_branch = parts[1].strip()
+        remote = (parts[2].strip() if len(parts) >= 3 else "origin") or "origin"
+        if not sub_path:
+            perr.append(f"{path.name}:{i} missing submodule path")
+            continue
+        if sub_path in parsed:
+            perr.append(f"{path.name}:{i} duplicate submodule path: {sub_path}")
+            continue
+        if not target_branch or target_branch in ("<fill-me>", "<fill_me>", "tbd", "TBD"):
+            perr.append(f"{path.name}:{i} missing/placeholder target_branch for {sub_path}")
+            continue
+        parsed[sub_path] = (target_branch, remote)
+    return parsed, perr
+
+
 def sha256(path: Path) -> str:
     h = hashlib.sha256()
     with path.open("rb") as f:
@@ -334,6 +401,38 @@ def validate_change(
     errors: List[str] = []
     warnings: List[str] = []
 
+    # Submodule targets constraint: when `.gitmodules` declares submodules, require a per-change target mapping.
+    # In strict mode this is an error (blocks delivery); in non-strict mode it's a warning (informational).
+    subs = list_submodules_from_gitmodules(root)
+    if subs:
+        targets_path = change_dir / "submodules.targets"
+        if not targets_path.exists() or targets_path.stat().st_size == 0:
+            msg = "missing/empty: changes/<change-id>/submodules.targets (required when .gitmodules declares submodules)"
+            hint = f"hint: create it under {change_dir} (format: <sub_path> <target_branch> [remote])"
+            if strict:
+                errors.append(msg)
+                errors.append(hint)
+            else:
+                warnings.append(msg)
+                warnings.append(hint)
+        else:
+            targets, perr = parse_submodule_targets(targets_path)
+            for pe in perr:
+                errors.append(pe)
+            declared_paths = {p for _, p in subs}
+            missing_paths = sorted([p for p in declared_paths if p not in targets])
+            if missing_paths:
+                msg = f"{targets_path.name} missing entries for submodules: {', '.join(missing_paths)}"
+                if strict:
+                    errors.append(msg)
+                else:
+                    warnings.append(msg)
+            extra_paths = sorted([p for p in targets.keys() if p not in declared_paths])
+            if extra_paths:
+                warnings.append(
+                    f"{targets_path.name} includes unknown submodule paths (ignored): {', '.join(extra_paths)}"
+                )
+
     def file_state(rel: str) -> Optional[Path]:
         p = change_dir / rel
         if not p.exists():

package/templates/workspace/tools/ws_resolve_sub_target.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# ws_resolve_sub_target.sh — Resolve the target branch & remote for a submodule path.
+#
+# Usage:
+#   source tools/ws_resolve_sub_target.sh
+#   ws_resolve_sub_target <sub_path> <sub_name> <targets_file> <base_branch>
+#
+# Outputs two variables: _resolved_branch and _resolved_remote.
+# Returns 0 on success, 2 on failure (with error printed to stderr).
+
+ws_resolve_sub_target() {
+  local sub_path="$1" sub_name="$2" targets="$3" base_branch="$4"
+  _resolved_branch=""
+  _resolved_remote=""
+
+  # Priority 1: changes/<id>/submodules.targets (per-change override)
+  local override=""
+  if [[ -f "${targets}" ]]; then
+    override="$(awk -v p="${sub_path}" '
+      $1==p && $0 !~ /^[[:space:]]*#/ {
+        b=$2; r=$3;
+        if (r=="") r="origin";
+        if (b!="") { print b " " r; exit }
+      }
+    ' "${targets}" 2>/dev/null || true)"
+  fi
+
+  if [[ -n "${override:-}" ]]; then
+    _resolved_branch="${override%% *}"
+    _resolved_remote="${override#* }"
+    if [[ "${_resolved_branch:-}" == "." ]]; then _resolved_branch="${base_branch}"; fi
+  else
+    # Priority 2: .gitmodules submodule.<name>.branch
+    local cfg_branch
+    cfg_branch="$(git config --file .gitmodules --get "submodule.${sub_name}.branch" 2>/dev/null || true)"
+    if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="${base_branch}"; fi
+    _resolved_branch="${cfg_branch}"
+    _resolved_remote="origin"
+  fi
+
+  if [[ -z "${_resolved_branch:-}" ]]; then
+    echo "error: cannot resolve target branch for submodule path=${sub_path}" >&2
+    echo "hint: add an entry to ${targets} (preferred for multi-channel), or set .gitmodules submodule.<name>.branch" >&2
+    return 2
+  fi
+  return 0
+}