@harmonyos-arkts/d2h 0.1.20 → 0.1.22

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')}