@harmonyos-arkts/d2h 0.1.19 → 0.1.21

package/workflow/feature_plan.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""Validate a feature planning handoff, without inferring feature semantics."""
+
+import importlib.util
+import argparse
+import json
+from pathlib import Path
+
+
+def validate_delivery(data, require):
+    """Optional, explicit scope tiers; scope_items remain the authorization source."""
+    delivery = data.get('delivery')
+    if delivery is None:
+        return
+    require(data.get('schema') == 'd2h-feature-plan/v2', 'delivery requires v2 scope tracking')
+    if not isinstance(delivery, dict):
+        require(False, 'delivery must be an object')
+        return
+    tiers = {'mvp': 0, 'core': 1, 'full': 2}
+    target = delivery.get('target')
+    require(isinstance(target, str) and target in tiers, 'delivery target must be mvp/core/full')
+    require(type(delivery.get('customized')) is bool, 'delivery customized must be boolean')
+    require(isinstance(delivery.get('reason'), str) and bool(delivery['reason'].strip()), 'delivery reason required')
+    feature_rows = data.get('features') if isinstance(data.get('features'), list) else []
+    items = {(f.get('feature_id'), i.get('scope_id')): (f, i) for f in feature_rows if isinstance(f, dict) and isinstance(f.get('scope_items'), list) for i in f['scope_items'] if isinstance(i, dict) and isinstance(f.get('feature_id'), str) and isinstance(i.get('scope_id'), str)}
+    remaining = {key for key, (f, i) in items.items() if f.get('scope_status') != 'excluded' and i.get('status') != 'excluded'}
+    rows = delivery.get('scope_layers')
+    require(isinstance(rows, list), 'delivery scope_layers must be an array')
+    mapping = {}
+    for row in rows if isinstance(rows, list) else []:
+        if not isinstance(row, dict) or not isinstance(row.get('feature_id'), str) or not isinstance(row.get('scope_id'), str):
+            require(False, 'delivery needs feature_id/scope_id references')
+            continue
+        key = (row['feature_id'], row['scope_id'])
+        require(key in items, 'delivery references unknown scope')
+        require(key not in mapping, 'delivery scope mapped more than once')
+        layer = row.get('layer')
+        require(isinstance(layer, str) and layer in tiers, 'delivery layer must be mvp/core/full')
+        mapping[key] = layer if isinstance(layer, str) else None
+    require(remaining <= mapping.keys(), 'delivery must map every non-excluded scope, including deferred/unresolved')
+    if delivery.get('customized') is False and isinstance(target, str) and target in tiers:
+        expected = {key for key in remaining if tiers.get(mapping.get(key), 99) <= tiers[delivery['target']]}
+        selected = {key for key in remaining if items[key][0].get('scope_status') == 'included' and not items[key][0].get('needs_clarification') and items[key][1].get('status') == 'included' and items[key][1].get('milestone') != 'unassigned'}
+        require(expected == selected, 'delivery preset must match authorized scope; use customized=true for local adjustments')
+
+
+def validate(data, previous=None, check_analysis=True, require_delivery=False):
+    errors = []
+
+    def require(condition, message):
+        if not condition:
+            errors.append(message)
+
+    def text(value):
+        return isinstance(value, str) and bool(value.strip())
+
+    def records(key, id_key):
+        items = data.get(key)
+        if not isinstance(items, list):
+            errors.append(f"{key} must be an array")
+            return {}
+        result = {}
+        for item in items:
+            if not isinstance(item, dict) or not text(item.get(id_key)):
+                errors.append(f"{key} entries require {id_key}")
+                continue
+            identity = item[id_key]
+            require(identity not in result, f"duplicate {id_key}: {identity}")
+            result[identity] = item
+        return result
+
+    if not isinstance(data, dict):
+        return ["plan must be an object"]
+    require(data.get("schema") in {"d2h-feature-plan/v1", "d2h-feature-plan/v2"}, "unsupported schema")
+    revision = data.get("revision")
+    require(type(revision) is int and revision > 0, "revision must be a positive integer")
+    sources = records("sources", "source_id")
+    milestones = records("milestones", "milestone_id")
+    features = records("features", "feature_id")
+    require("unassigned" not in milestones, "unassigned is a reserved milestone")
+    for identity, source in sources.items():
+        require(source.get("kind") in {"facts", "utg", "inventory", "source", "user"}, f"{identity}: invalid source kind")
+        require(text(source.get("locator")) and text(source.get("revision")), f"{identity}: locator and revision required")
+    for identity, milestone in milestones.items():
+        require(text(milestone.get("title")), f"{identity}: title required")
+        checks = milestone.get("acceptance")
+        require(isinstance(checks, list) and bool(checks) and all(text(c) for c in checks), f"{identity}: acceptance required")
+
+    graph = {}
+    for identity, feature in features.items():
+        require(text(feature.get("title")), f"{identity}: title required")
+        origin = feature.get("origin")
+        require(origin in {"extracted", "user", "merged"}, f"{identity}: invalid origin")
+        refs = feature.get("source_refs")
+        kinds = set()
+        require(isinstance(refs, list) and bool(refs), f"{identity}: source_refs required")
+        for ref in refs if isinstance(refs, list) else []:
+            if not isinstance(ref, dict) or not text(ref.get("ref")) or ref.get("source_id") not in sources:
+                errors.append(f"{identity}: invalid source reference")
+                continue
+            kind = sources[ref["source_id"]].get("kind")
+            if isinstance(kind, str):
+                kinds.add(kind)
+        if origin in {"user", "merged"}:
+            require("user" in kinds, f"{identity}: user provenance required")
+        if origin in {"extracted", "merged"}:
+            require(bool(kinds - {"user"}), f"{identity}: extracted provenance required")
+        require(feature.get("user_priority") in {"must", "normal", "later"}, f"{identity}: invalid priority")
+        status = feature.get("scope_status")
+        require(status in {"included", "deferred", "excluded"}, f"{identity}: invalid scope status")
+        if status in {"deferred", "excluded"}:
+            require(text(feature.get("reason")), f"{identity}: scope change reason required")
+        require(feature.get("milestone") in [*milestones, "unassigned"], f"{identity}: unknown milestone")
+        for key in (("required_scope", "acceptance") if data.get("schema") == "d2h-feature-plan/v1" else ("acceptance",)):
+            values = feature.get(key)
+            require(isinstance(values, list) and bool(values) and all(text(v) for v in values), f"{identity}: {key} must be nonempty strings")
+        deferred = feature.get("deferred_scope", [])
+        require(isinstance(deferred, list), f"{identity}: deferred_scope must be an array")
+        for item in deferred if isinstance(deferred, list) else []:
+            require(isinstance(item, dict) and text(item.get("description")) and item.get("target_milestone") in [*milestones, "unassigned"], f"{identity}: invalid deferred scope")
+        if data.get("schema") == "d2h-feature-plan/v2":
+            items = feature.get("scope_items")
+            require(isinstance(items, list) and bool(items), f"{identity}: scope_items required")
+            seen = set()
+            for item in items if isinstance(items, list) else []:
+                if not isinstance(item, dict) or not text(item.get("scope_id")):
+                    errors.append(f"{identity}: scope_id required")
+                    continue
+                scope_id = item["scope_id"]
+                require(scope_id not in seen, f"{identity}: duplicate scope_id {scope_id}")
+                seen.add(scope_id)
+                require(text(item.get("description")), f"{identity}/{scope_id}: description required")
+                require(item.get("status") in {"included", "deferred", "excluded", "unresolved"}, f"{identity}/{scope_id}: invalid scope status")
+                require(item.get("milestone") in [*milestones, "unassigned"], f"{identity}/{scope_id}: unknown milestone")
+                require(isinstance(item.get("acceptance"), list) and bool(item["acceptance"]) and all(text(v) for v in item["acceptance"]), f"{identity}/{scope_id}: acceptance required")
+                if item.get("status") != "included":
+                    require(text(item.get("reason")), f"{identity}/{scope_id}: disposition reason required")
+            require("required_scope" not in feature and "deferred_scope" not in feature, f"{identity}: v2 uses scope_items as sole scope source")
+        derived = feature.get("derived_from")
+        require(isinstance(derived, list) and all(text(v) and v != identity for v in derived), f"{identity}: invalid derived_from")
+        require(type(feature.get("needs_clarification")) is bool, f"{identity}: needs_clarification must be boolean")
+        targets = feature.get("requested_before")
+        require(isinstance(targets, list), f"{identity}: requested_before must be an array")
+        graph[identity] = []
+        for target in targets if isinstance(targets, list) else []:
+            if not text(target) or target not in features or target == identity:
+                errors.append(f"{identity}: invalid requested_before target: {target}")
+                continue
+            require(feature.get("milestone") == features[target].get("milestone"), f"{identity}: ordering crosses milestones: {target}")
+            graph[identity].append(target)
+
+    validate_delivery(data, require)
+    if require_delivery and not errors:
+        delivery = data.get('delivery')
+        require(isinstance(delivery, dict), 'usable delivery presets require explicit delivery configuration')
+        if isinstance(delivery, dict):
+            eligible = {(f.get('feature_id'), i.get('scope_id')) for f in features.values() if f.get('scope_status') != 'excluded' for i in f.get('scope_items', []) if i.get('status') != 'excluded'}
+            rows = delivery.get('scope_layers')
+            for index, target in enumerate(('mvp', 'core', 'full')):
+                layers = ('mvp', 'core', 'full')[:index + 1]
+                keys = {(r.get('feature_id'), r.get('scope_id')) for r in rows if isinstance(r, dict) and r.get('layer') in layers} if isinstance(rows, list) else set()
+                require(bool(keys & eligible), f'{target} preset has no selectable scope; assess scope_layers instead of assigning every item to full')
+
+    # Iterative topological check supports large inventories without recursion limits.
+    indegree = dict.fromkeys(graph, 0)
+    for targets in graph.values():
+        for target in targets:
+            indegree[target] += 1
+    ready = [key for key, degree in indegree.items() if degree == 0]
+    visited = 0
+    while ready:
+        visited += 1
+        for target in graph[ready.pop()]:
+            indegree[target] -= 1
+            if indegree[target] == 0:
+                ready.append(target)
+    require(visited == len(graph), "requested_before contains a cycle")
+    changes = data.get("changes")
+    require(isinstance(changes, list), "changes must be an array")
+    for change in changes if isinstance(changes, list) else []:
+        if not isinstance(change, dict):
+            errors.append("invalid change record")
+            continue
+        number = change.get("revision")
+        require(type(number) is int and type(revision) is int and 1 <= number <= revision, "invalid change revision")
+        require(change.get("actor") in {"user", "ai", "import"} and text(change.get("summary")), "change actor and summary required")
+        ids = change.get("feature_ids")
+        require(isinstance(ids, list) and all(text(v) and v in features for v in ids), "change references unknown features")
+    require(isinstance(data.get("open_questions"), list), "open_questions must be an array")
+    if previous is not None:
+        if not isinstance(previous, dict) or (previous.get("schema"), data.get("schema")) not in {("d2h-feature-plan/v1", "d2h-feature-plan/v1"), ("d2h-feature-plan/v1", "d2h-feature-plan/v2"), ("d2h-feature-plan/v2", "d2h-feature-plan/v2")}:
+            errors.append("unsupported feature schema transition")
+        else:
+            old_revision = previous.get("revision")
+            if data != previous:
+                require(type(revision) is int and type(old_revision) is int and revision == old_revision + 1, "changed plan must increment revision by one")
+                require(isinstance(changes, list) and any(isinstance(c, dict) and c.get("revision") == revision for c in changes), "changed plan needs a current revision event")
+            old_changes = previous.get("changes", [])
+            require(isinstance(changes, list) and changes[:len(old_changes)] == old_changes, "previous change history must be preserved")
+            for feature in features.values():
+                old = next((f for f in previous.get("features", []) if f.get("feature_id") == feature["feature_id"]), {})
+                old_scope = {v["scope_id"] for v in old.get("scope_items", [])}
+                new_scope = {v["scope_id"] for v in feature.get("scope_items", [])}
+                require(old_scope <= new_scope, "previous scope IDs must be retained; exclude replaced scope items")
+            old_ids = {f["feature_id"] for f in previous.get("features", []) if isinstance(f, dict) and text(f.get("feature_id"))}
+            require(old_ids <= features.keys(), "previous feature IDs must be retained; exclude replaced features")
+    if not errors and check_analysis:
+        loader = importlib.util.spec_from_file_location('analysis_handoff', Path(__file__).with_name('artifact_bindings.py'))
+        handoff = importlib.util.module_from_spec(loader)
+        loader.loader.exec_module(handoff)
+        errors.extend(handoff.validate_links(data))
+    return errors
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("plan", type=Path)
+    parser.add_argument("--previous", type=Path)
+    parser.add_argument("--require-delivery", action="store_true", help="Require explicit, nonempty MVP/core/full cumulative presets")
+    args = parser.parse_args()
+    try:
+        data = json.loads(args.plan.read_text(encoding="utf-8"))
+        previous = json.loads(args.previous.read_text(encoding="utf-8")) if args.previous else None
+        errors = validate(data, previous, require_delivery=args.require_delivery)
+    except (OSError, ValueError) as error:
+        errors = [str(error)]
+    for error in errors:
+        print(f"ERROR: {error}")
+    print(json.dumps({"errors": len(errors)}, ensure_ascii=False))
+    return bool(errors)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/workflow/page_batches.py

@@ -0,0 +1,223 @@
+"""Explicit page-round validation and bounded batch recommendations; no source inference."""
+import hashlib
+import json
+
+
+def require(value, message):
+    if not value:
+        raise ValueError(message)
+
+
+def text(value):
+    return isinstance(value, str) and bool(value.strip())
+
+
+def records(items, key):
+    require(isinstance(items, list) and bool(items), f'{key}: nonempty records required')
+    result = {}
+    for item in items:
+        require(isinstance(item, dict) and text(item.get(key)) and item[key] not in result, f'{key}: missing or duplicate ID')
+        result[item[key]] = item
+    return result
+
+
+def enabled(plan):
+    return plan.get('dispatch_mode', 'single-spec') == 'page-batches'
+
+
+def validate(plan, features, specs, edges):
+    mode = plan.get('dispatch_mode', 'single-spec')
+    require(mode in {'single-spec', 'page-batches'}, 'unknown dispatch_mode')
+    if mode == 'single-spec':
+        require('rounds' not in plan and 'page_batches' not in plan, 'rounds require explicit page-batches dispatch_mode')
+        return
+    rounds = records(plan.get('rounds'), 'round_id')
+    batches = records(plan.get('page_batches'), 'batch_id')
+    milestones = [m['milestone_id'] for m in features['milestones']]
+    milestone_order = []
+    for index, item in enumerate(rounds.values(), 1):
+        require(type(item.get('order')) is int and item['order'] == index, 'round order must be consecutive and match array order')
+        require(item.get('kind') in {'baseline', 'incremental', 'completion'}, 'unknown round kind')
+        require(text(item.get('goal')) and text(item.get('rationale')), 'round goal and rationale required')
+        require(item.get('milestone') in milestones, 'round has unknown milestone')
+        milestone_order.append(milestones.index(item['milestone']))
+        checks = item.get('goal_checks')
+        require(isinstance(checks, list) and bool(checks) and all(text(c) for c in checks) and len(set(checks)) == len(checks), 'round goal_checks required and unique')
+    require(milestone_order == sorted(milestone_order), 'rounds cannot reverse milestone order')
+    for milestone in {r['milestone'] for r in rounds.values()}:
+        group = [r for r in rounds.values() if r['milestone'] == milestone]
+        require(group[0]['kind'] == 'baseline' and sum(r['kind'] == 'baseline' for r in group) == 1, 'each milestone starts with exactly one baseline round')
+        require(all(r['kind'] != 'completion' for r in group[:-1]), 'completion round must be last in its milestone')
+    pages = {p['page_id'] for p in plan['pages']}
+    owner = {}
+    for bid, batch in batches.items():
+        require(batch.get('round_id') in rounds and batch.get('page_id') in pages, f'{bid}: unknown round or page')
+        require(text(batch.get('goal')) and text(batch.get('rationale')), f'{bid}: batch goal and grouping rationale required')
+        members = batch.get('spec_ids')
+        require(isinstance(members, list) and bool(members) and all(text(s) for s in members) and len(set(members)) == len(members), f'{bid}: unique spec_ids required')
+        require(type(batch.get('max_specs')) is int and batch['max_specs'] > 0 and len(members) <= batch['max_specs'], f'{bid}: spec count exceeds batch budget')
+        for key in ('max_effort_hours', 'opportunistic_hours'):
+            value = batch.get(key)
+            require(type(value) in (int, float) and value >= 0 and value < float('inf'), f'{bid}: invalid {key}')
+        require(batch['max_effort_hours'] > 0 and batch['opportunistic_hours'] <= batch['max_effort_hours'], f'{bid}: invalid effort budget')
+        for sid in members:
+            require(sid in specs and sid not in owner, f'{bid}: unknown or multiply assigned Spec: {sid}')
+            require(specs[sid]['page_id'] == batch['page_id'], f'{bid}: cross-page grouping is not allowed')
+            require(specs[sid]['milestone'] == rounds[batch['round_id']]['milestone'], f'{bid}: round milestone mismatch')
+            owner[sid] = bid
+        require(sum(specs[s]['effort']['expected'] for s in members) <= batch['max_effort_hours'], f'{bid}: effort exceeds batch budget; split the page pass')
+    require(owner.keys() == specs.keys(), 'every Spec must belong to exactly one page batch')
+    for rid, item in rounds.items():
+        members = {s for s, bid in owner.items() if batches[bid]['round_id'] == rid}
+        require(bool(members), f'{rid}: empty round')
+        checks = {c for sid in members for c in specs[sid]['checks']}
+        require(set(item['goal_checks']) <= checks, f'{rid}: goal checks must map to member Specs')
+    batch_edges = {bid: set() for bid in batches}
+    for sid, parents in edges.items():
+        consumer = owner[sid]
+        consumer_round = rounds[batches[consumer]['round_id']]['order']
+        for parent in parents:
+            provider = owner[parent]
+            require(rounds[batches[provider]['round_id']]['order'] <= consumer_round, f'{sid}: dependency/order requires a later round')
+            if provider != consumer:
+                batch_edges[consumer].add(provider)
+    remaining = set(batches)
+    while remaining:
+        layer = {b for b in remaining if not batch_edges[b] & remaining}
+        require(layer, 'page batch contraction cycle; split interleaved page work')
+        remaining -= layer
+    for page in plan['pages']:
+        require(type(page.get('scope_complete')) is bool, 'page scope_complete coverage declaration required')
+        if page['scope_complete']:
+            refs = page.get('scope_evidence_refs')
+            require(isinstance(refs, list) and bool(refs) and all(text(ref) for ref in refs), 'complete page scope requires coverage evidence refs')
+
+
+def round_signature(plan, features, round_id, edges):
+    specs = {s['spec_id']: s for s in plan['specs']}
+    item = next(r for r in plan['rounds'] if r['round_id'] == round_id)
+    members = {sid for b in plan['page_batches'] if b['round_id'] == round_id for sid in b['spec_ids']}
+    closure, pending = set(members), list(members)
+    while pending:
+        for parent in edges[pending.pop()]:
+            if parent not in closure:
+                closure.add(parent)
+                pending.append(parent)
+    semantic = ('page_id', 'feature_refs', 'scope', 'evidence_refs', 'requires', 'provides', 'checks')
+    needed_features = {f for sid in closure for f in specs[sid]['feature_refs']}
+    payload = {'round': {k: item[k] for k in ('round_id', 'kind', 'milestone', 'goal', 'goal_checks')}, 'members': sorted(members), 'specs': [{k: specs[sid][k] for k in ('spec_id', *semantic)} for sid in sorted(closure)], 'features': [{k: feature.get(k) for k in ('feature_id', 'required_scope', 'acceptance', 'source_refs', 'origin')} for feature in sorted(features['features'], key=lambda f: f['feature_id']) if feature['feature_id'] in needed_features]}
+    if features['schema'] == 'd2h-feature-plan/v2':
+        payload['scope_refs'] = {sid: specs[sid].get('scope_refs') for sid in sorted(closure)}
+        keys = {(ref['feature_id'], ref['scope_id']) for sid in closure for ref in specs[sid].get('scope_refs', [])}
+        payload['scope_items'] = [{'feature_id': f['feature_id'], **item} for f in features['features'] for item in f['scope_items'] if (f['feature_id'], item['scope_id']) in keys]
+    if plan.get('work_packet_policy') == 'required-v1':
+        payload['work_packets'] = {sid: {'brief': specs[sid].get('implementation_brief'), 'layers': specs[sid]['testing'].get('layers')} for sid in sorted(closure)}
+        payload['shared_contracts'] = [c for c in plan.get('shared_contracts', []) if set([c['producer_spec_id'], *c['consumer_spec_ids']]) & closure]
+    return hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+
+
+def relevant_specs(plan, initial, edges):
+    """A required round goal cannot be delivered with only half its membership."""
+    if not enabled(plan):
+        return initial
+    rounds = {r['round_id']: r for r in plan['rounds']}
+    result = set(initial)
+    while True:
+        before = set(result)
+        touched = {b['round_id'] for b in plan['page_batches'] if set(b['spec_ids']) & result}
+        required_rounds = {rid for rid, item in rounds.items() if any(item['milestone'] == rounds[target]['milestone'] and item['order'] <= rounds[target]['order'] for target in touched)}
+        result.update(s for b in plan['page_batches'] if b['round_id'] in required_rounds for s in b['spec_ids'])
+        result.update(parent for sid in list(result) for parent in edges[sid])
+        if result == before:
+            return result
+
+
+def batch_sequence(plan, edges):
+    batches = {b['batch_id']: b for b in plan['page_batches']}
+    owner = {sid: bid for bid, b in batches.items() for sid in b['spec_ids']}
+    result = []
+    for round_plan in plan['rounds']:
+        remaining = {bid for bid, b in batches.items() if b['round_id'] == round_plan['round_id']}
+        while remaining:
+            layer = sorted(bid for bid in remaining if not any(owner[parent] in remaining and owner[parent] != bid for sid in batches[bid]['spec_ids'] for parent in edges[sid]))
+            require(layer, 'invalid page batch order')
+            result.extend(layer)
+            remaining.difference_update(layer)
+    return result
+
+
+def schedule(plan, features, state, view, edges, evidence_valid):
+    if not enabled(plan):
+        return view
+    specs = {s['spec_id']: s for s in plan['specs']}
+    rounds = {r['round_id']: r for r in plan['rounds']}
+    batches = {b['batch_id']: b for b in plan['page_batches']}
+    batch_order = {bid: index for index, bid in enumerate(batch_sequence(plan, edges))}
+    rows = view['tasks']
+    relevant = set(view['relevant_specs'])
+    round_rows = {}
+    for rid, item in rounds.items():
+        members = sorted(s for b in batches.values() if b['round_id'] == rid for s in b['spec_ids'])
+        signature = round_signature(plan, features, rid, edges)
+        proofs = [p for p in state.get('round_deliveries', []) if p['round_id'] == rid and p['signature'] == signature and evidence_valid(p['evidence'], p['candidate'])]
+        current = any(p['candidate'] == state['candidate'] for p in proofs) and all(rows[s]['accepted'] for s in members)
+        round_rows[rid] = {'order': item['order'], 'kind': item['kind'], 'goal': item['goal'], 'milestone': item['milestone'], 'spec_ids': members, 'delivered': bool(proofs), 'current_accepted': current, 'relevant': bool(set(members) & relevant)}
+    current_round = next((rid for rid, item in round_rows.items() if item['relevant'] and not item['delivered']), None)
+    active = state.get('active_batch')
+    if active:
+        require(active['batch_id'] in batches and set(active['spec_ids']) <= set(batches[active['batch_id']]['spec_ids']), 'active batch no longer matches plan; pause before revision')
+    old_ready = list(view['ready'])
+    stage_ready = [s for s in old_ready if any(b['round_id'] == current_round and s in b['spec_ids'] for b in batches.values())]
+    ranks = {'later': 0, 'normal': 1, 'must': 2}
+    last_page = state.get('batch_runs', [{}])[-1].get('page_id') if state.get('batch_runs') else None
+    batch_rows = {}
+    for bid, batch in batches.items():
+        members = batch['spec_ids']
+        potential = {s for s in members if state['tasks'][s]['implementation'] == 'planned' and not rows[s]['external_blockers'] and not rows[s].get('readiness_gaps') and s in relevant}
+        # Internal unverified prerequisites can be prepared in the same lease, but
+        # a blocked external dependency must never be hidden by grouping.
+        while True:
+            kept = {s for s in potential if set(rows[s]['blocked_by']) <= potential}
+            if kept == potential:
+                break
+            potential = kept
+        rank = max((ranks[rows[s]['effective_priority']] for s in potential), default=-1)
+        core = {s for s in potential if ranks[rows[s]['effective_priority']] == rank}
+        optional = potential - core
+        outside = [s for s in stage_ready if s not in members]
+        optional_hours = sum(specs[s]['effort']['expected'] for s in optional)
+        min_optional_rank = min((ranks[rows[s]['effective_priority']] for s in optional), default=rank)
+        higher_outside = any(ranks[rows[s]['effective_priority']] > min_optional_rank for s in outside)
+        selected = core | (optional if optional_hours <= batch['opportunistic_hours'] and not higher_outside else set())
+        # Keep deterministic dependency order within the fixed dispatch window.
+        selected_order, remaining = [], set(selected)
+        while remaining:
+            layer = sorted((s for s in remaining if not set(edges[s]) & remaining), key=lambda s: (-ranks[rows[s]['effective_priority']], s))
+            require(layer, 'invalid internal batch order')
+            selected_order.extend(layer)
+            remaining.difference_update(layer)
+        eligible = bool(set(selected_order) & set(stage_ready)) and batch['round_id'] == current_round and not active and not view['running'] and not view['validation_debt']['backpressure']
+        highest = [s for s in selected_order if ranks[rows[s]['effective_priority']] == rank]
+        critical = max((view['remaining_path_hours'][s] for s in highest), default=0)
+        shared = max((len(rows[s]['inherited_from']) for s in highest), default=0)
+        effort = sum(specs[s]['effort']['expected'] for s in selected_order)
+        score = sum(rows[s]['value_score'] for s in selected_order) / effort if effort else 0
+        batch_rows[bid] = {'page_id': batch['page_id'], 'round_id': batch['round_id'], 'goal': batch['goal'], 'spec_ids': list(members), 'dispatchable_spec_ids': selected_order, 'deferred_spec_ids': sorted(potential - set(selected_order)), 'eligible': eligible, 'accepted': all(rows[s]['accepted'] for s in members), 'implemented': all(state['tasks'][s]['implementation'] == 'implemented' for s in members), 'blocked_by': sorted({p for s in members for p in rows[s]['blocked_by'] if p not in members}), 'external_blockers': sorted({p for s in members for p in rows[s]['external_blockers']}), 'effective_priority_rank': rank, 'critical_hours': critical, 'shared_unlocks': shared, 'page_affinity': int(batch['page_id'] == last_page), 'priority_index': score, 'estimated_worker_hours': effort, 'planned_worker_hours': sum(specs[s]['effort']['expected'] for s in members)}
+    ordered_batches = [bid for bid, item in batch_rows.items() if item['eligible']]
+    ordered_batches.sort(key=lambda b: (-batch_rows[b]['effective_priority_rank'], -batch_rows[b]['critical_hours'], -batch_rows[b]['shared_unlocks'], -batch_rows[b]['page_affinity'], -batch_rows[b]['priority_index'], b))
+    page_rows = {}
+    for page in plan['pages']:
+        pid = page['page_id']
+        passes = [b for b in batches.values() if b['page_id'] == pid]
+        passes.sort(key=lambda b: batch_order[b['batch_id']])
+        first_order = rounds[passes[0]['round_id']]['order'] if passes else None
+        baseline_specs = {s for b in passes if rounds[b['round_id']]['order'] == first_order for s in b['spec_ids']}
+        all_specs = {s for b in passes for s in b['spec_ids']}
+        page_rows[pid] = {'scope_complete': page['scope_complete'], 'baseline_verified': bool(baseline_specs) and all(rows[s]['accepted'] for s in baseline_specs), 'complete': page['scope_complete'] and bool(all_specs) and all(rows[s]['accepted'] for s in all_specs), 'passes': [{'page_pass': i, 'round_id': b['round_id'], 'batch_id': b['batch_id'], 'spec_ids': list(b['spec_ids']), 'accepted': batch_rows[b['batch_id']]['accepted']} for i, b in enumerate(passes, 1)]}
+    view.update(rounds=round_rows, current_round=current_round, page_batches=batch_rows, ready_batches=ordered_batches, active_batch=active, pages=page_rows, ready_specs=stage_ready)
+    runs = state.get('batch_runs', [])
+    view['page_dispatch_metrics'] = {'finished_windows': sum(r['result'] == 'completed' for r in runs), 'paused_windows': sum(r['result'] == 'paused' for r in runs), 'page_switches': sum(a['page_id'] != b['page_id'] for a, b in zip(runs, runs[1:])), 'average_specs_per_window': sum(len(r['spec_ids']) for r in runs) / len(runs) if runs else None}
+    view['ready'] = [s for s in stage_ready if active and s in active['spec_ids']]
+    relevant_rounds = [r for r in round_rows.values() if r['relevant']]
+    view['milestone_accepted'] = view['milestone_accepted'] and all(r['current_accepted'] for r in relevant_rounds)
+    return view

package/workflow/spec_generation.py

@@ -0,0 +1,120 @@
+"""Bind selected, detailed Spec blocks to per-member planning inputs (not acceptance)."""
+import hashlib
+import json
+import re
+from pathlib import Path
+
+POLICY = 'required-v1'
+SCHEMA = 'd2h-spec-generation/v1'
+HEADINGS = ('页面范围', '开发顺序', '页面功能', 'UI 操作与验收', 'Android 证据', 'HarmonyOS 实现范围', '未决项与平台差异')
+
+
+def digest(value):
+    return hashlib.sha256(value.encode('utf-8')).hexdigest()
+
+
+def canonical(value):
+    return json.dumps(value, sort_keys=True, ensure_ascii=False)
+
+
+def signature(plan, features, spec):
+    page = next(p for p in plan['pages'] if p['page_id'] == spec['page_id'])
+    feature_map = {f['feature_id']: f for f in features['features']}
+    scopes = []
+    for ref in spec.get('scope_refs', []):
+        feature = feature_map[ref['feature_id']]
+        scopes.append({'feature_id': feature['feature_id'],
+                       'scope': next(s for s in feature['scope_items'] if s['scope_id'] == ref['scope_id']),
+                       'source': feature.get('source'), 'origin': feature.get('origin'), 'source_refs': feature.get('source_refs'),
+                       'acceptance': feature.get('acceptance'), 'scope_status': feature['scope_status'],
+                       'needs_clarification': feature['needs_clarification']})
+    if not scopes:
+        scopes = [feature_map[f] for f in spec['feature_refs']]
+    contracts = [c for c in plan.get('shared_contracts', []) if spec['spec_id'] in [c['producer_spec_id'], *c['consumer_spec_ids']]]
+    # Global revisions and unrelated scopes are deliberately excluded; actual member changes are not.
+    semantic_spec = {k: spec.get(k) for k in ('spec_id', 'page_id', 'feature_refs', 'scope_refs', 'scope', 'evidence_refs', 'requires', 'provides', 'checks', 'implementation_brief', 'allocation')}
+    semantic_spec['testing'] = {k: v for k, v in spec['testing'].items() if k != 'estimated_hours'}
+    return digest(canonical({'spec': semantic_spec, 'package': page['package'], 'scopes': scopes,
+                             'shared_contracts': contracts, 'work_packet_policy': plan.get('work_packet_policy')}))
+
+
+def document(plan, root, spec):
+    if root is None:
+        raise ValueError('generation root required')
+    root = Path(root).resolve()
+    page = next(p for p in plan['pages'] if p['page_id'] == spec['page_id'])
+    directory = root / page['package']
+    file = directory / 'spec.md'
+    if directory.is_symlink() or file.is_symlink() or not file.is_file() or file.resolve().parent != directory:
+        raise ValueError('local detailed spec.md required')
+    text = file.read_text(encoding='utf-8')
+    sid = spec['spec_id']
+    start, end = f'<!-- d2h-spec:start {sid} -->', f'<!-- d2h-spec:end {sid} -->'
+    if text.count(start) != 1 or text.count(end) != 1 or text.index(start) >= text.index(end):
+        raise ValueError('unique ordered Spec block markers required')
+    body = text.split(start, 1)[1].split(end, 1)[0]
+    if '<!-- d2h-spec:' in body:
+        raise ValueError('Spec blocks cannot be nested')
+    if not all(check in body for check in spec['checks']):
+        raise ValueError('all planned check IDs must occur in detailed block')
+    pattern = re.compile(r'<!-- d2h-spec:start ([^\r\n]+?) -->.*?<!-- d2h-spec:end \1 -->', re.S)
+    members = pattern.findall(text)
+    context = pattern.sub('', text)
+    if len(set(members)) != len(members) or '<!-- d2h-spec:' in context:
+        raise ValueError('all member blocks must have unique, ordered matching boundaries')
+    # All seven shared sections remain in the original layout, including sections after UI checks.
+    # Adding another member may add empty separator lines, not change shared behavior.
+    context = '\n'.join(line.rstrip() for line in context.splitlines() if line.strip())
+    if not all('## ' + heading in context for heading in HEADINGS):
+        raise ValueError('seven shared Spec sections required outside member blocks')
+    return {'context_sha256': digest(context), 'body_sha256': digest(body)}
+
+
+def manifest(root):
+    path = Path(root) / 'generation.json'
+    if path.is_symlink():
+        raise ValueError('generation manifest cannot be linked')
+    if not path.exists():
+        return {'schema': SCHEMA, 'specs': {}}
+    data = json.loads(path.read_text(encoding='utf-8'))
+    if not isinstance(data, dict) or data.get('schema') != SCHEMA or not isinstance(data.get('specs'), dict):
+        raise ValueError('generation manifest schema mismatch')
+    return data
+
+
+def gaps(plan, features, spec, root):
+    if plan.get('spec_generation_policy') != POLICY:
+        return []
+    try:
+        if root is None:
+            raise ValueError('generation root required')
+        recorded = manifest(root)['specs'].get(spec['spec_id'], {})
+        if not isinstance(recorded, dict):
+            raise ValueError('generation entry must be an object')
+        current = {**document(plan, root, spec), 'input_sha256': signature(plan, features, spec)}
+        if any(recorded.get(key) != value for key, value in current.items()):
+            raise ValueError('detailed Spec absent, changed or bound to stale planning inputs')
+        return []
+    except (OSError, ValueError, KeyError, TypeError, StopIteration) as error:
+        return ['spec generation: ' + str(error)]
+
+
+def record(plan, features, root, spec_ids, expected_hash):
+    if plan.get('spec_generation_policy') != POLICY:
+        raise ValueError('generation requires explicit spec_generation_policy=required-v1')
+    if expected_hash != digest(canonical(plan)):
+        raise ValueError('generation plan hash mismatch; re-read selected revision')
+    specs = {s['spec_id']: s for s in plan['specs']}
+    if not spec_ids or len(set(spec_ids)) != len(spec_ids) or not set(spec_ids) <= specs.keys():
+        raise ValueError('explicit unique known spec IDs required')
+    result = manifest(root)
+    for sid in spec_ids:
+        result['specs'][sid] = {**document(plan, root, specs[sid]),
+                                'input_sha256': signature(plan, features, specs[sid]),
+                                'plan_revision': plan['revision'], 'plan_sha256': expected_hash}
+    return result
+
+
+def proof(root, sid):
+    entry = manifest(root)['specs'][sid]
+    return {key: entry[key] for key in ('input_sha256', 'context_sha256', 'body_sha256')}