@my-life-buddies/cli 0.1.2

package/resources/buddy-creator/scripts/completion.py

@@ -0,0 +1,240 @@
+"""Create local deliverables from confirmed versions. No developer handoff."""
+import hashlib
+import copy
+import html
+import json
+import os
+import shutil
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+LABELS = {'definition': '定义', 'knowledge': '知识', 'methods': '方法', 'service': '服务'}
+
+
+def _bytes(value):
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2, allow_nan=False).encode('utf-8')
+
+
+def _hash(raw):
+    return hashlib.sha256(raw).hexdigest()
+
+
+def _atomic(path, raw):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix='.' + path.name + '-', dir=str(path.parent))
+    try:
+        with os.fdopen(fd, 'wb') as stream:
+            stream.write(raw)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, str(path))
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def _confirmed(state, object_id):
+    artifact = state.get('artifacts', {}).get(object_id)
+    return bool(artifact and any(record.get('objectId') == object_id and record.get('hash') == artifact['hash']
+                                and not record.get('invalidatedBy') and record.get('decision') == 'confirmed'
+                                for record in state.get('confirmations', [])))
+
+
+def _ready(state, catalog):
+    return not state.get('paused') and not state.get('pendingTurnId') and all(
+        _confirmed(state, '%s.%d' % (stage, index + 1))
+        for stage in catalog['stages'] for index in range(len(catalog['chapters'][stage])))
+
+
+def _line_chunks(text, columns=32, limit=3):
+    text = ' '.join(str(text or '待补充').split())
+    lines, line, width = [], '', 0
+    for char in text:
+        char_width = 1 if ord(char) < 128 else 2
+        if width + char_width > columns * 2:
+            lines.append(line)
+            line, width = '', 0
+        line += char
+        width += char_width
+    if line:
+        lines.append(line)
+    if len(lines) > limit:
+        lines = lines[:limit]
+        lines[-1] = lines[-1][:-1] + '…'
+    return lines
+
+
+def _blueprint(state):
+    blueprint = copy.deepcopy(state['artifacts'].get('service.blueprint', {}).get('data') or {})
+    transitions = blueprint.setdefault('transitions', {})
+    for artifact in state['artifacts'].values():
+        if artifact.get('kind') == 'transition' and artifact.get('data'):
+            path_id = artifact['id'].removeprefix('transition.')
+            transitions[path_id] = dict(transitions.get(path_id, {}), **artifact['data'])
+    return blueprint
+
+
+def _diagram(state):
+    blueprint = _blueprint(state)
+    stages = blueprint.get('stages', {})
+    transitions = blueprint.get('transitions', {})
+    boxes = []
+    for key, title, meaning, y in [('acquisition', '获客期', '先免费体验', 90),
+                                  ('paid', '付费期', '订阅后持续获得帮助 · AI 对话不限次数', 325),
+                                  ('maintenance', '维持期', '未订阅或到期未续费 · 保留基础对话与历史', 560)]:
+        config = stages.get(key, {})
+        lines = _line_chunks(config.get('result') or config.get('service'), columns=32, limit=3)
+        content = ''.join('<tspan x="76" dy="25">%s</tspan>' % html.escape(line) for line in lines)
+        boxes.append('<g><rect x="48" y="%d" width="540" height="160" rx="12" fill="#20271b" stroke="#556446"/>'
+                     '<text x="76" y="%d" fill="#b8d879" font-size="24" font-weight="700">%s</text>'
+                     '<text x="76" y="%d" fill="#bac2b0" font-size="14">%s</text>'
+                     '<text y="%d" fill="#edf0e8" font-size="17">%s</text></g>' %
+                     (y, y + 35, title, y + 61, html.escape(meaning), y + 71, content))
+    cycle = blueprint.get('billingCycle') or {}
+    units = {'day': '天', 'week': '周', 'month': '个月', 'year': '年'}
+    duration = str(cycle.get('count', '')) + units.get(cycle.get('unit'), '') if isinstance(cycle, dict) else str(cycle)
+    terms = ('订阅：¥%s / %s' % (blueprint.get('price', '待定'), duration or '待定'))
+    def caption(key, fallback):
+        return html.escape(str(transitions.get(key, {}).get('title') or fallback))
+    return ('<svg xmlns="http://www.w3.org/2000/svg" width="980" height="810" viewBox="0 0 980 810" role="img" aria-labelledby="title desc">'
+            '<title id="title">Buddy 服务模式</title><desc id="desc">免费体验、付费订阅和维持三阶段，以及五条用户路径。完整约定见服务手册。</desc>'
+            '<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">'
+            '<path d="M0 0L10 5L0 10Z" fill="#b8d879"/></marker></defs>'
+            '<rect width="980" height="810" rx="16" fill="#151a13"/><g font-family="system-ui,sans-serif">'
+            '<text x="48" y="43" fill="#edf0e8" font-size="25" font-weight="700">Buddy · 服务模式</text>'
+            '<text x="48" y="69" fill="#bac2b0" font-size="15">%s</text>%s'
+            '<g fill="none" stroke="#94aa76" stroke-width="2" marker-end="url(#arrow)">'
+            '<path d="M260 250V325"/><path d="M260 485V560"/>'
+            '<path d="M588 150H902V640H588"/>'
+            '<path d="M588 355H682V445H588"/>'
+            '<path d="M588 670H780V410H588" stroke-dasharray="6 5"/></g>'
+            '<g fill="#dce8ca" font-size="16">'
+            '<text x="278" y="292">%s</text><text x="278" y="527">%s</text>'
+            '<text x="808" y="284">%s</text><text x="693" y="390">%s</text>'
+            '<text x="793" y="555">%s</text></g>'
+            '<text x="48" y="769" fill="#bac2b0" font-size="15">阶段卡片展示摘要；具体服务、权益和转换条件以已确认手册为准。</text></g></svg>') % (
+                html.escape(terms), ''.join(boxes), caption('acquisition-paid', '体验后订阅'),
+                caption('paid-maintenance', '到期未续费'), caption('acquisition-maintenance', '暂不订阅'),
+                caption('paid-paid', '续费'), caption('maintenance-paid', '恢复订阅'))
+
+
+def snapshot(workspace, state):
+    path = Path(workspace) / 'completion.json'
+    if not path.exists() or state.get('pendingTurnId') or state.get('paused'):
+        return None
+    try:
+        record = json.loads(path.read_text(encoding='utf-8'))
+        if record.get('revision') != state.get('revision'):
+            return None
+        if record.get('status') == 'ready' and not (Path(record['directory']) / 'BUDDY_MANUAL.md').is_file():
+            record['status'] = 'failed'
+            record['message'] = '四册确认已保留，本地成果需要重新生成。'
+        return {key: record.get(key) for key in ('revision', 'status', 'message', 'fileCount', 'updatedAt')}
+    except (OSError, ValueError, KeyError):
+        return None
+
+
+def return_to_caller(workspace, state, result):
+    """Report the Skill boundary, not the caller's next implementation step. Read-only."""
+    catalog = json.loads((Path(__file__).resolve().parent.parent / 'references' / 'catalog.json').read_text(encoding='utf-8'))
+    if not _ready(state, catalog):
+        return result
+    workspace = Path(workspace).resolve()
+    record = None
+    try:
+        record = json.loads((workspace / 'completion.json').read_text(encoding='utf-8'))
+        revision = state['revision']
+        if not isinstance(revision, str) or not revision or any(c not in 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-' for c in revision):
+            raise ValueError('版本身份无效。')
+        if not isinstance(record, dict) or record.get('revision') != revision or record.get('status') != 'ready':
+            raise ValueError('当前确认版本的成果尚未生成成功。')
+        directory = workspace / 'deliverables' / revision
+        manual, manifest = directory / 'BUDDY_MANUAL.md', directory / 'MANIFEST.json'
+        if (directory.parent.is_symlink() or directory.is_symlink() or manual.is_symlink() or manifest.is_symlink()
+                or record.get('directory') != str(directory) or record.get('manualPath') != str(manual)):
+            raise ValueError('成果路径与当前作品不一致。')
+        inventory = json.loads(manifest.read_text(encoding='utf-8'))
+        entries = [f for f in inventory['files'] if f['path'] == 'BUDDY_MANUAL.md']
+        if (inventory.get('revision') != revision or inventory.get('buddyId') != state['buddyId']
+                or inventory.get('complete') is not True or len(entries) != 1
+                or _hash(manual.read_bytes()) != entries[0]['sha256']):
+            raise ValueError('手册与已确认成果不一致。')
+        result['completion'] = {key: record[key] for key in
+                                ('revision', 'status', 'directory', 'manualPath', 'fileCount', 'message', 'updatedAt')}
+        result['directive'] = 'creator_complete'
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        # Never hand off a stale path or a success-shaped but unusable export.
+        result['completion'] = {'revision': state.get('revision'), 'status': 'failed',
+                                'message': '四册确认已保留，当前成果缺失、失效或被修改；先用 finalize 恢复交付。',
+                                'error': (record.get('error') if isinstance(record, dict)
+                                          and record.get('revision') == state['revision'] else None) or str(error)}
+        result['directive'] = 'finalize_required'
+    return result
+
+
+def finalize(workspace, state):
+    workspace = Path(workspace)
+    catalog = json.loads((Path(__file__).resolve().parent.parent / 'references' / 'catalog.json').read_text(encoding='utf-8'))
+    if not _ready(state, catalog):
+        return None
+    revision = str(state['revision'])
+    if not revision or any(char not in 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-' for char in revision):
+        raise ValueError('REVISION_INVALID: 无法识别当前版本身份。')
+    output = workspace / 'deliverables' / revision
+    record = {'revision': revision, 'updatedAt': datetime.now(timezone.utc).isoformat()}
+    staging = None
+    try:
+        files, manual = {}, ['# Buddy 创作手册', '', '搭子：' + state['buddyId'], '']
+        for stage in catalog['stages']:
+            parts = ['# ' + LABELS[stage] + '手册', '']
+            for index, title in enumerate(catalog['chapters'][stage]):
+                artifact = state['artifacts']['%s.%d' % (stage, index + 1)]
+                parts.extend(['## %d. %s' % (index + 1, title), '', artifact['markdown'], ''])
+                if artifact.get('unresolved'):
+                    parts.extend(['待补充：' + '；'.join(artifact['unresolved']), ''])
+            text = '\n'.join(parts)
+            files['booklets/%s.md' % stage] = text.encode('utf-8')
+            manual.extend([text, ''])
+        manual.extend(['## 服务模式图', '', '![服务模式](SERVICE_MODEL.svg)', '',
+                       '本手册记录已确认的创作设计，后续开发、内容核实和实际履约仍按具体项目推进。', ''])
+        files['BUDDY_MANUAL.md'] = '\n'.join(manual).encode('utf-8')
+        files['SERVICE_MODEL.svg'] = _diagram(state).encode('utf-8')
+        files['service-blueprint.json'] = _bytes({
+            'data': _blueprint(state),
+            'sourceArtifact': {key: state['artifacts'].get('service.blueprint', {}).get(key) for key in ('id', 'hash')},
+            'transitionArtifacts': [{key: artifact.get(key) for key in ('id', 'hash')} for artifact in state['artifacts'].values() if artifact.get('kind') == 'transition']})
+        files['versions.json'] = _bytes({'buddyId': state['buddyId'], 'revision': revision,
+                                        'artifacts': state['artifacts'], 'confirmations': state['confirmations']})
+        files['sources.json'] = _bytes(list(state.get('sources', {}).values()))
+        files['MANIFEST.json'] = _bytes({'format': 'buddy-creator-1', 'buddyId': state['buddyId'],
+                                        'revision': revision, 'complete': True,
+                                        'files': [{'path': path, 'sha256': _hash(raw), 'bytes': len(raw)} for path, raw in files.items()]})
+        output.parent.mkdir(parents=True, exist_ok=True)
+        staging = Path(tempfile.mkdtemp(prefix='.build-', dir=str(output.parent)))
+        for path, raw in files.items():
+            _atomic(staging / path, raw)
+        if output.exists():
+            # Reuse intact outputs; preserve manually edited exports as a separate directory.
+            intact = all((output / path).is_file() and (output / path).read_bytes() == raw for path, raw in files.items())
+            if intact:
+                shutil.rmtree(str(staging))
+                staging = None
+            else:
+                saved = output.with_name(output.name + '-previous-' + datetime.now().strftime('%Y%m%d%H%M%S%f'))
+                os.replace(str(output), str(saved))
+                os.replace(str(staging), str(output))
+                staging = None
+        else:
+            os.replace(str(staging), str(output))
+            staging = None
+        record.update(status='ready', directory=str(output), manualPath=str(output / 'BUDDY_MANUAL.md'),
+                      fileCount=len(files), message='四册已确认，创作手册和服务模式图已保存在本机。')
+    except Exception as error:
+        record.update(status='failed', error=str(error), message='四册确认已保留，本地成果生成需要重试。')
+    finally:
+        if staging:
+            shutil.rmtree(str(staging), ignore_errors=True)
+    _atomic(workspace / 'completion.json', _bytes(record))
+    return record

package/resources/buddy-creator/scripts/interview.py

@@ -0,0 +1,215 @@
+"""Bound interview depth by both a concrete gap and its parent target.
+
+The host assesses meaning and novelty with evidence; code owns counters, bounds
+and history. No model calls and no keyword-based inference of user consent.
+"""
+from __future__ import annotations
+
+import copy
+import re
+
+from buddy_core import CLOSED, catalog, evidence, require, text
+
+POLICY = catalog()['interviewPolicy']
+GAP_LIMIT = POLICY['gapMaxAnswers']
+NO_GAIN_LIMIT = POLICY['noGainLimit']
+
+def tracked(target_id):
+    # Source discovery still ends by the creator's explicit choice.
+    return target_id != 'K02'
+
+
+def initial_id(target_id):
+    return target_id + '.initial'
+
+
+def ensure(state, target_id):
+    history = state.setdefault('interview', {'targets': {}, 'gaps': {}})
+    if target_id not in history['targets']:
+        answers = state['targets'][target_id]['answerInputIds']
+        history['targets'][target_id] = {
+            'windowStart': 0, 'noGainStreak': 0, 'lastGain': False,
+            'stopReason': None, 'reopens': [],
+        }
+        history['gaps'][initial_id(target_id)] = {
+            'id': initial_id(target_id), 'targetId': target_id,
+            'description': catalog()['cards'][target_id]['minimum'],
+            'impact': '当前目标的必要内容', 'blocking': catalog()['cards'][target_id]['hard'], 'evidence': [],
+            'status': 'open', 'windowStart': 0, 'noGainStreak': 0,
+            'answers': [{'inputId': key, 'hasNewInformation': None} for key in answers],
+        }
+    return history['targets'][target_id]
+
+
+def count(state, target_id):
+    progress = state.get('interview', {}).get('targets', {}).get(target_id, {})
+    return len(state['targets'][target_id]['answerInputIds']) - progress.get('windowStart', 0)
+
+
+def target_open(state, target_id):
+    card = catalog()['cards'][target_id]
+    require(count(state, target_id) < card['maxAnswers'], 'TARGET_LIMIT',
+            '本目标已到本轮回答上限；保留待补，转到其他目标。更换缺口或案例不会重置次数。', {'targetId': target_id})
+    progress = state.get('interview', {}).get('targets', {}).get(target_id, {})
+    require(not progress.get('stopReason'), 'TARGET_DEFERRED',
+            '本轮已收口；只能依据用户明确针对该目标的续谈请求重新展开。', {'targetId': target_id})
+    review = card.get('reviewAfter', card['maxAnswers'])
+    if count(state, target_id) >= review:
+        require(progress.get('lastGain') is True, 'NO_EXTENSION',
+                '整理节点后没有实质新增，不能继续延长本目标。', {'targetId': target_id})
+
+
+def question_gap(state, question):
+    target_id = question['targetId']
+    ensure(state, target_id)
+    gap_id = question.get('gapId', initial_id(target_id))
+    gap = state['interview']['gaps'].get(gap_id)
+    require(gap and gap['targetId'] == target_id, 'GAP_NOT_FOUND',
+            '问题必须绑定本目标已登记的具体缺口。', {'gapId': gap_id})
+    require(gap['status'] == 'open' and len(gap['answers']) - gap['windowStart'] < GAP_LIMIT
+            and gap['noGainStreak'] < NO_GAIN_LIMIT, 'GAP_CLOSED',
+            '该缺口已讲清、暂放或达到边界；不要换一种问法重复追问。', {'gapId': gap_id})
+    card = catalog()['cards'][target_id]
+    if count(state, target_id) >= card.get('reviewAfter', card['maxAnswers']):
+        require(gap['blocking'], 'EXTENSION_REQUIRES_BLOCKER',
+                '四轮整理后只补影响当前结论或执行的关键缺口，其他细节留待补充。')
+    return {'targetId': target_id, 'gapId': gap_id}
+
+
+def prepare(state, patch, inp, intent):
+    require(isinstance(patch, dict) and not set(patch) - {'gaps', 'assessment', 'reopen', 'resolutions'},
+            'INTERVIEW_SCHEMA', 'interview 仅使用 gaps、assessment、reopen、resolutions。')
+    changed = set()
+    proposals = patch.get('gaps', [])
+    require(isinstance(proposals, list), 'GAP_SCHEMA', 'gaps 使用数组。')
+    for proposal in proposals:
+        require(isinstance(proposal, dict) and set(proposal) ==
+                {'id', 'targetId', 'description', 'impact', 'blocking', 'evidence'},
+                'GAP_SCHEMA', '缺口使用 id/targetId/description/impact/blocking/evidence。')
+        key, target_id = proposal['id'], proposal['targetId']
+        require(target_id in state['targets'] and tracked(target_id), 'GAP_TARGET', '缺口必须属于现有采访目标。')
+        require(catalog()['cards'][target_id]['stage'] == state['stage'], 'STAGE_SCOPE', '只登记当前阶段的采访缺口。')
+        require(text(key) and re.fullmatch(re.escape(target_id) + r'\.[a-z0-9_-]{1,48}', key)
+                and text(proposal['description']) and text(proposal['impact'])
+                and type(proposal['blocking']) is bool, 'GAP_SCHEMA', '缺口须有稳定编号、具体内容和对本目标的影响。')
+        evidence(state, proposal['evidence'])
+        require(proposal['evidence'], 'EVIDENCE_REQUIRED', '新增缺口必须有真实原话、资料或产物依据。')
+        ensure(state, target_id)
+        gaps = state['interview']['gaps']
+        old = gaps.get(key)
+        if old:
+            require(all(old[field] == proposal[field] for field in proposal), 'GAP_IMMUTABLE',
+                    '沿用已有缺口编号和含义，不能改写它以重置采访。')
+            continue
+        target_open(state, target_id)
+        require(state['targets'][target_id]['status'] not in CLOSED, 'FOLLOWUP_CLOSED', '目标已收敛，不能靠新增缺口重开。')
+        normalized = re.sub(r'\s+', '', proposal['description'])
+        require(not any(g['targetId'] == target_id and re.sub(r'\s+', '', g['description']) == normalized
+                        for g in gaps.values()), 'DUPLICATE_GAP', '相同缺口沿用原编号。')
+        gaps[key] = dict(copy.deepcopy(proposal), status='open', windowStart=0, noGainStreak=0, answers=[])
+        changed.add(target_id)
+    resolutions = patch.get('resolutions', [])
+    require(isinstance(resolutions, list), 'RESOLUTION_SCHEMA', 'resolutions 使用数组。')
+    for resolution in resolutions:
+        require(isinstance(resolution, dict) and set(resolution) == {'gapId', 'summary', 'evidence'}
+                and text(resolution['summary']), 'RESOLUTION_SCHEMA', '补充解决使用 gapId/summary/evidence。')
+        evidence(state, resolution['evidence'], inp['id'])
+        gap = state.get('interview', {}).get('gaps', {}).get(resolution['gapId'])
+        require(gap, 'GAP_NOT_FOUND', '未找到待补缺口。')
+        require(catalog()['stages'].index(catalog()['cards'][gap['targetId']]['stage']) <=
+                catalog()['stages'].index(state['stage']), 'STAGE_SCOPE', '不能提前解决后续阶段目标。')
+        gap['status'] = 'resolved'
+        gap.setdefault('resolutions', []).append(dict(copy.deepcopy(resolution), inputId=inp['id']))
+        changed.add(gap['targetId'])
+    reopen = patch.get('reopen')
+    if reopen is not None:
+        require(isinstance(reopen, dict) and set(reopen) == {'targetId', 'gapId', 'reason', 'evidence'}
+                and intent in {'resume', 'revision'} and text(reopen['reason']),
+                'REOPEN_SCHEMA', '续谈须为 resume/revision，指定 targetId/gapId/reason/evidence。')
+        target_id = reopen['targetId']
+        require(target_id in state['targets'] and tracked(target_id)
+                and catalog()['cards'][target_id]['stage'] == state['stage'], 'REOPEN_SCOPE', '仅恢复当前阶段的指定目标。')
+        evidence(state, reopen['evidence'], inp['id'])
+        progress = ensure(state, target_id)
+        gap = state['interview']['gaps'].get(reopen['gapId'])
+        require(gap and gap['targetId'] == target_id and state['targets'][target_id]['status'] in CLOSED,
+                'REOPEN_SCOPE', '仅恢复已经收口的目标及其已记录缺口。')
+        progress['reopens'].append(dict(copy.deepcopy(reopen), inputId=inp['id'],
+                                       previousWindowStart=progress['windowStart']))
+        progress.update(windowStart=len(state['targets'][target_id]['answerInputIds']),
+                        noGainStreak=0, lastGain=False, stopReason=None)
+        gap.update(windowStart=len(gap['answers']), noGainStreak=0, status='open')
+        state['targets'][target_id]['status'] = 'exploring'
+        changed.add(target_id)
+    return changed
+
+
+def assess(state, target_id, gap_id, assessment, inp):
+    require(isinstance(assessment, dict) and set(assessment) ==
+            {'hasNewInformation', 'resolved', 'summary', 'evidence'}
+            and type(assessment['hasNewInformation']) is bool and type(assessment['resolved']) is bool
+            and text(assessment['summary']), 'ASSESSMENT_REQUIRED',
+            '采访回答须提交 interview.assessment：hasNewInformation/resolved/summary/evidence。')
+    evidence(state, assessment['evidence'], inp['id'])
+    progress = ensure(state, target_id)
+    gap = state['interview']['gaps'].get(gap_id or initial_id(target_id))
+    require(gap and gap['targetId'] == target_id, 'GAP_NOT_FOUND', '未找到本轮实际展示的待答缺口。')
+    gain = assessment['hasNewInformation']
+    gap['answers'].append(dict(copy.deepcopy(assessment), inputId=inp['id']))
+    gap['noGainStreak'] = 0 if gain else gap['noGainStreak'] + 1
+    progress['noGainStreak'] = 0 if gain else progress['noGainStreak'] + 1
+    progress['lastGain'] = gain
+    if assessment['resolved']:
+        gap['status'] = 'resolved'
+    elif gap['noGainStreak'] >= NO_GAIN_LIMIT or len(gap['answers']) - gap['windowStart'] >= GAP_LIMIT:
+        gap['status'] = 'deferred'
+
+
+def settle(state):
+    for target_id, progress in state.get('interview', {}).get('targets', {}).items():
+        target, card = state['targets'][target_id], catalog()['cards'][target_id]
+        gaps = [g for g in state['interview']['gaps'].values() if g['targetId'] == target_id]
+        unresolved = [g for g in gaps if g['status'] != 'resolved'
+                      and (g['answers'] or g['id'] != initial_id(target_id))]
+        require(target['status'] != 'sufficient' or not unresolved, 'UNRESOLVED_GAP',
+                '已记录的缺口仍未解决，不能将目标标为充分；可暂放并保留范围说明。', {'targetId': target_id})
+        reason = ('target_limit' if count(state, target_id) >= card['maxAnswers'] else
+                  'no_new_information' if progress['noGainStreak'] >= NO_GAIN_LIMIT else
+                  'review_without_gain' if count(state, target_id) >= card.get('reviewAfter', card['maxAnswers'])
+                  and not progress['lastGain'] else None)
+        if target['status'] not in CLOSED:
+            if reason:
+                progress['stopReason'] = reason
+                target['status'] = 'exhausted'
+            elif any(g['status'] == 'deferred' for g in gaps) and not any(g['status'] == 'open' for g in gaps):
+                progress['stopReason'] = 'gap_limit'
+                target['status'] = 'exhausted'
+        if target['status'] in CLOSED:
+            for gap in gaps:
+                if gap['status'] == 'open':
+                    gap['status'] = 'resolved' if target['status'] == 'sufficient' else 'deferred'
+                if gap['status'] == 'deferred' and gap['description'] not in target['gaps']:
+                    target['gaps'].append(gap['description'])
+        resolved = {g['description'] for g in gaps if g['status'] == 'resolved'}
+        target['gaps'] = [description for description in target['gaps'] if description not in resolved]
+
+
+def blockers(state, stage, target_id=None):
+    return [g for g in state.get('interview', {}).get('gaps', {}).values()
+            if g['blocking'] and g['status'] != 'resolved'
+            and catalog()['cards'][g['targetId']]['stage'] == stage
+            and (target_id is None or g['targetId'] == target_id)]
+
+
+def guidance(state):
+    result = {}
+    for target_id, target in state['targets'].items():
+        if catalog()['cards'][target_id]['stage'] != state['stage'] or not tracked(target_id):
+            continue
+        card = catalog()['cards'][target_id]
+        result[target_id] = {
+            'answersThisWindow': count(state, target_id), 'maxAnswers': card['maxAnswers'],
+            'reviewDue': count(state, target_id) >= card.get('reviewAfter', card['maxAnswers']),
+            'initialGapId': initial_id(target_id),
+        }
+    return result