@harmonyos-arkts/d2h 0.1.20 → 0.1.22

package/workflow/spec_runtime.py

@@ -0,0 +1,890 @@
+#!/usr/bin/env python3
+"""Validate AI-authored incremental plans and enforce explicit execution contracts."""
+import argparse
+import copy
+import hashlib
+import importlib.util
+import json
+import math
+import os
+from pathlib import Path
+import tempfile
+import sys
+from datetime import datetime, timezone
+
+sys.dont_write_bytecode = True
+
+SCHEMA = 'd2h-page-plan/v2'
+PRIORITY = {'later': 0, 'normal': 1, 'must': 2}
+WEIGHTS = {'milestone': 6, 'unlock': 5, 'user_value': 4, 'risk_reduction': 3, 'feedback': 2}
+
+_batch_spec = importlib.util.spec_from_file_location('page_batches', Path(__file__).with_name('page_batches.py'))
+page_batches = importlib.util.module_from_spec(_batch_spec)
+_batch_spec.loader.exec_module(page_batches)
+
+_packet_spec = importlib.util.spec_from_file_location('work_packets', Path(__file__).with_name('work_packets.py'))
+work_packets = importlib.util.module_from_spec(_packet_spec)
+_packet_spec.loader.exec_module(work_packets)
+
+_generation_spec = importlib.util.spec_from_file_location('spec_generation', Path(__file__).with_name('spec_generation.py'))
+spec_generation = importlib.util.module_from_spec(_generation_spec)
+_generation_spec.loader.exec_module(spec_generation)
+
+_delivery_spec = importlib.util.spec_from_file_location('delivery_view', Path(__file__).with_name('delivery_view.py'))
+delivery_view = importlib.util.module_from_spec(_delivery_spec)
+_delivery_spec.loader.exec_module(delivery_view)
+
+_overview_spec = importlib.util.spec_from_file_location('dashboard_overview', Path(__file__).with_name('dashboard_overview.py'))
+dashboard_overview = importlib.util.module_from_spec(_overview_spec)
+_overview_spec.loader.exec_module(dashboard_overview)
+
+
+def demand(value, message):
+    if not value:
+        raise ValueError(message)
+
+
+def nonempty(value):
+    return isinstance(value, str) and bool(value.strip())
+
+
+def strings(value, label, required=False):
+    demand(isinstance(value, list) and (not required or value) and all(nonempty(v) for v in value), f'{label}: expected string array')
+    demand(len(set(value)) == len(value), f'{label}: duplicate values')
+    return value
+
+
+def number(value, label, positive=False):
+    demand(type(value) in (int, float) and math.isfinite(value) and (value > 0 if positive else value >= 0), f'{label}: invalid number')
+    return value
+
+
+def fingerprint(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+
+
+def file_hash(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def stamp():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def parse_time(value):
+    parsed = datetime.fromisoformat(value)
+    demand(parsed.tzinfo is not None, 'timestamps require timezone')
+    return parsed
+
+
+def indexed(items, key):
+    demand(isinstance(items, list), f'{key}: expected records')
+    result = {}
+    for item in items:
+        demand(isinstance(item, dict) and nonempty(item.get(key)), f'{key}: missing ID')
+        demand(item[key] not in result, f'{key}: duplicate {item[key]}')
+        result[item[key]] = item
+    return result
+
+
+def feature_validator():
+    path = Path(__file__).with_name('feature_plan.py')
+    spec = importlib.util.spec_from_file_location('feature_validation', path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.validate
+
+
+def scope_owners(plan, features):
+    """Every authorized atomic requirement has one implementation owner and check mapping."""
+    if features['schema'] != 'd2h-feature-plan/v2':
+        return None
+    items = {(f['feature_id'], i['scope_id']): (f, i) for f in features['features'] for i in f['scope_items']}
+    owners = {}
+    for spec in plan['specs']:
+        refs = spec.get('scope_refs')
+        demand(isinstance(refs, list) and refs, f"{spec['spec_id']}: scope_refs required for v2 features")
+        referenced = set()
+        mapped_checks = set()
+        for ref in refs:
+            demand(isinstance(ref, dict), 'invalid scope reference')
+            key = (ref.get('feature_id'), ref.get('scope_id'))
+            demand(key in items, 'unknown scope reference')
+            demand(key not in owners, 'scope item has duplicate Spec owners; split the requirement upstream')
+            feature, item = items[key]
+            demand(key[0] in spec['feature_refs'], 'scope reference outside feature_refs')
+            demand(feature['scope_status'] == 'included' and not feature['needs_clarification'] and item['status'] == 'included' and item['milestone'] == spec['milestone'], 'scope item not authorized for this milestone')
+            checks = strings(ref.get('checks'), 'scope checks', True)
+            demand(set(checks) <= set(spec['checks']), 'scope checks outside Spec checks')
+            mapped_checks.update(checks)
+            referenced.add(key[0])
+            owners[key] = spec['spec_id']
+        demand(referenced == set(spec['feature_refs']), 'every feature_ref needs a scope reference')
+        demand(mapped_checks == set(spec['checks']), 'every Spec check needs a scope mapping')
+    for key, (feature, item) in items.items():
+        authorized = feature['scope_status'] == 'included' and not feature['needs_clarification'] and item['status'] == 'included' and item['milestone'] != 'unassigned'
+        demand(not authorized or key in owners, f'{key}: authorized scope item needs a Spec')
+    return owners
+
+
+def scope_progress(plan, features, view):
+    owners = scope_owners(plan, features)
+    if owners is None:
+        view.update(scope_tracking=False, feature_progress={}, scope_coverage_accepted=False)
+        view['delivery_progress'] = delivery_view.progress(features, view)
+        return view
+    progress = {}
+    for feature in features['features']:
+        items = []
+        for item in feature['scope_items']:
+            owner = owners.get((feature['feature_id'], item['scope_id']))
+            excluded = feature['scope_status'] == 'excluded' or item['status'] == 'excluded'
+            accepted = bool(owner and view['tasks'][owner]['accepted'])
+            items.append(dict(item, spec_id=owner, accepted=accepted, resolved=excluded or accepted))
+        remaining = [i['scope_id'] for i in items if not i['resolved']]
+        progress[feature['feature_id']] = {'complete': not remaining, 'remaining_scope_ids': remaining, 'items': items}
+    view.update(scope_tracking=True, feature_progress=progress, scope_coverage_accepted=all(f['complete'] for f in progress.values()))
+    if 'pages' in view:
+        for pid, row in view['pages'].items():
+            related = {fid for spec in plan['specs'] if spec['page_id'] == pid for fid in spec['feature_refs']}
+            row['complete'] = row['complete'] and all(progress[f]['complete'] for f in related)
+    view['delivery_progress'] = delivery_view.progress(features, view)
+    return view
+
+
+def validate(plan, features, root=None):
+    demand(isinstance(plan, dict) and plan.get('schema_version') == SCHEMA, 'v2 plan required; v1 must be explicitly reconciled by AI, not reinterpreted')
+    errors = feature_validator()(features)
+    demand(not errors, '; '.join(errors))
+    demand(type(plan.get('revision')) is int and plan['revision'] > 0, 'positive plan revision required')
+    source = plan.get('feature_source', {})
+    demand(source.get('revision') == features['revision'] and source.get('sha256') == fingerprint(features), 'feature source revision/hash mismatch')
+    demand(nonempty(source.get('path')) and Path(source['path']).is_absolute(), 'feature source path must be absolute')
+    milestone_ids = [m['milestone_id'] for m in features['milestones']]
+    demand(plan.get('milestone') in milestone_ids, 'active milestone not declared')
+    feature_map = {f['feature_id']: f for f in features['features']}
+    pages = indexed(plan.get('pages'), 'page_id')
+    specs = indexed(plan.get('specs'), 'spec_id')
+    demand(bool(specs), 'at least one spec required')
+    retired = indexed(plan.get('retired_specs', []), 'spec_id')
+    demand(not specs.keys() & retired.keys(), 'retired spec cannot also be active')
+    for retired_spec in retired.values():
+        demand(nonempty(retired_spec.get('reason')), 'retired spec needs explicit reason')
+    demand(plan.get('spec_generation_policy') in (None, spec_generation.POLICY), 'unsupported spec_generation_policy')
+    for page in pages.values():
+        package = page.get('package')
+        demand(nonempty(package) and package not in {'.', '..'} and '/' not in package and '\\' not in package, 'page package must be one stable directory')
+        if root:
+            directory = (Path(root) / package).resolve()
+            demand(directory.parent == Path(root).resolve(), 'page package escapes output root')
+            spec_file = directory / 'spec.md'
+            if plan.get('spec_generation_policy') == spec_generation.POLICY and not directory.exists():
+                continue
+            demand(directory.is_dir() and spec_file.is_file() and spec_file.resolve().parent == directory and {p.name for p in directory.iterdir()} == {'spec.md'}, 'page package must contain only a local spec.md file')
+    demand(len({p['package'] for p in pages.values()}) == len(pages), 'duplicate page package')
+    providers, edges, coverage = {}, {}, set()
+    all_checks = set()
+    for sid, item in specs.items():
+        demand(item.get('page_id') in pages, f'{sid}: unknown page')
+        refs = strings(item.get('feature_refs'), f'{sid}.feature_refs', True)
+        demand(set(refs) <= feature_map.keys(), f'{sid}: unknown feature')
+        demand(item.get('milestone') in milestone_ids, f'{sid}: unknown milestone')
+        demand(all((features['schema'] == 'd2h-feature-plan/v2' or feature_map[f]['milestone'] == item['milestone']) and feature_map[f]['scope_status'] == 'included' and not feature_map[f]['needs_clarification'] for f in refs), f'{sid}: scope not authorized or unresolved; return to feature planning')
+        coverage.update(refs)
+        strings(item.get('scope'), f'{sid}.scope', True)
+        strings(item.get('evidence_refs'), f'{sid}.evidence_refs', True)
+        checks = strings(item.get('checks'), f'{sid}.checks', True)
+        demand(not all_checks & set(checks), f'{sid}: checks must be globally unique')
+        all_checks.update(checks)
+        testing = item.get('testing', {})
+        immediate = strings(testing.get('immediate'), f'{sid}.immediate')
+        batch = strings(testing.get('batch'), f'{sid}.batch')
+        demand(not set(immediate) & set(batch) and set(immediate + batch) == set(checks), f'{sid}: checks must partition into immediate and batch')
+        risk = testing.get('risk_dimensions', {})
+        demand(set(risk) == {'impact', 'shared', 'uncertainty', 'dependency'}, f'{sid}: four risk dimensions required')
+        demand(all(type(v) is int and 0 <= v <= 3 for v in risk.values()), f'{sid}: risk ratings must be 0..3')
+        triggers = strings(testing.get('triggers'), f'{sid}.triggers')
+        demand(set(triggers) <= {'data-loss', 'authentication', 'startup', 'shared-contract'}, f'{sid}: unknown risk trigger')
+        if triggers or sum(risk.values()) >= 8:
+            demand(set(immediate) == set(checks), f'{sid}: high risk requires immediate checks')
+        demand(testing.get('latest_validation_point') == item['milestone'], f'{sid}: validation deadline must be its milestone')
+        number(testing.get('estimated_hours'), f'{sid}.test hours', True)
+        score = item.get('ratings', {})
+        demand(set(score) == set(WEIGHTS) and all(type(v) is int and 0 <= v <= 5 for v in score.values()), f'{sid}: ratings must be five 0..5 integers')
+        effort = item.get('effort', {})
+        for name in ('low', 'expected', 'high', 'remaining_elapsed_hours'):
+            number(effort.get(name), f'{sid}.effort.{name}', True)
+        demand(effort['low'] <= effort['expected'] <= effort['high'], f'{sid}: invalid effort interval')
+        demand(effort.get('confidence') in {'low', 'medium', 'high'}, f'{sid}: confidence required')
+        allocation = item.get('allocation', {})
+        demand(type(allocation.get('recommended_workers')) is int and allocation['recommended_workers'] >= 1, f'{sid}: worker recommendation required')
+        demand(nonempty(allocation.get('rationale')), f'{sid}: allocation rationale required')
+        strings(allocation.get('owned_paths'), f'{sid}.owned_paths', True)
+        requires = strings(item.get('requires'), f'{sid}.requires')
+        provides = item.get('provides')
+        demand(isinstance(provides, list), f'{sid}: provides must be array')
+        for cap in provides:
+            demand(isinstance(cap, dict) and nonempty(cap.get('capability')), f'{sid}: invalid capability')
+            name = cap['capability']
+            demand(name not in providers, f'duplicate capability provider: {name}')
+            needed = strings(cap.get('checks'), f'{sid}.{name}.checks', True)
+            demand(set(needed) <= set(immediate), f'{sid}: provided capabilities require immediate contract checks')
+            providers[name] = sid
+        edges[sid] = []
+    dispositions = indexed(plan.get('dispositions'), 'feature_id')
+    for fid, disposition in dispositions.items():
+        demand(fid in feature_map and fid not in coverage, 'disposition must refer to uncovered known feature')
+        demand(nonempty(disposition.get('reason')), 'disposition reason required')
+        demand((features['schema'] == 'd2h-feature-plan/v2' and not any(i['status'] == 'included' and i['milestone'] != 'unassigned' for i in feature_map[fid]['scope_items'])) or feature_map[fid]['scope_status'] != 'included' or feature_map[fid]['milestone'] == 'unassigned' or feature_map[fid]['needs_clarification'], 'authorized included feature cannot be silently omitted')
+    scope_owners(plan, features)
+    demand(coverage | dispositions.keys() == feature_map.keys(), 'all features need specs or explicit upstream disposition')
+    for sid, item in specs.items():
+        for cap in item['requires']:
+            demand(cap in providers, f'{sid}: missing capability provider: {cap}')
+            provider = providers[cap]
+            demand(provider != sid, f'{sid}: self dependency')
+            demand(milestone_ids.index(specs[provider]['milestone']) <= milestone_ids.index(item['milestone']), f'{sid}: dependency requires later milestone; return scope conflict upstream')
+            edges[sid].append(provider)
+        for fid in item['feature_refs']:
+            for preceding in features['features']:
+                if fid in preceding['requested_before']:
+                    edges[sid].extend(other for other, value in specs.items() if preceding['feature_id'] in value['feature_refs'] and other != sid and (features['schema'] != 'd2h-feature-plan/v2' or value['milestone'] == item['milestone']))
+    # Deduplicate shared edges; reject combined explicit order + capability cycles.
+    edges = {key: sorted(set(value)) for key, value in edges.items()}
+    ordered, remaining = [], set(specs)
+    while remaining:
+        layer = sorted(s for s in remaining if not set(edges[s]) & remaining)
+        demand(layer, 'dependency/order cycle: ' + ', '.join(sorted(remaining)))
+        ordered.extend(layer)
+        remaining.difference_update(layer)
+    policy = plan.get('validation_policy', {})
+    for key in ('max_pending_specs', 'max_pending_hours', 'max_age_hours'):
+        number(policy.get(key), key, True)
+    demand(type(policy['max_pending_specs']) is int, 'max_pending_specs must be integer')
+    demand(plan.get('implementation_workers') == 1, 'only one implementation worker supported in this version')
+    work_packets.validate(plan, specs, demand, strings)
+    page_batches.validate(plan, features, specs, edges)
+    return specs, providers, edges, ordered
+
+
+def init_state(plan, features):
+    specs, _, _, _ = validate(plan, features)
+    return {'schema': 'd2h-spec-execution/v1', 'plan_hash': fingerprint(plan), 'plan_revision': plan['revision'], 'feature_hash': fingerprint(features), 'candidate': None, 'tasks': {sid: {'implementation': 'planned', 'validation': 'not_ready', 'acceptance': 'pending', 'evidence': [], 'external_blockers': [], 'metrics': {}} for sid in specs}, 'events': [], 'history': [], 'milestone_evidence': [], 'active_batch': None, 'batch_runs': [], 'round_deliveries': []}
+
+
+def current_evidence(task, candidate):
+    def intact(evidence):
+        try:
+            return all(Path(evidence[key]['path']).is_file() and file_hash(evidence[key]['path']) == evidence[key]['sha256'] for key in ('artifact', 'hap'))
+        except (KeyError, OSError, TypeError):
+            return False
+    return [e for e in task['evidence'] if e['candidate'] == candidate and intact(e)]
+
+
+def passed(task, candidate):
+    return {check for e in current_evidence(task, candidate) if e['kind'] == 'test' for check in e['checks']}
+
+
+def has_build(task, candidate):
+    return any(e['kind'] == 'build' for e in current_evidence(task, candidate))
+
+
+def build_hash(task, candidate):
+    return next((e['hap']['sha256'] for e in reversed(current_evidence(task, candidate)) if e['kind'] == 'build'), None)
+
+
+def assessment(item, task):
+    metrics = task['metrics']
+    categories = ('implementation_hours', 'test_hours', 'coordination_hours', 'rework_hours')
+    actual = sum(metrics[k] for k in categories) if all(type(metrics.get(k)) in (int, float) for k in categories) else None
+    result = {'expected_worker_hours': item['effort']['expected'], 'actual_worker_hours': actual, 'effort_ratio': actual / item['effort']['expected'] if actual is not None else None}
+    for key in ('coordination_hours', 'rework_hours', 'context_hours', 'repeated_analysis_hours'):
+        result[key.replace('_hours', '_share')] = metrics[key] / actual if actual and type(metrics.get(key)) in (int, float) else None
+    elapsed, waiting = metrics.get('elapsed_hours'), metrics.get('waiting_hours')
+    result['waiting_share'] = waiting / elapsed if type(elapsed) in (int, float) and elapsed > 0 and type(waiting) in (int, float) else None
+    result['first_pass'] = metrics.get('first_pass')
+    result['conflicts'] = metrics.get('conflicts')
+    return result
+
+
+def derive(plan, features, state, now=None, root=None):
+    specs, providers, edges, order = validate(plan, features)
+    demand(state.get('schema') == 'd2h-spec-execution/v1' and state.get('plan_hash') == fingerprint(plan) and state.get('feature_hash') == fingerprint(features), 'execution baseline mismatch; reconcile revision explicitly')
+    demand(set(state['tasks']) == set(specs), 'execution task set mismatch')
+    now = now or datetime.now(timezone.utc)
+    feature_map = {f['feature_id']: f for f in features['features']}
+    active = {s for s, item in specs.items() if item['milestone'] == plan['milestone']}
+    closure = set(active)
+    for sid in reversed(order):
+        if sid in closure:
+            closure.update(edges[sid])
+    closure = page_batches.relevant_specs(plan, closure, edges)
+    ranks = {s: max(PRIORITY[feature_map[f]['user_priority']] for f in specs[s]['feature_refs']) for s in specs}
+    inherited = {s: set() for s in specs}
+    cap_ready = dict.fromkeys(providers, False)
+    ready_specs = set()
+    debt, debt_hours, ages = [], 0, []
+    rows = {}
+    accepted = {}
+    for sid in order:
+        item = specs[sid]
+        task = state['tasks'][sid]
+        checks = passed(task, state['candidate'])
+        consumer_hap = build_hash(task, state['candidate'])
+        blocked = [providers[c] for c in item['requires'] if not cap_ready[c] or (consumer_hap is not None and build_hash(state['tasks'][providers[c]], state['candidate']) != consumer_hap)]
+        ordered_features = {f['feature_id'] for f in features['features'] if set(f['requested_before']) & set(item['feature_refs'])}
+        ordered_blockers = [p for p in edges[sid] if set(specs[p]['feature_refs']) & ordered_features and not accepted.get(p, False)]
+        blocked = sorted(set(blocked + ordered_blockers))
+        gaps = work_packets.readiness_gaps(plan, item) + spec_generation.gaps(plan, features, item, root)
+        if plan.get('spec_generation_policy') == spec_generation.POLICY and task['implementation'] != 'planned' and not gaps:
+            if task.get('spec_generation') != spec_generation.proof(root, sid):
+                gaps.append('spec generation: running/implemented work uses different detailed content; invalidate and repair')
+        missing_interfaces = [cap['capability'] for cap in item['provides'] if not work_packets.interface_ready(plan, task, cap['capability'], state['candidate'], file_hash)]
+        interfaces_ready = not missing_interfaces
+        if task['implementation'] == 'implemented' and not gaps and interfaces_ready and not blocked and not task['external_blockers'] and has_build(task, state['candidate']) and set(item['testing']['immediate']) <= checks:
+            ready_specs.add(sid)
+        for cap in item['provides']:
+            cap_ready[cap['capability']] = sid in ready_specs and set(cap['checks']) <= checks
+        complete = sid in ready_specs and not blocked and set(item['checks']) <= checks and task.get('reviewed_candidate') == state['candidate']
+        accepted[sid] = complete
+        if task['implementation'] == 'implemented' and not complete:
+            debt.append(sid)
+            debt_hours += item['testing']['estimated_hours']
+            ages.append((now - parse_time(task.get('pending_since', task['implemented_at']))).total_seconds() / 3600)
+        value = sum(item['ratings'][k] * w for k, w in WEIGHTS.items())
+        rows[sid] = {'effective_priority': next(k for k, v in PRIORITY.items() if v == ranks[sid]), 'inherited_from': sorted(inherited[sid]), 'blocked_by': blocked, 'external_blockers': task['external_blockers'], 'capabilities_ready': [c['capability'] for c in item['provides'] if cap_ready[c['capability']]], 'value_score': value, 'priority_index': value / item['effort']['expected'], 'assessment': assessment(item, task), 'accepted': complete, 'immediate_passed': sid in ready_specs, 'missing_checks': sorted(set(item['checks']) - checks), 'readiness_gaps': gaps, 'missing_interfaces': missing_interfaces, 'work_packet_ready': not gaps, 'eligible': sid in closure and not gaps and not blocked and not task['external_blockers'] and task['implementation'] == 'planned'}
+    for target in sorted(active):
+        if rows[target]['accepted']:
+            continue
+        pending, seen = list(edges[target]), set()
+        while pending:
+            sid = pending.pop()
+            if sid in seen:
+                continue
+            seen.add(sid)
+            inherited[sid].add(target)
+            ranks[sid] = max(ranks[sid], max(PRIORITY[feature_map[f]['user_priority']] for f in specs[target]['feature_refs']))
+            pending.extend(edges[sid])
+    for sid in rows:
+        rows[sid]['effective_priority'] = next(k for k, v in PRIORITY.items() if v == ranks[sid])
+        rows[sid]['inherited_from'] = sorted(inherited[sid])
+    # Longest remaining successor path (calendar time, distinct from worker effort).
+    lengths = {s: 0 if rows[s]['accepted'] else specs[s]['effort']['remaining_elapsed_hours'] for s in specs}
+    for sid in reversed(order):
+        for parent in edges[sid]:
+            if parent in closure and sid in closure:
+                lengths[parent] = max(lengths[parent], (0 if rows[parent]['accepted'] else specs[parent]['effort']['remaining_elapsed_hours']) + lengths[sid])
+    policy = plan['validation_policy']
+    pressure = len(debt) >= policy['max_pending_specs'] or debt_hours >= policy['max_pending_hours'] or any(age >= policy['max_age_hours'] for age in ages)
+    running = [s for s, t in state['tasks'].items() if t['implementation'] == 'in_progress']
+    candidates = [s for s, row in rows.items() if row['eligible']]
+    candidates.sort(key=lambda s: (-ranks[s], -lengths[s], -len(inherited[s]), -rows[s]['priority_index'], s))
+    validation_due = sorted(s for s in debt if not rows[s]['immediate_passed'])
+    regression = any(e['candidate'] == state['candidate'] and e['milestone'] == plan['milestone'] and current_evidence({'evidence': [e['evidence']]}, state['candidate']) for e in state['milestone_evidence'])
+    view = {'tasks': rows, 'relevant_specs': sorted(closure), 'ready': [] if pressure or running else candidates, 'ranked_candidates': candidates, 'validation_due': validation_due, 'validation_debt': {'specs': sorted(debt), 'estimated_hours': debt_hours, 'oldest_hours': max(ages, default=0), 'backpressure': pressure}, 'running': running, 'remaining_path_hours': lengths, 'milestone_regression_passed': regression, 'milestone_accepted': all(rows[s]['accepted'] for s in closure) and bool(active) and regression}
+    return scope_progress(plan, features, page_batches.schedule(plan, features, state, view, edges, lambda evidence, candidate: bool(current_evidence({'evidence': [evidence]}, candidate))))
+
+
+def dispatch_context(plan, features, state, batch_id, root, now=None):
+    """Read-only dispatch snapshot, trimmed to the claimed or eligible window."""
+    view = derive(plan, features, state, now, root)
+    demand(page_batches.enabled(plan), 'context requires page-batches mode')
+    demand(batch_id in view['page_batches'], 'unknown context batch')
+    active = state.get('active_batch')
+    if active:
+        demand(active['batch_id'] == batch_id, 'another batch owns the dispatch window')
+        selected = active['spec_ids']
+    else:
+        demand(batch_id in view['ready_batches'], 'context batch is not eligible')
+        selected = view['page_batches'][batch_id]['dispatchable_spec_ids']
+    batch = next(b for b in plan['page_batches'] if b['batch_id'] == batch_id)
+    page = next(p for p in plan['pages'] if p['page_id'] == batch['page_id'])
+    round_item = next(r for r in plan['rounds'] if r['round_id'] == batch['round_id'])
+    specs = {s['spec_id']: s for s in plan['specs']}
+    providers = {c['capability']: s['spec_id'] for s in plan['specs'] for c in s['provides']}
+    required = sorted({cap for sid in selected for cap in specs[sid]['requires']})
+    result = {'schema': 'd2h-dispatch-context/v1', 'plan_revision': plan['revision'], 'feature_revision': features['revision'], 'plan_hash': fingerprint(plan), 'feature_hash': fingerprint(features), 'candidate': state['candidate'], 'event_sequence': len(state['events']), 'batch_id': batch_id, 'page_id': page['page_id'], 'round_id': round_item['round_id'], 'goal': round_item['goal'], 'page_spec_path': str((Path(root) / page['package'] / 'spec.md').resolve()), 'spec_ids': list(selected), 'members': [{'work_packet': work_packets.packet(plan, specs[sid], state['tasks'][sid], state['candidate'], file_hash), 'readiness_gaps': view['tasks'][sid]['readiness_gaps'], 'spec': copy.deepcopy(specs[sid]), 'implementation': state['tasks'][sid]['implementation'], 'accepted': view['tasks'][sid]['accepted'], 'missing_checks': view['tasks'][sid]['missing_checks']} for sid in selected], 'required_capabilities': [{'capability': cap, 'provider_spec_id': providers[cap], 'current_ready': cap in view['tasks'][providers[cap]]['capabilities_ready'], 'interface': state['tasks'][providers[cap]].get('interfaces', {}).get(cap) if work_packets.interface_ready(plan, state['tasks'][providers[cap]], cap, state['candidate'], file_hash) else None} for cap in required]}
+    result['context_hash'] = fingerprint(result)
+    return result
+
+
+def validate_evidence(evidence, candidate, spec, root):
+    evidence = copy.deepcopy(evidence)
+    demand(evidence.get('kind') in {'build', 'test'}, 'evidence kind must be build/test')
+    demand(nonempty(candidate) and evidence.get('candidate') == candidate, 'evidence candidate mismatch')
+    demand(evidence.get('exit_code') == 0 and type(evidence.get('exit_code')) is int, 'evidence must have successful exit code')
+    command = evidence.get('command')
+    demand(isinstance(command, list) and len(command) >= 3 and command[:3] == ['droid2hmos', evidence['kind'], 'harmony'], 'managed command required')
+    parse_time(evidence.get('timestamp', ''))
+    for name in ('artifact', 'hap'):
+        ref = evidence.get(name, {})
+        path = Path(ref.get('path', ''))
+        if not path.is_absolute():
+            path = root / path
+        demand(path.is_file() and ref.get('sha256') == file_hash(path), f'{name} evidence file/hash mismatch')
+        ref['path'] = str(path.resolve())
+    if evidence['kind'] == 'test':
+        demand(evidence.get('layer', 'device') == 'device', 'only managed device test evidence is supported; local/static evidence needs a CLI adapter')
+        demand(nonempty(evidence.get('device')), 'test device required')
+        demand('--runner' in command and command[command.index('--runner') + 1:command.index('--runner') + 2] == ['python'] and '--test-list' in command, 'managed Python runner/test-list required')
+        checks = strings(evidence.get('checks'), 'evidence checks', True)
+        demand(set(checks) <= set(spec['checks']), 'unknown test checks')
+        counts = evidence.get('counts', {})
+        demand(type(counts.get('executed')) is int and counts['executed'] > 0 and type(counts.get('passed')) is int and counts.get('passed') == counts['executed'] and all(type(counts.get(k)) is int and counts[k] == 0 for k in ('failed', 'errors', 'skipped')), 'nonzero execution and no failed/error/skipped required')
+        strings(evidence.get('managed_evidence'), 'managed evidence refs', True)
+    return evidence
+
+
+def apply_event(plan, features, state, event, root, now=None):
+    state = copy.deepcopy(state)
+    snapshot = derive(plan, features, state, now, root)
+    kind = event.get('type')
+    sid = event.get('spec_id')
+    task = state['tasks'].get(sid)
+    specs = {s['spec_id']: s for s in plan['specs']}
+    if kind == 'start_batch':
+        demand(page_batches.enabled(plan), 'start_batch requires page-batches mode')
+        bid = event.get('batch_id')
+        demand(bid in snapshot['ready_batches'], 'page batch not ready or round gate/backpressure/worker active')
+        highest_rank = max(snapshot['page_batches'][key]['effective_priority_rank'] for key in snapshot['ready_batches'])
+        demand(snapshot['page_batches'][bid]['effective_priority_rank'] == highest_rank, 'a higher-priority page batch is ready')
+        selected = snapshot['page_batches'][bid]['dispatchable_spec_ids']
+        demand(event.get('spec_ids') == selected, 'dispatch members must match current bounded batch recommendation')
+        demand(all(nonempty(event.get(k)) for k in ('baseline', 'reason', 'worker')), 'batch baseline, AI reason and worker required')
+        batch = next(b for b in plan['page_batches'] if b['batch_id'] == bid)
+        optional = [member for member in selected if PRIORITY[snapshot['tasks'][member]['effective_priority']] < highest_rank]
+        state['active_batch'] = {'batch_id': bid, 'page_id': batch['page_id'], 'round_id': batch['round_id'], 'spec_ids': selected, 'opportunistic_spec_ids': optional, 'plan_revision': plan['revision'], 'feature_revision': features['revision'], 'baseline': event['baseline'], 'reason': event['reason'], 'worker': event['worker'], 'started_at': now.isoformat() if now else stamp()}
+    elif kind in {'finish_batch', 'pause_batch'}:
+        active_batch = state.get('active_batch')
+        demand(active_batch and event.get('batch_id') == active_batch['batch_id'] and not snapshot['running'], 'finish/pause matching batch only after member work stops')
+        demand(nonempty(event.get('reason')), 'batch completion/pause reason required')
+        if kind == 'finish_batch':
+            demand(all(snapshot['tasks'][member]['immediate_passed'] and not snapshot['tasks'][member]['blocked_by'] for member in active_batch['spec_ids']), 'all dispatched members need implementation and immediate gates before release')
+        state.setdefault('batch_runs', []).append({**active_batch, 'result': 'completed' if kind == 'finish_batch' else 'paused', 'ended_at': now.isoformat() if now else stamp(), 'completion_reason': event['reason']})
+        state['active_batch'] = None
+    elif kind == 'round_accept':
+        demand(page_batches.enabled(plan) and not state.get('active_batch') and not snapshot['running'], 'release page batch before round acceptance')
+        rid = event.get('round_id')
+        demand(rid in snapshot['rounds'] and snapshot['rounds'][rid]['relevant'], 'known relevant round required')
+        round_row = snapshot['rounds'][rid]
+        demand(all(r['delivered'] for r in snapshot['rounds'].values() if r['relevant'] and r['order'] < round_row['order']), 'earlier round goal must be delivered first')
+        demand(all(snapshot['tasks'][member]['accepted'] for member in round_row['spec_ids']), 'all round Specs must be individually accepted')
+        demand(nonempty(event.get('reviewer')) and nonempty(event.get('review')), 'round goal behavior review required')
+        round_plan = next(r for r in plan['rounds'] if r['round_id'] == rid)
+        evidence = validate_evidence(event.get('evidence', {}), state['candidate'], {'checks': round_plan['goal_checks']}, root)
+        demand(evidence['kind'] == 'test' and set(evidence['checks']) == set(round_plan['goal_checks']), 'round goal checks must be executed')
+        demand(all(build_hash(state['tasks'][member], state['candidate']) == evidence['hap']['sha256'] for member in round_row['spec_ids']), 'round proof must match current member HAP')
+        _, _, edges, _ = validate(plan, features)
+        state.setdefault('round_deliveries', []).append({'round_id': rid, 'signature': page_batches.round_signature(plan, features, rid, edges), 'candidate': state['candidate'], 'evidence': evidence, 'reviewer': event['reviewer'], 'review': event['review']})
+    elif kind == 'candidate':
+        demand(not snapshot['running'], 'finish or pause running work before candidate change')
+        demand(nonempty(event.get('candidate')) and event['candidate'] != state['candidate'], 'new candidate required')
+        state['candidate'] = event['candidate']
+        for value in state['tasks'].values():
+            value['validation'] = 'stale' if value['evidence'] else value['validation']
+            value['acceptance'] = 'pending'
+            value.pop('reviewed_candidate', None)
+            if value['implementation'] == 'implemented':
+                value.setdefault('pending_since', now.isoformat() if now else stamp())
+    elif kind == 'regression':
+        active = [s for s in specs.values() if s['milestone'] == plan['milestone']]
+        demand(all(snapshot['tasks'][sid]['accepted'] for sid in snapshot['relevant_specs']), 'accept milestone and prerequisite specs before final regression')
+        if page_batches.enabled(plan):
+            demand(not state.get('active_batch') and all(r['current_accepted'] for r in snapshot['rounds'].values() if r['relevant']), 'current round goal proofs required before milestone regression')
+        combined = {'checks': sorted({check for s in active for check in s['checks']})}
+        evidence = validate_evidence(event.get('evidence', {}), state['candidate'], combined, root)
+        demand(evidence['kind'] == 'test' and set(evidence['checks']) == set(combined['checks']), 'regression must cover all milestone checks')
+        demand(all(any(e['kind'] == 'build' and e['hap'] == evidence['hap'] for e in current_evidence(state['tasks'][s['spec_id']], state['candidate'])) for s in active), 'regression requires matching current HAP builds')
+        state['milestone_evidence'].append({'candidate': state['candidate'], 'milestone': plan['milestone'], 'evidence': evidence})
+    else:
+        demand(task is not None, 'known spec_id required')
+        if kind == 'start':
+            demand(sid in snapshot['ready'], 'spec not ready or validation backpressure/another worker active')
+            active_batch = state.get('active_batch')
+            if active_batch and sid in active_batch.get('opportunistic_spec_ids', []):
+                demand(not any(other not in active_batch['spec_ids'] and PRIORITY[snapshot['tasks'][other]['effective_priority']] > PRIORITY[snapshot['tasks'][sid]['effective_priority']] for other in snapshot['ready_specs']), 'higher-priority work became ready; pause optional page work')
+            demand(nonempty(event.get('baseline')) and nonempty(event.get('reason')), 'dispatch baseline and AI selection reason required')
+            task.update(implementation='in_progress', dispatch={'plan_revision': plan['revision'], 'feature_revision': features['revision'], 'baseline': event['baseline'], 'reason': event['reason']})
+            if page_batches.enabled(plan):
+                task['dispatch']['batch'] = copy.deepcopy(state['active_batch'])
+        elif kind == 'implemented':
+            demand(task['implementation'] == 'in_progress', 'only running work can be implemented')
+            demand(nonempty(event.get('commit')), 'implementation commit required')
+            task.update(implementation='implemented', validation='pending', commit=event['commit'], implemented_at=(now.isoformat() if now else stamp()))
+            task.setdefault('pending_since', task['implemented_at'])
+        elif kind == 'evidence':
+            demand(task['implementation'] == 'implemented', 'implement before attaching evidence')
+            evidence = validate_evidence(event.get('evidence', {}), state['candidate'], specs[sid], root)
+            if evidence['kind'] == 'build' and any(e['kind'] == 'build' and e['candidate'] == state['candidate'] and e['hap']['sha256'] != evidence['hap']['sha256'] for e in task['evidence']):
+                task['evidence'] = []
+                task['acceptance'] = 'pending'
+                task.pop('reviewed_candidate', None)
+            if evidence['kind'] == 'test':
+                demand(any(e['kind'] == 'build' and e['candidate'] == state['candidate'] and e['hap'] == evidence['hap'] for e in task['evidence']), 'test requires matching current build/HAP')
+            task['evidence'].append(evidence)
+            task['validation'] = 'passed' if set(specs[sid]['checks']) <= passed(task, state['candidate']) and has_build(task, state['candidate']) else 'pending'
+        elif kind == 'interface':
+            demand(work_packets.enabled(plan) and task['implementation'] == 'implemented', 'interface confirmation requires implemented provider and work-packet policy')
+            capability = event.get('capability')
+            demand(any(c['capability'] == capability for c in specs[sid]['provides']), 'interface must belong to provider')
+            demand(nonempty(state['candidate']) and event.get('candidate') == state['candidate'], 'interface candidate mismatch')
+            demand(nonempty(event.get('reviewer')) and nonempty(event.get('summary')), 'interface behavior review required')
+            strings(event.get('symbols'), 'actual interface symbols', True)
+            code_files = copy.deepcopy(event.get('code_files'))
+            demand(isinstance(code_files, list) and bool(code_files), 'actual interface code files required')
+            for ref in code_files:
+                demand(isinstance(ref, dict) and nonempty(ref.get('path')), 'interface code path required')
+                path = Path(ref['path'])
+                path = path if path.is_absolute() else root / path
+                demand(path.is_file() and ref.get('sha256') == file_hash(path), 'interface code file/hash mismatch')
+                ref['path'] = str(path.resolve())
+            task.setdefault('interfaces', {})[capability] = {'candidate': state['candidate'], 'symbols': event['symbols'], 'summary': event['summary'], 'reviewer': event['reviewer'], 'code_files': code_files}
+        elif kind == 'accept':
+            demand(snapshot['tasks'][sid]['immediate_passed'] and not snapshot['tasks'][sid]['blocked_by'] and not snapshot['tasks'][sid]['missing_checks'], 'all checks, dependencies and build must pass')
+            demand(nonempty(event.get('review')) and nonempty(event.get('reviewer')), 'independent behavior review and reviewer required')
+            task.update(acceptance='accepted', reviewed_candidate=state['candidate'], review=event['review'], reviewer=event['reviewer'])
+            task.pop('pending_since', None)
+        elif kind == 'block':
+            strings(event.get('reasons'), 'external blockers', True)
+            task['external_blockers'] = event['reasons']
+            if task['implementation'] == 'in_progress':
+                task['implementation'] = 'planned'
+        elif kind == 'unblock':
+            demand(nonempty(event.get('reason')), 'recovery reason required')
+            task['external_blockers'] = []
+        elif kind in {'invalidate', 'failed'}:
+            demand(nonempty(event.get('reason')), 'invalidation/failure reason required')
+            task['evidence'] = []
+            task.update(validation='failed' if kind == 'failed' else 'stale', acceptance='pending')
+            task.pop('reviewed_candidate', None)
+            task.pop('interfaces', None)
+            state['milestone_evidence'] = []
+            if page_batches.enabled(plan):
+                _, _, dependency_edges, _ = validate(plan, features)
+                affected = {sid}
+                while True:
+                    expanded = affected | {child for child, parents in dependency_edges.items() if set(parents) & affected}
+                    if expanded == affected:
+                        break
+                    affected = expanded
+                affected_rounds = {b['round_id'] for b in plan['page_batches'] if set(b['spec_ids']) & affected}
+                state['round_deliveries'] = [proof for proof in state.get('round_deliveries', []) if proof['round_id'] not in affected_rounds]
+            if task['implementation'] == 'implemented':
+                task.setdefault('pending_since', now.isoformat() if now else stamp())
+        elif kind == 'repair':
+            demand(not snapshot['running'] and task['implementation'] == 'implemented' and task['validation'] in {'failed', 'stale'}, 'repair requires failed/stale implementation and idle worker')
+            demand(not state.get('active_batch') or sid in state['active_batch']['spec_ids'], 'pause active batch before repairing unrelated Spec')
+            task.update(implementation='in_progress', acceptance='pending')
+            task['evidence'] = []
+            task.pop('reviewed_candidate', None)
+            task.pop('interfaces', None)
+        elif kind == 'pause':
+            demand(task['implementation'] == 'in_progress' and nonempty(event.get('reason')), 'pause running work with reason')
+            task['implementation'] = 'planned'
+        elif kind == 'metrics':
+            metrics = event.get('metrics')
+            demand(isinstance(metrics, dict), 'metrics object required')
+            demand(set(metrics) <= {'implementation_hours', 'test_hours', 'coordination_hours', 'waiting_hours', 'rework_hours', 'elapsed_hours', 'first_pass', 'conflicts', 'context_hours', 'repeated_analysis_hours'}, 'unknown metric')
+            for key, value in metrics.items():
+                if value is not None:
+                    demand(type(value) is bool, 'first_pass must be boolean') if key == 'first_pass' else number(value, key)
+                    if key == 'conflicts':
+                        demand(type(value) is int, 'conflicts must be integer')
+            combined = {**task['metrics'], **metrics}
+            for child, parent in [('context_hours', 'implementation_hours'), ('repeated_analysis_hours', 'context_hours')]:
+                a, b = combined.get(child), combined.get(parent)
+                if type(a) in (int, float) and type(b) in (int, float):
+                    demand(a <= b, f'{child} must not exceed {parent}')
+            task['metrics'].update(metrics)
+        else:
+            raise ValueError('unknown event type')
+    if plan.get('spec_generation_policy') == spec_generation.POLICY and kind in {'start', 'repair'}:
+        demand(not spec_generation.gaps(plan, features, specs[sid], root), 'valid generated Spec required before implementation')
+        task['spec_generation'] = spec_generation.proof(root, sid)
+    state['events'].append({'sequence': len(state['events']) + 1, 'timestamp': now.isoformat() if now else stamp(), 'plan_revision': plan['revision'], 'event': copy.deepcopy(event)})
+    final_view = derive(plan, features, state, now, root)
+    for key, row in final_view['tasks'].items():
+        if not row['accepted']:
+            state['tasks'][key]['acceptance'] = 'pending'
+    return state
+
+
+def reconcile(plan, features, state, previous_plan, previous_features, reason, root=None):
+    derive(previous_plan, previous_features, state, root=root)
+    validate(plan, features)
+    demand(nonempty(reason), 'revision reason required')
+    demand(not state.get('active_batch') and not any(t['implementation'] == 'in_progress' for t in state['tasks'].values()), 'explicitly pause running work and active batch before replanning')
+    demand(plan['revision'] == previous_plan['revision'] + 1, 'plan revision must increment by one')
+    new_ids = {s['spec_id'] for s in plan['specs']}
+    retired_ids = {s['spec_id'] for s in plan.get('retired_specs', [])}
+    demand(set(state['tasks']) <= new_ids | retired_ids, 'retain historical spec IDs or explicitly retire them')
+    if features != previous_features:
+        errors = feature_validator()(features, previous_features)
+        demand(not errors, '; '.join(errors))
+    new = init_state(plan, features)
+    new['events'] = copy.deepcopy(state['events'])
+    new['history'] = copy.deepcopy(state['history']) + [{'plan': previous_plan, 'features': previous_features, 'execution': {k: copy.deepcopy(v) for k, v in state.items() if k not in {'history', 'events'}}, 'reason': reason}]
+    new['batch_runs'] = copy.deepcopy(state.get('batch_runs', []))
+    new['round_deliveries'] = copy.deepcopy(state.get('round_deliveries', []))
+    old_specs = {s['spec_id']: s for s in previous_plan['specs']}
+    old_features = {f['feature_id']: f for f in previous_features['features']}
+    new_features = {f['feature_id']: f for f in features['features']}
+    for item in plan['specs']:
+        sid = item['spec_id']
+        if sid in state['tasks']:
+            new['tasks'][sid] = copy.deepcopy(state['tasks'][sid])
+            semantic_keys = ('required_scope', 'acceptance', 'source_refs', 'origin')
+            feature_changed = any(any(old_features.get(fid, {}).get(k) != new_features[fid].get(k) for k in semantic_keys) for fid in item['feature_refs'])
+            semantic_spec_keys = ('implementation_brief', 'scope_refs', 'page_id', 'feature_refs', 'scope', 'evidence_refs', 'requires', 'provides', 'checks')
+            if features['schema'] == 'd2h-feature-plan/v2':
+                for ref in item.get('scope_refs', []):
+                    fid, rid = ref['feature_id'], ref['scope_id']
+                    old_item = next((i for i in old_features.get(fid, {}).get('scope_items', []) if i['scope_id'] == rid), None)
+                    new_item = next(i for i in new_features[fid]['scope_items'] if i['scope_id'] == rid)
+                    feature_changed = feature_changed or old_item != new_item
+            scope_changed = any(old_specs[sid].get(k) != item.get(k) for k in semantic_spec_keys)
+            checks_changed = any(old_specs[sid]['testing'].get(k) != item['testing'].get(k) for k in ('immediate', 'batch', 'triggers', 'risk_dimensions', 'layers'))
+            related = lambda p: [c for c in p.get('shared_contracts', []) if sid in [c['producer_spec_id'], *c['consumer_spec_ids']]]
+            contracts_changed = related(previous_plan) != related(plan) or previous_plan.get('work_packet_policy') != plan.get('work_packet_policy') or previous_plan.get('spec_generation_policy') != plan.get('spec_generation_policy')
+            if scope_changed or checks_changed or feature_changed or contracts_changed:
+                new['tasks'][sid].update(implementation='planned', validation='stale', acceptance='pending', evidence=[])
+                new['tasks'][sid].pop('reviewed_candidate', None)
+                new['tasks'][sid].pop('interfaces', None)
+    new['candidate'] = state['candidate']
+    new['events'].append({'sequence': len(new['events']) + 1, 'timestamp': stamp(), 'plan_revision': plan['revision'], 'event': {'type': 'reconcile', 'reason': reason}})
+    final_view = derive(plan, features, new, root=root)
+    for key, row in final_view['tasks'].items():
+        if not row['accepted']:
+            new['tasks'][key]['acceptance'] = 'pending'
+    return new
+
+
+def render(plan, features, state, root=None):
+    view = derive(plan, features, state, root=root)
+    report = {
+        'schema_version': 'd2h-spec-batch-report/v1',
+        'source': {
+            'plan_revision': plan['revision'], 'plan_sha256': fingerprint(plan),
+            'features_path': plan['feature_source']['path'],
+            'features_revision': features['revision'], 'features_sha256': fingerprint(features),
+            'execution': 'execution.json', 'event_count': len(state['events']),
+        },
+        'candidate': state['candidate'],
+        'milestone': plan['milestone'],
+        'state': view,
+        'tasks': {},
+        'dispositions': plan.get('dispositions', []),
+        'retired_specs': plan.get('retired_specs', []),
+        'milestone_evidence': state['milestone_evidence'],
+        'batch_runs': state.get('batch_runs', []),
+        'round_deliveries': state.get('round_deliveries', []),
+        'revision_history': state['history'],
+        'history': state['events'],
+    }
+    feature_map = {feature['feature_id']: feature for feature in features['features']}
+    for item in plan['specs']:
+        sid = item['spec_id']
+        report['tasks'][sid] = {
+            'plan': item,
+            'execution': state['tasks'][sid],
+            'user_priorities': {fid: feature_map[fid]['user_priority'] for fid in item['feature_refs']},
+            'current_evidence': current_evidence(state['tasks'][sid], state['candidate']),
+        }
+    return json.dumps(report, ensure_ascii=False, indent=2) + '\n'
+
+
+REPORT_MARKER = '> Generated by d2h workflow; execution.json is authoritative. Do not edit status here.'
+
+
+def report_paths(root):
+    return root / 'batch_report.json', root / 'batch_report.md'
+
+
+def check_report_targets(root, initializing=False):
+    report, markdown = report_paths(root)
+    for target in (report, markdown):
+        demand(not target.is_symlink(), 'refusing linked report target: ' + str(target))
+        if target.exists():
+            demand(not initializing, 'existing report requires history-preserving recovery, not init')
+    if report.exists():
+        payload = json.loads(report.read_text(encoding='utf-8'))
+        demand(isinstance(payload, dict) and payload.get('schema_version') == 'd2h-spec-batch-report/v1',
+               'report schema mismatch; preserve the legacy page ledger before migration')
+    if markdown.exists():
+        demand(REPORT_MARKER in markdown.read_text(encoding='utf-8').splitlines()[:5],
+               'existing Markdown history requires explicit migration before projection')
+
+
+def render_markdown(report):
+    def cell(value):
+        return str(value if value is not None else 'unknown').replace('|', '\\|').replace('\n', ' ')
+    source = report['source']
+    lines = ['# Spec 执行报告', '', REPORT_MARKER, '',
+             f"- 计划版本：{source['plan_revision']}；范围版本：{source['features_revision']}",
+             f"- 当前候选：{cell(report['candidate'])}；里程碑：{cell(report['milestone'])}",
+             f"- 执行事件：{source['event_count']}；计划身份：{source['plan_sha256']}", '',
+             '| Spec | 当前范围 | 实现 | 验收 | 待验证 | 阻塞 |',
+             '|---|---|---|---|---|---|']
+    for sid, task in report['tasks'].items():
+        status = report['state']['tasks'][sid]
+        blockers = status.get('blocked_by', []) + status.get('external_blockers', [])
+        lines.append('| ' + ' | '.join(cell(x) for x in (
+            sid, '; '.join(task['plan'].get('scope', [])), task['execution']['implementation'],
+            'accepted' if status.get('accepted') else 'pending',
+            '; '.join(status.get('missing_checks', [])), '; '.join(str(b) for b in blockers))) + ' |')
+        lines.extend(['', f"## {cell(sid)}", '',
+                      '- 实现提交：' + cell(task['execution'].get('commit')),
+                      '- 当前有效证据数：' + str(len(task['current_evidence']))])
+        for evidence in task['current_evidence']:
+            lines.append('- 证据：' + cell(json.dumps(evidence, ensure_ascii=False)))
+        lines.append('')
+    # Keep the summary table contiguous; details follow it.
+    rows = [line for line in lines if line.startswith('|')]
+    details = [line for line in lines[9:] if not line.startswith('|')]
+    return '\n'.join(lines[:8] + [''] + rows + [''] + details).rstrip() + '\n'
+
+
+def write_reports(root, plan, features, state):
+    report_path, markdown_path = report_paths(root)
+    serialized = render(plan, features, state, root)
+    write_atomic(report_path, serialized)
+    write_atomic(markdown_path, render_markdown(json.loads(serialized)))
+
+
+def write_atomic(path, value, exclusive=False):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(dir=path.parent, prefix='.spec-runtime-')
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as stream:
+            stream.write(value)
+        if exclusive:
+            os.link(temporary, path)
+        else:
+            os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action', choices=['validate', 'init', 'derive', 'event', 'render', 'reconcile', 'context', 'dashboard', 'generation'])
+    parser.add_argument('--plan', type=Path, required=True)
+    parser.add_argument('--features', type=Path, required=True)
+    parser.add_argument('--planning-only', action='store_true', help='validate structure without requiring generated page documents; validate only')
+    parser.add_argument('--spec-id', action='append')
+    parser.add_argument('--expected-plan-hash')
+    parser.add_argument('--execution', type=Path)
+    parser.add_argument('--event', type=Path)
+    parser.add_argument('--previous-plan', type=Path)
+    parser.add_argument('--previous-features', type=Path)
+    parser.add_argument('--reason')
+    parser.add_argument('--batch-id')
+    parser.add_argument('--output', type=Path)
+    parser.add_argument('--baseline-features', type=Path)
+    parser.add_argument('--overview', type=Path)
+    parser.add_argument('--feature-analysis', type=Path)
+    parser.add_argument('--analysis-progress', type=Path)
+    parser.add_argument('--expected-sequence', type=int)
+    args = parser.parse_args()
+    def load(path):
+        demand(path is not None, 'missing required file argument')
+        return json.loads(path.read_text(encoding='utf-8'))
+    lock = None
+    try:
+        plan, features = load(args.plan), load(args.features)
+        demand(Path(plan.get('feature_source', {}).get('path', '')).resolve() == args.features.resolve(), 'feature source path mismatch')
+        demand(not args.planning_only or args.action == 'validate', '--planning-only is restricted to validate')
+        validate(plan, features, None if args.planning_only else args.plan.parent)
+        if args.action == 'generation':
+            receipt = spec_generation.record(plan, features, args.plan.parent, args.spec_id, args.expected_plan_hash)
+            write_atomic(args.plan.parent / 'generation.json', json.dumps(receipt, ensure_ascii=False, indent=2) + '\n')
+            print(json.dumps({'ok': True, 'spec_ids': args.spec_id, 'note': 'content binding only; not semantic review or acceptance'}))
+            return 0
+        if args.action == 'validate':
+            print(json.dumps({'ok': True, 'schema': SCHEMA, 'plan_sha256': fingerprint(plan), 'planning_only': args.planning_only}))
+            return 0
+        demand(args.execution is not None, '--execution required')
+        if args.action in {'init', 'event', 'reconcile', 'render'}:
+            check_report_targets(args.plan.parent, initializing=args.action == 'init')
+        if args.action in {'init', 'event', 'reconcile'}:
+            lock = args.execution.with_suffix(args.execution.suffix + '.lock')
+            lock.parent.mkdir(parents=True, exist_ok=True)
+            # Lock file is held through read/validate/write. Never remove another process lock.
+            try:
+                lock.open('x').close()
+            except FileExistsError:
+                lock = None
+                raise ValueError('execution writer already active; inspect stale lock before retry')
+        state = init_state(plan, features) if args.action == 'init' else load(args.execution)
+        if args.action in {'event', 'reconcile'}:
+            demand(args.expected_sequence == len(state['events']), 'expected-sequence mismatch; reread ledger before writing')
+        if args.action == 'event':
+            payload = load(args.event)
+            for event in payload if isinstance(payload, list) else [payload]:
+                state = apply_event(plan, features, state, event, args.plan.parent)
+        if args.action == 'reconcile':
+            state = reconcile(plan, features, state, load(args.previous_plan), load(args.previous_features), args.reason, args.plan.parent)
+        if args.action in {'init', 'event', 'reconcile'}:
+            write_atomic(args.execution, json.dumps(state, ensure_ascii=False, indent=2) + '\n', args.action == 'init')
+        view = derive(plan, features, state, root=args.plan.parent)
+        if args.action in {'init', 'event', 'reconcile'}:
+            write_reports(args.plan.parent, plan, features, state)
+        if args.action == 'render':
+            demand(args.output is not None and args.output.resolve() == (args.plan.parent / 'batch_report.json').resolve(), '--output must be plan directory/batch_report.json')
+            write_reports(args.plan.parent, plan, features, state)
+        if args.action == 'context':
+            view = dispatch_context(plan, features, state, args.batch_id, args.plan.parent)
+        if args.action == 'dashboard':
+            baseline = load(args.baseline_features) if args.baseline_features else None
+            if baseline is not None:
+                demand(not feature_validator()(baseline, check_analysis=False) and baseline['schema'] == 'd2h-feature-plan/v2', 'valid v2 review baseline required')
+                demand(baseline['revision'] <= features['revision'], 'review baseline cannot be newer than current features')
+            view = delivery_view.snapshot(plan, features, state, view, stamp(), baseline)
+            view['overview'] = dashboard_overview.prepare(load(args.overview) if args.overview else None, state['candidate'])
+            if args.feature_analysis:
+                handoff_path = Path(__file__).with_name('artifact_bindings.py')
+                loader = importlib.util.spec_from_file_location('analysis_handoff', handoff_path)
+                handoff = importlib.util.module_from_spec(loader)
+                loader.loader.exec_module(handoff)
+                report, analysis_overview = handoff.dashboard_report(args.feature_analysis, features)
+                # Analysis owns stack/dependency inventory; optional overview supplies measured code/tools and reviewed preparation.
+                supplemental = copy.deepcopy(view['overview'])
+                for source in supplemental.get('sources', []):
+                    source['source_id'] = 'supplemental:' + source['source_id']
+                for source in supplemental.get('source_checks', []):
+                    source['source_id'] = 'supplemental:' + source['source_id']
+                for row in ([supplemental['code']] if supplemental.get('code') else []) + supplemental.get('tools', []) + supplemental.get('dependencies', []) + supplemental.get('blockers', []):
+                    row['source_refs'] = ['supplemental:' + ref for ref in row.get('source_refs', [])]
+                merged = dashboard_overview.prepare(analysis_overview, state['candidate'])
+                merged['code'] = supplemental.get('code') or merged.get('code')
+                merged['tools'] = supplemental.get('tools', [])
+                merged['sources'] += supplemental.get('sources', [])
+                merged['source_checks'] += supplemental.get('source_checks', [])
+                merged['stale'] = merged['stale'] or supplemental.get('stale', False)
+                # Explicit supplemental preparation records supersede report todos only with a current report binding.
+                if args.overview:
+                    bound = any(s.get('path') == report['path'] and s.get('sha256') == report['sha256'] for s in supplemental.get('sources', []))
+                    if bound and not supplemental.get('stale', False):
+                        if 'blockers' in supplemental:
+                            merged['blockers'] = supplemental['blockers']
+                        merged['dependencies'] += supplemental.get('dependencies', [])
+                view['overview'] = merged
+                view['feature_analysis'] = report
+            view['analysis'] = dashboard_overview.read_analysis(args.analysis_progress)
+            if args.output is not None:
+                demand(args.output.resolve() == (args.plan.parent / 'dashboard.html').resolve(), '--output must be plan directory/dashboard.html')
+                template = Path(__file__).with_name('assets') / 'dashboard.html'
+                write_atomic(args.output, delivery_view.html(view, template.read_text(encoding='utf-8')))
+        print(json.dumps(view, ensure_ascii=False, indent=2))
+        return 0
+    except (ValueError, OSError, KeyError, TypeError, IndexError, AttributeError) as error:
+        print(json.dumps({'error': str(error)}, ensure_ascii=False))
+        return 2
+    finally:
+        if lock is not None:
+            lock.unlink(missing_ok=True)
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())