@givolt/i3-composer-agent 3.1.0 → 4.0.0

package/skills/i3-enterprise-sop/references/controlled-handoff.md

@@ -1,41 +0,0 @@
-# 单次受控交接
-
-<!-- i3:zh-guide:start -->
-## 中文使用说明
-
-按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
-
-默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
-<!-- i3:zh-guide:end -->
-
-本辅助 v0.4.0 处理明确选用的现有 BRD／PRD／AD／TestCase 路径登记、只读手动交接及[同主题准确组合改选](selection-handoff.md)。本次源码修订尚未测试、尚未发布。显式运行，不是自动安装的 Hook，不提供企业跨阶段 auto，不接管原 Spec／Plan／Build。当前适配项目级 CodeBuddy CLI、Python 3.9+，其他宿主和项目外来源保留手动方式。
-
-## 谁负责什么
-
-- 调用方根据用户本次实际选用意图、项目采用记录和准确主题准备请求；inputs 取直接上游、采用规约、共享契约、工程骨架及本次相关已有工作，不猜最高版本。原任务已经明确选用时直接承接，不要求使用人重复确认或填写全部资源路径。
-- 只读会话只开放 Read／Glob／Grep／Skill，原生加载唯一 SOP Skill 并完整读取必要来源；允许同次补读，不写稿、不提交 shell、不调用原 Spec、Plan 或 Build。原 Spec 仍用于另有明确委托的生成／修订任务。
-- 外层核真实回执、方法范围、文件快照和有界报告。漏读、失败、越界、报告矛盾或输入变化均停止登记，不扩权、循环重试、猜版本或改业务稿。
-- 只读预检通过且本次准确文档已明确选用，外层才以固定 argv、shell=false 执行一次 handoff.py select。初次选用或同路径复用无需候选预登记；不同既有选择走改选预览，不直接替换。
-- 写后只允许本次清单和必要原始字节历史变化。清单顶层仅 schemaVersion、scope、selected；保护其他主题、业务稿、Plan、任务及 scope／selected 内人工内容。旧 candidates／delivery 在已获准选用写入时随旧清单历史留存后移出当前文件，未知顶层字段先明确用途，不静默丢弃。
-
-## 调用约定
-
-调用方在项目外准备一次性 request.json：schemaVersion=1；operation 为 select 或 manual；work 为真实范围；manifest 为已有清单项目相对路径（manual 可省略）；reference 含 role、path，主题文档另有 capabilityId、prdId；inputs 为本次明确采用的来源路径数组；task 为真实任务。首次选用前可在本次明确权限内初始化三字段清单，入口本身不自动初始化。
-
-```bash
-python3 <资料根>/controlled_handoff.py --project-root <项目根> --request <调用方请求.json> --evidence-dir <全新项目外证据目录>
-```
-
-用户已明确选用本次准确文档时，调用方才加 --select-reference。没有选用委托则只返回原因、推荐及选项，不写清单；manual 始终零项目写入。选用不是业务批准或 Plan 开工批准，原方法停轮保持。
-
-旧候选登记／撤回操作和 --register-candidate、--withdraw-candidate 已移除，不转换为选用授权。未选稿件只保留实际文件和会话路径，不维护待审队列，不为弃用某稿而改 JSON 或删文件。
-
-同主题改选继续使用 selection-preview／selection-switch；只有真人确认准确预览，后续切换才加 --switch-selection，并经过新的只读预检及快照核对。该参数与 --select-reference 互不替代，预览不写项目。请求和结果位于项目外证据目录，不成为业务 JSON 的审批或任务状态。
-
-## 问题交互
-
-结果含 status、reason、recommendation、options 和真实登记尝试。缺来源、选用冲突、人工改稿取舍、拒绝或并发变化须保留现场，给原因及可选操作，不承诺宿主弹窗。methodIssues、工具真实失败、报告问题及文件变化分开；成功加载禁止方法属于方法越界，不能伪造为工具 failed 或 blocked。
-
-## 保证范围
-
-入口只约束由此进入的一次作业；原命令、其他会话和其他宿主不自动挂载该保护。工具限制依赖宿主执行，完整读取不证明理解或业务批准；瞬时文件快照不禁止用户以后修改，基础锁不保证跨编辑器事务。证据目录必须全新且在项目外；只有一次原生会话，无自动循环复测。旧验证记录只对旧候选流程有效，本修订未运行测试。

package/skills/i3-enterprise-sop/references/controlled_handoff.py

@@ -1,379 +0,0 @@
-#!/usr/bin/env python3
-"""One CodeBuddy readonly preflight, receipt audit, then an explicitly selected reference.
-
-Explicit adapter, not a Hook or enterprise auto. Python standard library only.
-Request/evidence are caller records, never business approval or handoff JSON state.
-"""
-import argparse
-import importlib.util
-import json
-import os
-from pathlib import Path
-import re
-import shutil
-import subprocess
-import sys
-import time
-import uuid
-
-sys.dont_write_bytecode = True
-RESOURCES = Path(__file__).resolve().parent
-
-
-def module(name, path):
-    spec = importlib.util.spec_from_file_location(name, path)
-    value = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(value)
-    return value
-
-
-native = module('controlled_native', RESOURCES/'verification/check_native_execution.py')
-handoff = module('controlled_json', RESOURCES/'handoff.py')
-selection = module('controlled_selection', RESOURCES/'selection_handoff.py')
-
-
-class Decision(ValueError):
-    def __init__(self, code, message):
-        super().__init__(message)
-        self.code = code
-
-
-def save(path, value):
-    path.write_text(json.dumps(value, ensure_ascii=False, indent=2)+'\n')
-
-
-def response(status, code, message, *, recommendation='核对所列原因，在新作业中重新只读预检。', evidence=None):
-    return {'schemaVersion': 1, 'status': status,
-            'reason': {'code': code, 'message': message, 'evidence': evidence or []},
-            'recommendation': {'id': 'readonly-preflight', 'description': recommendation},
-            'options': [{'id': 'readonly-preflight', 'label': '重新只读预检'},
-                        {'id': 'manual-handoff', 'label': '手动传递明确路径'},
-                        {'id': 'stop', 'label': '暂停并保留现场'}],
-            'registration': {'attempted': False},
-            'businessApproved': False, 'implementationApproved': False, 'published': False}
-
-
-def decision_response(error):
-    choices = {
-        'topic_choice_required': ('choose-topic', '明确 PBC 与 PRD 主题', '请明确本次 PBC 与 PRD 主题，沿用真实选定路径，不按最高版本猜测。'),
-        'work_conflict': ('choose-manifest', '确认本次工作与清单', '请确认本次工作的实际清单，保留其他工作与已有选择。'),
-        'resource_identity': ('choose-source', '确认采用来源', '请确认项目实际采用的资料来源；不切换到其他副本。'),
-        'skill_identity': ('choose-source', '确认采用来源', '请确认唯一实际安装的 SOP Skill，不自动借用其他安装。'),
-        'manifest_required': ('choose-handoff', '选择清单或手动交接', '建议先使用准确路径手动交接；需要清单时另行明确创建范围。'),
-        'selection_preview_required': ('create-preview', '先保存准确改选预览', '先只读核对准确组合与影响，再明确选择该预览；不直接替换。'),
-    }
-    choice = choices.get(getattr(error, 'code', ''))
-    out = response('needs_confirmation' if choice else 'blocked', getattr(error, 'code', 'execution_unconfirmed'), str(error))
-    if choice:
-        out['recommendation'] = {'id': choice[0], 'description': choice[2]}
-        out['options'].insert(0, {'id': choice[0], 'label': choice[1]})
-    return out
-
-
-def local_file(root, raw):
-    if not isinstance(raw, str) or not raw.strip():
-        raise Decision('missing_path', '需要明确的实际文件路径，不能由模型猜测版本。')
-    p = (root/Path(raw)).resolve()
-    if not p.is_relative_to(root) or not p.is_file() or not p.read_text(encoding='utf-8').strip():
-        raise Decision('unavailable_input', '文件须在本项目内实际可读且非空：'+raw)
-    return str(p.relative_to(root))
-
-
-def installed_resource_root(project_root):
-    """Resolve this installed Skill, never the toolkit's shared references."""
-    root = Path(project_root).resolve()
-    base = root/'.codebuddy'
-    locator = base/'.i3-composer-agent.json'
-    try:
-        metadata = native.loads(locator.read_text(encoding='utf-8'))
-    except (OSError, ValueError) as error:
-        raise Decision('resource_identity', '项目安装清单不可读或损坏，不能改用另一副本。') from error
-    if (not isinstance(metadata, dict) or metadata.get('name') != 'i3-composer-agent'
-            or not metadata.get('version') or metadata.get('scope') != 'project'):
-        raise Decision('resource_identity', '项目安装身份或作用域不一致，需先确认采用来源。')
-    catalog = metadata.get('catalog', {})
-    registered = catalog.get('skills', []) if isinstance(catalog, dict) else []
-    assets = metadata.get('assets', [])
-    aliases = ('i3-enterprise-sop', 'enterprise-sop')
-    names = [name for name in aliases if (base/'skills'/name/'SKILL.md').is_file()]
-    if (len(names) != 1 or not isinstance(registered, list)
-            or [name for name in aliases if name in registered] != names):
-        raise Decision('skill_identity', '需要唯一且已登记的项目 SOP Skill，不自动选择另一副本。')
-    name = names[0]
-    skill = base/'skills'/name
-    entry = skill/'SKILL.md'
-    resources = skill/'references'
-    required = [f'skills/{name}/SKILL.md', f'skills/{name}/references/readme.md']
-    if (not isinstance(assets, list) or not all(item in assets for item in required)
-            or not resources.resolve().is_relative_to(base.resolve())
-            or not entry.resolve().is_relative_to(base.resolve())
-            or not (resources/'readme.md').is_file()):
-        raise Decision('resource_identity', '本次 SOP Skill 的资料未完整登记或不可读；不借用共用 references。')
-    try:
-        text = entry.read_text(encoding='utf-8')
-        identity = re.match(r'\A---\s*\n(.*?)\n---(?:\s*\n|\Z)', text, re.S)
-        if not identity or not re.search(r'^name:\s*'+re.escape(name)+r'\s*$', identity[1], re.M):
-            raise Decision('skill_identity', 'SOP Skill 正文身份与安装清单不一致。')
-        if not (resources/'readme.md').read_text(encoding='utf-8').strip():
-            raise Decision('resource_identity', '本次 SOP 资料入口为空，不能改用其他副本。')
-    except OSError as error:
-        raise Decision('resource_identity', '本次 SOP Skill 或资料入口不可读。') from error
-    return resources.resolve()
-
-
-def prepare(project_root, request, *, resource_root=RESOURCES):
-    root = Path(project_root).resolve(); resources = Path(resource_root).resolve()
-    if isinstance(request, dict) and request.get('operation') in ('selection-preview', 'selection-switch'):
-        proposal = selection.plan(root, request)
-        base = dict(proposal['preflightRequest'])
-        receipt = None
-        if request['operation'] == 'selection-switch':
-            preview = Path(request.get('preview', '')).resolve()
-            if preview.is_relative_to(root) or not preview.is_file():
-                raise Decision('selection_preview_required', '须先核对项目外保存的准确预览，再明确委托该次改选。')
-            receipt = native.loads(preview.read_text())
-            if (not isinstance(receipt, dict) or receipt.get('kind') != 'i3-sop-selection-preview'
-                    or not isinstance(receipt.get('plan'), dict)
-                    or not isinstance(receipt['plan'].get('preflightRequest'), dict)
-                    or not isinstance(receipt['plan']['preflightRequest'].get('inputs'), list)):
-                raise Decision('selection_preview_required', '预览证据不符合契约，不能作为改选依据。')
-            base['inputs'] += receipt.get('plan', {}).get('preflightRequest', {}).get('inputs', [])
-        base['inputs'] += [str(resources/'selection-handoff.md')]
-        prepared = prepare(root, base, resource_root=resources)
-        prepared.update(request=request, selection=proposal, selectionReceipt=receipt)
-        return prepared
-    fields = {'schemaVersion', 'operation', 'work', 'manifest', 'reference', 'inputs', 'task'}
-    if not isinstance(request, dict) or set(request)-fields or request.get('schemaVersion') != 1:
-        raise Decision('request_contract', '调用方请求不符合单次交接契约。')
-    if request.get('operation') not in ('select', 'manual'):
-        raise Decision('explicit_enterprise_required', '本入口只接受明确选用登记或手动交接；旧候选登记及撤回操作已退出，不转换为选用授权。')
-    if not root.is_dir() or not resources.is_relative_to(root):
-        raise Decision('project_install_required', '本片仅支持项目内实际 CodeBuddy 安装；其他来源可继续手动交接。')
-    if not isinstance(request.get('work'), str) or not request['work'].strip() or not isinstance(request.get('task'), str) or not request['task'].strip():
-        raise Decision('missing_scope', '需要本次真实工作范围及任务说明。')
-    ref = request.get('reference')
-    if not isinstance(ref, dict) or set(ref)-{'role', 'path', 'capabilityId', 'prdId'} or ref.get('role') not in ('brd', 'prd', 'ad', 'testCase'):
-        raise Decision('reference_contract', '本片只登记明确的 BRD/PRD/AD/TestCase 现稿。')
-    if ref['role'] in handoff.TOPIC_ROLES and not all(isinstance(ref.get(k), str) and ref[k].strip() for k in ('capabilityId', 'prdId')):
-        raise Decision('topic_choice_required', '尚未明确 PBC 与 PRD 主题，不能按文件版本号自动选择。')
-    reference = handoff._reference(root, ref['role'], local_file(root, ref.get('path')), ref.get('capabilityId'), ref.get('prdId'))
-    inputs = request.get('inputs', [])
-    if not isinstance(inputs, list):
-        raise Decision('input_contract', '本次采用的直接上游、规约和骨架须以路径列表交接。')
-    paths = [local_file(root, p) for p in inputs]
-    locator = root/'.codebuddy/.i3-composer-agent.json'
-    if installed_resource_root(root) != resources:
-        raise Decision('resource_identity', '项目安装身份或实际资料根不一致，需先确认采用来源。')
-    locator_lines = [i for i, line in enumerate(locator.read_text().splitlines(), 1)
-                     if any(line.lstrip().startswith('"'+key+'":') for key in ('name', 'version', 'scope', 'catalog', 'skills'))
-                     or any('"'+value+'"' in line for value in (
-                         'i3-enterprise-sop', 'enterprise-sop',
-                         'skills/i3-enterprise-sop/SKILL.md', 'skills/i3-enterprise-sop/references/readme.md',
-                         'skills/enterprise-sop/SKILL.md', 'skills/enterprise-sop/references/readme.md'))]
-    selected = []
-    manifest = request.get('manifest')
-    if manifest:
-        mf = handoff._manifest_path(root, manifest)
-        local_file(root, str(mf))
-        value = handoff._load(mf.read_bytes())
-        if value['scope']['work'] != request['work']:
-            raise Decision('work_conflict', '交接清单属于其他工作范围，不能自动替换。')
-        context = value
-        if request['operation'] == 'select':
-            context = handoff._selected_only(value)
-            selection_check = json.loads(json.dumps(context['selected']))
-            handoff._assign(selection_check, reference)
-            # A first selection may name a new topic; only existing sources in
-            # that scope, plus global references, belong in the preflight.
-            context['selected']['topics'] = [
-                topic for topic in context['selected'].get('topics', [])
-                if reference['role'] in handoff.TOPIC_ROLES
-                and all(topic[key] == reference[key] for key in ('capabilityId', 'prdId'))]
-        resolved = handoff._resolve(root, context, ref.get('capabilityId'), ref.get('prdId'), ())
-        selected = [local_file(root, x['path']) for x in resolved['references']]
-        manifest = str(mf.relative_to(root))
-    elif request['operation'] == 'select':
-        raise Decision('manifest_required', '选用登记需要现有明确清单；确认采用后可授权初始化，或继续手动交接。')
-    skills = root/'.codebuddy/skills'
-    names = sorted({name for name in ('i3-enterprise-sop', 'enterprise-sop') if (skills/name/'SKILL.md').is_file()})
-    if len(names) != 1:
-        raise Decision('skill_identity', '需要唯一且可读取的项目 SOP Skill，不能选择另一安装副本。')
-    common = ['readme.md', 'stages.json', 'template-contracts.md', 'handoff-contract.md',
-              'lifecycle-contract.md', 'recovery-contract.md', 'controlled-handoff.md', 'verification/readme.md']
-    required = [local_file(root, p) for p in ('CODEBUDDY.md', 'README.md') if (root/p).is_file()]
-    required += [str(locator.relative_to(root))]+[local_file(root, str(resources/p)) for p in common]
-    required += ([manifest] if manifest else [])+[reference['path']]+selected+paths
-    required = list(dict.fromkeys(required))
-    scope = {'profile': 'status', 'requiredReads': required, 'reportInputs': required, 'allowedWrites': [],
-             'requiredSkills': names, 'files': native.inventory(root), 'gateExpectations': {},
-             'tools': ['Read', 'Glob', 'Grep', 'Skill'], 'allowedShellCommands': [],
-             'requiredReadLines': {str(locator.relative_to(root)): locator_lines},
-             'forbiddenSkills': [p.name for p in skills.iterdir() if p.is_dir() and p.name not in names]}
-    return {'root': str(root), 'resourceRoot': str(resources), 'request': request, 'reference': reference,
-            'manifest': manifest, 'scope': scope}
-
-
-def prompt_for(prepared):
-    scope = prepared['scope']
-    report = {'schemaVersion': 1, 'failedAttempts': [],
-              'inputChecks': [{'path': p, 'status': 'full'} for p in scope['reportInputs']], 'gates': []}
-    return ('本次显式企业 SOP 单次只读预检。原始任务：'+prepared['request']['task']+'\n'
-            '先实际调用 Skill '+scope['requiredSkills'][0]+'。只核现稿与真实来源，不生成或修订文档。\n'
-            '本会话仅开放 Read/Glob/Grep/Skill；不要提交 Bash、写工具或其他 Skill，外层负责后续获准登记。\n'
-            '逐项读完下列项目相对路径；允许在本次只读会话内补读漏项，不扩大来源、不选新版本。\n'
-            +json.dumps(scope['requiredReads'], ensure_ascii=False)+'\n'
-            '安装清单仅需下列行核 name/version/scope、catalog.skills 与当前 SOP Skill 的精确 assets；资料取该 Skill 的 references：'
-            +json.dumps(scope['requiredReadLines'], ensure_ascii=False)+'\n'
-            '如工具拒绝、失败、来源冲突，保留事实并说明原因、推荐、可选操作，不绕过或重复尝试。\n'
-            '结束时附且仅附一个原生执行报告块。inputChecks 路径全集固定为上面列表，状态枚举仅 full/partial/not_read；'
-            'failedAttempts 按实际非成功尝试顺序列 tool/subject/status，status 仅 blocked/failed/unconfirmed；'
-            '工具成功加载了本次禁止的方法属于方法越界，应在正文如实说明，不能伪造为工具 failed 或 blocked；'
-            'gates 固定为空数组，不创造业务或开工批准。全读成功无失败时的确切结构如下，否则按真实结果填写：\n'
-            +native.START+'\n```json\n'+json.dumps(report, ensure_ascii=False)+'\n```\n'+native.END+'\n')
-
-
-def launch(prepared, evidence, *, timeout=240, max_turns=40):
-    executable = shutil.which('codebuddy')
-    if not executable:
-        raise Decision('host_unavailable', '本机没有 CodeBuddy CLI；可使用手动路径，不自动安装依赖。')
-    argv = [executable, '-p', '--verbose', '--output-format', 'stream-json', '--permission-mode', 'default',
-            '--tools', 'Read,Glob,Grep,Skill', '--allowedTools', 'Read', 'Glob', 'Grep', 'Skill',
-            '--disallowedTools', 'Bash,Write,Edit,PowerShell,NotebookEdit,Task,Agent',
-            '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}',
-            '--max-turns', str(max_turns), '--session-id', str(uuid.uuid4())]
-    save(evidence/'invocation.json', {'argv': argv, 'cwd': prepared['root'], 'attempts': 1,
-                                     'modelOverridden': False, 'systemPromptOverridden': False})
-    (evidence/'prompt.txt').write_text(prompt_for(prepared))
-    started = time.monotonic(); timed_out = False
-    with (evidence/'prompt.txt').open('rb') as inp, (evidence/'trace.jsonl').open('wb') as out, (evidence/'stderr.log').open('wb') as err:
-        proc = subprocess.Popen(argv, cwd=prepared['root'], stdin=inp, stdout=out, stderr=err,
-                                env={**os.environ, 'CODEBUDDY_DISABLE_AUTO_MEMORY': '1', 'CODEBUDDY_CODE_DISABLE_AUTO_MEMORY': '1'})
-        try:
-            proc.wait(timeout=timeout)
-        except subprocess.TimeoutExpired:
-            timed_out = True; proc.terminate()
-            try:
-                proc.wait(timeout=10)
-            except subprocess.TimeoutExpired:
-                proc.kill(); proc.wait()
-    process = {'exitCode': proc.returncode, 'timedOut': timed_out, 'elapsedSeconds': round(time.monotonic()-started, 2)}
-    save(evidence/'process.json', process)
-    events = [native.loads(line) for line in (evidence/'trace.jsonl').read_text().splitlines() if line.strip()]
-    return events, process
-
-
-def finish(prepared, events, process, evidence, *, select_reference=False, switch=False):
-    root = Path(prepared['root']); evidence = Path(evidence)
-    audit = native.assess(root, prepared['scope'], events, process)
-    save(evidence/'preflight-audit.json', audit)
-    if not audit['passed']:
-        out = response('blocked', 'preflight_failed', '实际读取、调用、报告或文件边界未通过；本次不启动登记。', evidence=['preflight-audit.json', 'trace.jsonl'])
-        out['reason']['details'] = {
-            'incompleteInputs': [x['path'] for x in audit['inputs']['checks'] if x['status'] != 'full'],
-            'failedAttempts': [x for x in audit['attempts'] if x['status'] != 'succeeded'],
-            'methodIssues': audit['nativeMethods']['issues'],
-            'unexpectedChanges': audit['boundaries']['changedFiles'],
-            'reportIssues': audit['reportConsistency']['issues'],
-            'executionIssues': audit['toolDiscipline']['issues']}
-        return out
-    if native.inventory(root) != prepared['scope']['files']:
-        return response('blocked', 'project_changed', '预检后项目发生变化，须回读当前内容，不能覆盖人工修改。')
-    if 'selection' in prepared:
-        return selection.finish(prepared, evidence, authorized=switch, response=response)
-    if prepared['request']['operation'] == 'manual':
-        out = response('manual_ready', 'readonly_handoff_ready', '手动交接路径已只读核对，未创建或更新 JSON。')
-        out['references'] = {'primary': prepared['reference'], 'inputs': prepared['request'].get('inputs', [])}
-        return out
-    if not select_reference:
-        out = response('needs_confirmation', 'selection_not_authorized', '只读预检通过，但尚无本次准确文档的明确选用委托。', recommendation='核对准确文档及配套后明确选用；已有明确委托可由调用方直接承接，不重复询问。')
-        out['options'].insert(0, {'id': 'authorize-selection', 'label': '明确采用这份文档并登记'})
-        out['recommendation']['id'] = 'authorize-selection'
-        return out
-    helper = Path(prepared['resourceRoot'])/'handoff.py'
-    ref = prepared['reference']; request = prepared['request']
-    mf = root/prepared['manifest']; before = mf.read_bytes(); previous = handoff._load(before)
-    expected = handoff._selected_only(previous)
-    handoff._assign(expected['selected'], ref)
-    args = [sys.executable, str(helper), 'select', '--project-root', str(root), '--manifest', prepared['manifest'],
-            '--work', request['work'], '--role', ref['role'], '--path', ref['path']]
-    for key, flag in [('capabilityId', '--capability-id'), ('prdId', '--prd-id')]:
-        if key in ref:
-            args += [flag, ref[key]]
-    record = {'attempted': False, 'helper': str(helper), 'argv': args, 'shell': False, 'attempts': 0}
-    help_run = subprocess.run([sys.executable, str(helper), '--help'], capture_output=True, text=True, timeout=20)
-    save(evidence/'helper-help.json', {'exitCode': help_run.returncode, 'stdout': help_run.stdout, 'stderr': help_run.stderr})
-    if help_run.returncode or native.inventory(root) != prepared['scope']['files']:
-        return response('blocked', 'helper_precheck_failed', '接口核对失败或项目已变化，不执行登记。')
-    record.update(attempted=True, attempts=1)
-    try:
-        proc = subprocess.run(args, capture_output=True, text=True, timeout=20)
-        record.update(exitCode=proc.returncode, stdout=proc.stdout, stderr=proc.stderr)
-        result = native.loads(proc.stdout)
-        record['result'] = result
-    except (OSError, subprocess.TimeoutExpired, ValueError) as exc:
-        record['error'] = str(exc); result = {}
-    save(evidence/'registration.json', record)
-    if record.get('exitCode') != 0 or result.get('ok') is not True:
-        out = response('blocked', 'registration_failed', '登记失败或结果未确认；保留现稿、清单和锁，不重试或旁路写入。', evidence=['registration.json'])
-        out['registration'] = record
-        return out
-    changed = native.inventory(root)
-    delta = sorted(k for k in set(changed)|set(prepared['scope']['files']) if changed.get(k) != prepared['scope']['files'].get(k))
-    allowed = [prepared['manifest']]
-    history = result.get('history')
-    historical = None
-    if history:
-        hp = handoff._manifest_path(root, history)
-        allowed.append(str(hp.relative_to(root))); historical = hp.read_bytes()
-    current = handoff._load(mf.read_bytes())
-    expected_change = expected != previous
-    passed = (current == expected and result.get('changed') is expected_change
-              and set(delta) == (set(allowed) if expected_change else set())
-              and (historical == before if expected_change else history is None))
-    save(evidence/'readback.json', {'passed': passed, 'changedFiles': delta, 'manifest': current,
-                                  'historyMatchesPreviousBytes': historical == before if history else None,
-                                  'businessDocumentsChanged': False if passed else None})
-    out = response('selected' if passed and expected_change else 'unchanged' if passed else 'blocked',
-                   'reference_selected' if passed else 'postcheck_failed',
-                   '明确选用的引用已登记并回读；业务稿、其他主题和原Plan保持，计划批准另行处理。' if passed else '登记后差量不符合约定，保留实际现场交人工核对，不自动回滚。',
-                   evidence=['preflight-audit.json', 'registration.json', 'readback.json'])
-    out['registration'] = record
-    return out
-
-
-def run(project_root, request, evidence_dir, *, select_reference=False, switch=False, timeout=240, max_turns=40):
-    root = Path(project_root).resolve(); evidence = Path(evidence_dir).resolve()
-    if evidence.is_relative_to(root) or evidence.exists():
-        raise ValueError('evidence directory must be new and outside the project; never overwrite a prior run')
-    evidence.mkdir(parents=True)
-    save(evidence/'request.json', request)
-    try:
-        prepared = prepare(root, request)
-        save(evidence/'before.json', prepared)
-        events, process = launch(prepared, evidence, timeout=timeout, max_turns=max_turns)
-        out = finish(prepared, events, process, evidence, select_reference=select_reference, switch=switch)
-    except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError) as exc:
-        out = decision_response(exc)
-        out['reason']['evidence'].append('request.json')
-    save(evidence/'result.json', out)
-    return out
-
-
-def main():
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('--project-root', required=True)
-    parser.add_argument('--request', required=True, help='caller-prepared explicit task/paths, not approval state')
-    parser.add_argument('--evidence-dir', required=True)
-    parser.add_argument('--select-reference', action='store_true', help='only with actual user selection of this exact document; not candidate-registration permission')
-    parser.add_argument('--switch-selection', action='store_true', help='only with actual delegation for the exact saved selection preview')
-    parser.add_argument('--timeout', type=int, default=240)
-    parser.add_argument('--max-turns', type=int, default=40)
-    args = parser.parse_args()
-    out = run(args.project_root, native.loads(Path(args.request).read_text()), args.evidence_dir,
-              select_reference=args.select_reference, switch=args.switch_selection, timeout=args.timeout, max_turns=args.max_turns)
-    print(json.dumps(out, ensure_ascii=False, indent=2))
-    return 0 if out['status'] in ('selected', 'unchanged', 'manual_ready') else 2
-
-
-if __name__ == '__main__':
-    sys.exit(main())

package/skills/i3-enterprise-sop/references/engineering-skeleton/adoption.md

@@ -1,200 +0,0 @@
-# 工程目录规范的采用与原 Plan／Build 交接
-
-<!-- i3:zh-guide:start -->
-## 中文使用说明
-
-按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
-
-默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
-<!-- i3:zh-guide:end -->
-
-版本：1.0.0。配套：[工程目录规范](directory-standard.md)。适用于明确选择该规范的新项目或现有项目，不随安装自动启用。§1—5 以企业 AD 交接为例；标准项目沿用自己的 SPEC 或等效规格，不补企业文档。存量接入、选择性更新和人工保护见 §6；入口与资源索引见 [README](readme.md)。
-
-## 1. 采用时明确什么
-
-先确定真实业务项目根、当前能力／需求主题、所选 AD 及已有代码位置。项目已有工程规范时优先复用；本资源补充目录职责或映射，不重选技术栈，也不把维护 i3 Skill 的仓库当成业务工程根。
-
-目录规范可以在 AD 准备时选定，无需另外调用一个工程骨架命令。技术栈、工程内部布局及构建命令仍由公共技术规约、实际配置和 AD 明确。目录规范能够先采用；尚未确定的技术决策只限制依赖它的设计或实施任务。
-
-将采用结果写入项目已有工程说明；没有合适位置时，可使用 docs/engineering/engineering-layout.md，或直接写在 AD 的相应章节。以下是填写要点，实际路径和状态据实填写，不为每个项目重复建立全部文档：
-
-| 项目 | 填写内容 |
-| --- | --- |
-| 采用来源 | 实际采用规范的真实可读路径及正文版本（本资源为 1.0.0）；使用项目副本时保留其来源、明确选用范围及本项目修改说明 |
-| 组织方式 | pbc-composite 或 agent-standalone；选择理由与项目根 |
-| 实际工程映射 | 工程稳定标识、类别、实际根、已有／拟建、业务模块、共享维护方与消费者 |
-| 配套依据 | 当前 AD 的身份／版本／路径、公共技术规约、必要契约及已有代码 |
-| 目录例外 | 现有结构或框架惯例与规范示例的差异、理由、影响及明确采用情况 |
-| 验证要求 | 本次文件落点核对及实际构建／测试方法；尚无代码时写待实施，不预填通过 |
-
-使用项目已采用副本后，以该副本为本次输入；发行资源更新不覆盖它。原路径失效、版本含糊或映射冲突时先说明准确缺项，不静默改读另一个来源。
-
-## 2. AD 如何引用
-
-沿用现有 AD 模板的栏目，不修改模板或原 Spec：
-
-| 现有 AD 位置 | 本次承接内容 |
-| --- | --- |
-| §0.3 公共技术规约、契约与骨架的本次采用 | 引用目录规范或项目采用说明的准确路径／版本，说明适用工程 |
-| §9.2 项目目录与维护位置 | 工程根、模块／源码、配置、测试、契约和运行装配的真实或拟建路径及 owner |
-| §9.6 工程骨架采用与落地 | 区分现有工程事实与拟建内容；落实当前技术选择、构建／启动／验证／恢复条件及依赖缺口 |
-
-其他版本的 AD 使用同义栏目。AD 的整体技术架构图、功能架构图、数据实体关系及必要详细设计仍完整保留，不能以目录规范替代。
-
-目录标准是实际可读的规范输入，不能据此把“可运行代码模板已取得”或“工程已生成”填为成功。未采用代码框架模板时可据实写“目录规范已采用；工程拟建；未采用代码框架模板”；语言／框架代码由后续获准任务实现。已有代码则引用真实代码／配置。若本项目另行要求复用特定代码模板，仍需取得它，不由本规范替代。
-
-一个 PBC 多份主题 PRD 的各自 AD 引用同一项目规范，并分别映射相关模块；不因 PRD 数量或版本变化重复创建工程。
-
-## 3. 交给原 Plan 的方式
-
-原 Plan 读取 SPEC.md 或等效规格。选定 AD 与其准确 PRD、公共技术规约、契约及目录采用说明共同提供本次等效规格；原 SPEC 六项内容须足够明确。独立 TestCase 为可选输入，已有且适用就引用；原型按需，可与 AD 并行。
-
-手动方式直接提供上述实际路径。已有三字段 JSON 时，可让本次任务先解析 selected 中当前主题的 engineeringSkeleton 及配套路径，再实际读取正文；选择路径不等于读取成功、认可或实施许可。无需为了目录规范新建 JSON，也不把工程说明写入新的顶层字段。
-
-先按当前主题读采用说明和必要规范条款，再读该主题 AD／PRD、所涉代码和共享消费者；不一次加载全部历史、所有主题或所有工程源码。跨主题共用约束及直接依赖仍须读齐。
-
-在项目根使用以下提示；替换方括号中的实际路径。它是原命令的明确任务上下文，不是新增命令参数：
-
-```text
-/i3-plan
-为本次已明确的需求范围制定计划：
-AD：[实际 AD 路径]；准确 PRD：[实际 PRD 路径]。
-公共技术规约：[已采用规范路径]；工程目录采用说明：[实际路径]。
-必要共享契约及已有代码：[实际路径；没有则说明不适用]。
-请实际读取这些来源；缺项或冲突先列出，不猜技术版本。
-按 AD 的工程／模块映射拆任务，明确新增或修改文件相对项目根的位置、
-工程负责人／共享依赖、验收条件及实际验证方法。
-将源码、配置和测试放入已采用位置；已有结构的例外明确写在计划里。
-保留原 Plan 的默认产物、唯一任务目标和审阅停点，不改业务稿。
-```
-
-计划沿用 tasks/plan.md 和原方法确定的唯一任务目标；默认文件目标为 tasks/todo.md，采用其他 tracker 时不复制竞争状态。不同未完成工作不覆盖。工程落点不是把模块名写入任务即可：任务的 Files likely touched 应包含预计路径，验收条件要核对真实新增／修改文件；实施中合理新增文件也须按映射核对。
-
-## 4. 原 Build 如何执行
-
-计划满足原有认可及执行条件后，原 Build 从计划取任务。任务必须指向当前 AD、目录采用说明和所需规范，使执行时能实际回读，而非只相信计划摘要或 JSON 的存在。
-
-```text
-/i3-build
-执行当前计划的下一项获准任务。
-先回读该任务引用的 AD、目录采用说明及所需规范／代码。
-按已采用工程根和模块路径实现；出现目录冲突先说明位置、原因和建议，
-不自行另建同名工程或把源码放进 spec、tasks、文档模板目录。
-完成原有验证后，对照任务及目录映射列出实际变更文件和落点差异。
-业务稿、人工代码和已完成任务按原规则保留。
-```
-
-原 /i3-build auto 使用同一份获准 Plan 和目录映射，保持原有 spec/ 识别、Git、计划认可、TDD／构建及逐任务执行条件。它不会因为本资源存在而自动读取规范；需要时在本次任务上下文明确引用。企业跨阶段 auto／调度不在本资源范围。
-
-规范期望目录约束被设计、任务和验收共同落实，不提供拦截一切写入的 Hook。未实际读取、任务没有落点或实际文件越界时，不声称目录验收通过。
-
-## 5. Build 后如何核目录
-
-在实际业务项目中核对本次任务新增、修改和必要删除的文件。可用 git status --short、针对任务的 git diff／文件清单及实际配置获取事实；不把其他人的未提交文件混作本次结果，也不只看空目录树。
-
-| 核对项 | 通过条件 |
-| --- | --- |
-| 来源与范围 | 当前 AD、目录采用说明及任务可回读，采用版本和实际工程根一致 |
-| 文件落点 | 每个变更文件都能映射到工程／模块、共用资产或原有管理文档位置；例外有明确依据 |
-| 工程边界 | 同一工程标识未重复创建，未按每份 PRD 再造底座；没有未经采用的顶层代码目录 |
-| 共享责任 | 契约、共用代码及跨工程测试各有实际维护位置与相关消费者，未复制其他主题的共享权威 |
-| 构建与测试 | 实际配置的源码、资源、测试和产物路径与采用映射一致；完成本次要求的原有验证 |
-| 人工内容 | 既有目录、项目自改规范、人工代码和已完成任务保留；无整仓覆盖或未经说明的移动／删除 |
-
-结果沿用原工程验证记录或本次任务总结，至少列出“文件／实际位置／采用依据／差异处理／验证结果”。不另建任务完成率或审批状态文件。构建产物、依赖、缓存按实际工具配置和忽略规则处理，不因出现 dist、target、node_modules 等就判源码越界。
-
-落点有偏差时先标注准确位置、影响、推荐和可选处理（按规范调整，或明确采用例外后同步 AD／Plan），不自动移动人工代码或改业务稿。目录核对通过与构建、业务测试、独立审查、Ship 就绪及发布分别记录。
-
-## 6. 现有工程与后续变更
-
-### 6.1 先确定本次范围与真实现状
-
-仅在本次任务明确采用或项目已采用指引指定时读取本资源。标准项目沿用自己的 SPEC 或等效规格，目录采用不要求补企业 BRD／PRD／AD；§2—5 的 AD 交接是企业 SOP 用法，标准项目将相同目录依据交给自己的规格与原 Plan。安装、目录存在、PRD 或 JSON 字样不激活企业 SOP。
-
-先确定实际业务项目根、本次需求／工程范围、已选规格、当前采用说明和唯一任务目标，再只读检查相关工程入口、源码／测试、构建／运行配置、项目自改说明及必要共享消费者。按当前主题加载必要来源和直接依赖，不一次读全部历史或所有工程；不猜语言／框架版本，不因缺项重选技术栈。
-
-### 6.2 把现有目录映射到逻辑职责
-
-| 逻辑职责 | 现有位置示例 | 映射与保护要求 |
-| --- | --- | --- |
-| frontend | web/、apps/console/ | 保留前端工程标识、框架入口和内部结构；不另外生成同名 frontend 工程 |
-| backend | services/asset-api/、server/ | 映射真实源码／测试／配置位置，不再建 backend/asset-api/ 的第二套底座 |
-| agents | 项目根“.”、已有服务内模块、agents/ 下工程 | 独立 Agent 可沿用根布局；服务内组件映射真实子路径，不强行拆工程 |
-| jobs | worker/、jobs/、现有后端任务模块 | 按触发与执行职责映射；目录名不决定进程或部署边界 |
-| 共用资产与配置 | 既有契约、shared、测试、CI／运行装配位置 | 保留实际维护位置、owner 和消费者；不按每份 PRD 复制共享权威 |
-
-采用结果复用项目现有工程说明，或写入当前规格；没有合适载体时才按需使用 docs/engineering/engineering-layout.md。至少列出来源／版本、项目根与组织方式、工程稳定标识及类别、实际根、已有／拟建、源码／配置／测试位置、维护方／消费者、例外与理由、真实验证命令和未定项。不要求每个项目重复建全部文档。
-
-在只读接入阶段，输出映射建议、缺项和影响，不创建目录、不写采用说明、不改业务稿或 JSON。人明确采用后才更新获准的工程说明；规格变化可由人修改或按原 Spec 形成候审稿，I5 不自动修业务稿。缺失事实只限制依赖它的任务，不能无依据阻断其他范围。
-
-已有不同工作的未完计划时，指出准确冲突并保留 tasks/plan.md、todo 或已有 tracker；不覆盖、批量关闭或另建竞争任务库。接入规范不清除旧任务、未提交改动或原始失败记录。
-
-### 6.3 比较新资源，再明确选择
-
-实际读取项目当前采用说明／副本，以及本次明确比较的新资源；先展示准确路径、正文版本、条款差异、项目例外和受影响工程／规格／未完任务。如有可读的旧采用来源，可辅助判断；没有时列明无法确定之处，不猜哪些段落属于用户修改，不建立新的基线库或自动合并器。
-
-| 选择 | 可写范围 | 后续依据 |
-| --- | --- | --- |
-| 保留当前 | 项目采用资料、业务稿、JSON、代码和历史均不写；在本次答复说明选择即可 | 继续读取原采用文件，不因新资源可读而换源 |
-| 部分采用 | 仅更新明确选中的条款及必要采用说明；保留其余本地约定和人工段落 | 标明选用来源／版本、选中条款及本地例外，不宣称整套新版都已采用 |
-| 整体采用 | 明确替换的是哪些规范内容，并逐项说明人工差异如何保留或处理；变更前保留原文件历史 | 新项目采用资料成为依据；整体采用不等于整文件／整仓覆盖或源码迁移 |
-
-人已明确选择且范围充分时继续完成该范围，不重复索要同一确认。涉及未明确的冲突，先给出准确位置、影响、推荐和可选操作：保留原约定、采用具体条款，或先人工修改。审查只标注问题，保留人工修改空间；不以审查意见自动修业务稿。
-
-仅改获准位置，保留人工代码、项目副本、其他主题及已完成任务。无法区分段落或文件归属时先列冲突，不把整个文件当成可替换生成物。选定新规则与现有规格／任务不一致时，先处理受影响范围，再实施依赖它的任务；采用说明更新不自动扩大已有 Build／auto 授权。
-
-### 6.4 版本和引用如何传递
-
-资源版本、项目采用内容和已实现工程分别核对。1.0.0 是资源内容版本，不使项目规格、工程代码或软件发行版自动升级。项目采用内容沿用现有文档版本／变更记录；版本从实际文件名与正文回读，不新增强制版本字段、成功锁或另一套状态库。
-
-手动方式直接交入当前规格、已采用说明及必要技术规范／契约／代码的实际路径。已有业务 JSON 顶层仍只有 schemaVersion、scope、selected，需要时沿用 selected.topics 中该主题 engineeringSkeleton 的字符串路径。没有 JSON 可以继续，不为本资源强制新建清单。
-
-采用文件路径未变时，JSON 不为记录版本重复写入；同路径人工改稿后重新读当前正文并核对任务，不要求保持旧 SHA256，不凭旧报告沿用认可。路径确需改选时，在人明确采用后沿用现有交接工具的准确预览／确认规则，只改相关主题引用并保留历史；其他 selected 和人工内容保留。不增加更新、迁移、候选、交付或审批字段。
-
-已选来源不可读或版本含糊时，展示缺项、影响和可选操作，不静默改读全局／另一路径或最高版本。原采用路径若直接指向已被升级替换的安装文件、旧版已不可读，就不能声称“仍使用旧版”；由人选择采用当前真实版本，或从实际可读历史恢复项目副本，不伪造旧内容。
-
-安装目录和项目采用副本分开。曾直接修改安装文件时，先识别并另存为项目资料，再处理升级。本规则保护采用作业中的项目自改内容，不证明原安装器已保护所有安装目录修改；安装／分发行为另按实际合同验证。
-
-### 6.5 需要物理迁移时交给原 Plan／Build
-
-规范更新默认不移动代码。只有真实工程、维护、构建或部署需求才提出迁移，不能仅因旧路径与示例不同就改名。目录迁移方案复用已有规格／工程说明与原 Plan，不另建迁移登记库。
-
-迁移任务须明确旧路径→新路径、实际涉及文件、共同消费者、导入引用、源码／测试／资源及构建／运行／CI／部署配置、人工与未提交内容保护、验证方法和失败恢复范围。企业项目按所选 AD 衔接；标准项目用本次规格承接。未知影响不能填为已核对。
-
-原 Plan 实际读取后，将文件路径、依赖、验收和恢复写进 tasks/plan.md 与原方法确定的唯一任务目标，保留计划认可停点。获准原 Build 回读任务所需来源，只处理明确清单，核实际新增／修改／必要删除文件和共享消费者；不以采用规范为由整仓复制、整目录覆盖或递归删除。
-
-完成本次要求的程序测试、构建和消费者回归，按 §5 核真实落点。只检查过 CI／部署配置而未实际运行时分别说明，不能报为运行通过。迁移完成不清除旧完成任务，以新任务记录本次变化；撤销未实施需求不自动删工程，功能退役另有明确移除／迁移／回归任务。
-
-恢复复用项目已有 Git／备份和明确文件范围，保留本地及其他人的修改，不执行整仓 reset 或覆盖人工内容来还原。计划认可、单任务实施、目录验收、业务审查和发布按各自原条件执行，不由 JSON 或目录存在推导。
-
-### 6.6 可复制的任务说明
-
-以下是自然语言任务或原命令的任务上下文，不是新参数。已采用指引能准确定位时先按指引查找并展示来源，只向用户补问缺少的选择或事实。
-
-```text
-先只读检查当前项目已采用的工程说明、当前规格、相关代码／构建配置和未完计划。
-按现状列出工程类别、真实根、源码／测试位置、维护方与必要例外。
-优先保留已有目录和人工内容，不生成目录、不搬代码、不改业务稿或 JSON。
-给出映射建议、准确缺项、推荐和可选操作，交我决定。
-```
-
-```text
-比较项目当前采用说明与本次明确的新目录资源；先展示实际路径和正文版本。
-按项目已采用指引查找，不能准确定位的来源再向我确认，不自动选最高版本。
-列出条款差异及对当前规格／未完任务的影响，保留人工约定。
-我尚未选择时只给建议；我明确选择后仅更新获准条款并展示差量、保留原文件历史。
-未采用的条款不写回，目录不迁移，业务稿和代码不自动修改。
-```
-
-```text
-/i3-plan
-依据当前明确采用的工程说明和本次规格，规划已明确的目录调整：
-旧位置：[路径] → 新位置：[路径]；范围：[文件／模块]。
-先实际读取所选来源、代码、引用和相关配置；按需读直接消费者。
-每项任务写明文件路径、人工内容保护、测试／构建和失败恢复方法。
-保留原计划／唯一任务目标和已完成事实；本轮只规划，等待原有认可后再 Build。
-```
-
-获准后使用原 /i3-build 执行当前明确任务，要求回读采用依据、核实际文件与配置落点，并如实列出验证和未通过项。原 /i3-build auto 的原有条件保持，不把上述迁移任务扩展为企业跨阶段调度。
-
-本节提供作业规则，不能代替真实调用／读取、任务认可、文件保护和迁移结果的证据；没有运行的步骤保留待验证，原始失败和人工处理意见不转写为通过。