@givolt/i3-composer-agent 2.3.7 → 3.1.0

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

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""Path-only SOP handoff helper. Never writes business documents or approvals."""
+import argparse
+import copy
+import json
+import os
+from pathlib import Path
+import tempfile
+import uuid
+
+VERSION = '0.2.0'
+GLOBAL_ROLES = {'brd', 'technicalBaseline'}
+TOPIC_ROLES = {'prd', 'ad', 'testCase', 'prototype', 'engineeringSkeleton', 'contracts'}
+
+
+def _unique(pairs):
+    value = {}
+    for key, item in pairs:
+        if key in value:
+            raise ValueError('duplicate JSON key: ' + key)
+        value[key] = item
+    return value
+
+
+def _nonstandard(value):
+    raise ValueError('nonstandard JSON constant: ' + value)
+
+
+def _load(raw):
+    value = json.loads(raw, object_pairs_hook=_unique, parse_constant=_nonstandard)
+    if not isinstance(value, dict) or type(value.get('schemaVersion')) is not int or value['schemaVersion'] != 1:
+        raise ValueError('unsupported handoff schemaVersion; no automatic migration')
+    scope = value.get('scope')
+    if not isinstance(scope, dict) or not isinstance(scope.get('work'), str) or not scope['work'].strip():
+        raise ValueError('scope.work must identify the actual work')
+    if not isinstance(value.get('selected'), dict):
+        raise ValueError('selected must be an object')
+    topics = value['selected'].get('topics', [])
+    if not isinstance(topics, list):
+        raise ValueError('selected.topics must be an array')
+    seen = set()
+    for topic in topics:
+        if not isinstance(topic, dict) or not all(isinstance(topic.get(k), str) and topic[k].strip() for k in ['capabilityId', 'prdId']):
+            raise ValueError('topic requires capabilityId and prdId')
+        identity = (topic['capabilityId'], topic['prdId'])
+        if identity in seen:
+            raise ValueError('ambiguous duplicate topic selection')
+        seen.add(identity)
+    return value
+
+
+def _selected_only(value):
+    """Canonical writes; legacy draft indexes never become selected inputs."""
+    unexpected = set(value) - {'schemaVersion', 'scope', 'selected', 'candidates', 'delivery'}
+    if unexpected:
+        raise ValueError('unrecognized top-level fields; preserve the original and resolve their purpose before writing: '
+                         + ', '.join(sorted(unexpected)))
+    return {key: copy.deepcopy(value[key]) for key in ('schemaVersion', 'scope', 'selected')}
+
+
+def _manifest_path(root, raw):
+    if not raw:
+        raise ValueError('an explicit manifest path is required for this operation')
+    path = Path(raw)
+    path = Path(os.path.abspath(path if path.is_absolute() else root / path))
+    if not path.resolve().is_relative_to(root):
+        raise ValueError('manifest must stay inside the explicit project root')
+    current = path
+    while current != root:
+        if current.is_symlink():
+            raise ValueError('manifest path must not traverse symbolic links')
+        current = current.parent
+        if current == current.parent and current != root:
+            raise ValueError('manifest path is outside project root')
+    return path
+
+
+def _reference(root, role, raw, capability_id=None, prd_id=None):
+    if role not in GLOBAL_ROLES | TOPIC_ROLES:
+        raise ValueError('unknown reference role')
+    if not isinstance(raw, str) or not raw.strip():
+        raise ValueError('reference path must be explicit')
+    path = Path(raw)
+    resolved = (path if path.is_absolute() else root / path).resolve()
+    if not path.is_absolute() and not resolved.is_relative_to(root):
+        raise ValueError('relative reference escapes project root; use an explicitly adopted absolute source')
+    if resolved.is_file():
+        if not resolved.read_text(encoding='utf-8').strip():
+            raise ValueError('empty document is not a complete handoff reference')
+    elif role != 'engineeringSkeleton' or not resolved.is_dir():
+        raise ValueError('reference missing or unreadable: ' + raw)
+    result = {'role': role, 'path': str(resolved.relative_to(root)) if resolved.is_relative_to(root) else str(resolved)}
+    if role in TOPIC_ROLES:
+        if not all(isinstance(x, str) and x.strip() for x in [capability_id, prd_id]):
+            raise ValueError('topic reference requires explicit capabilityId and prdId')
+        result.update(capabilityId=capability_id, prdId=prd_id)
+    return result
+
+
+def _assign(selected, reference, *, transient=False):
+    role, path = reference['role'], reference['path']
+    target = selected
+    if role in TOPIC_ROLES:
+        topics = selected.setdefault('topics', [])
+        matches = [x for x in topics if x['capabilityId'] == reference['capabilityId'] and x['prdId'] == reference['prdId']]
+        if len(matches) > 1:
+            raise ValueError('ambiguous duplicate topic selection')
+        if matches:
+            target = matches[0]
+        else:
+            target = {k: reference[k] for k in ['capabilityId', 'prdId']}
+            topics.append(target)
+    if role == 'contracts':
+        values = target.setdefault(role, [])
+        if not isinstance(values, list) or not all(isinstance(x, str) for x in values):
+            raise ValueError('contracts must be a path array')
+        if transient:
+            target[role] = [path]
+        elif path not in values:
+            values.append(path)
+    else:
+        if not transient and role in target and target[role] != path:
+            raise ValueError('existing selection differs; replacement and affected-pair recovery belong to S08')
+        target[role] = path
+
+
+def _resolve(root, value, capability_id, prd_id, manual):
+    selected = copy.deepcopy(value['selected'])
+    topics = selected.get('topics', [])
+    if bool(capability_id) != bool(prd_id):
+        raise ValueError('provide both capabilityId and prdId')
+    if not capability_id and len(topics) == 1:
+        capability_id, prd_id = topics[0]['capabilityId'], topics[0]['prdId']
+    manual_roles = set()
+    for item in manual:
+        role, separator, path = item.partition('=')
+        if not separator or role in manual_roles:
+            raise ValueError('manual references require one unambiguous ROLE=PATH per role')
+        manual_roles.add(role)
+        reference = _reference(root, role, path, capability_id, prd_id)
+        _assign(selected, reference, transient=True)
+    topics = selected.get('topics', [])
+    if not capability_id and len(topics) > 1:
+        raise ValueError('multiple topics; explicitly choose capabilityId and prdId')
+    references = []
+    for role in sorted(GLOBAL_ROLES):
+        if role in selected:
+            references.append(_reference(root, role, selected[role]))
+    matches = [x for x in topics if x['capabilityId'] == capability_id and x['prdId'] == prd_id]
+    if capability_id and topics and not matches:
+        raise ValueError('requested topic is not selected; no highest-version fallback')
+    for topic in matches:
+        for role in sorted(TOPIC_ROLES):
+            if role not in topic:
+                continue
+            paths = topic[role] if role == 'contracts' else [topic[role]]
+            if not isinstance(paths, list):
+                raise ValueError('contracts must be a path array')
+            for path in paths:
+                references.append(_reference(root, role, path, capability_id, prd_id))
+    for reference in references:
+        path = Path(reference['path'])
+        reference['resolvedPath'] = str(path if path.is_absolute() else root / path)
+    return {'ok': True, 'changed': False, 'source': 'manual' if manual else 'manifest',
+            'scope': value['scope'], 'references': references,
+            'proof': 'paths read now; caller must verify current identity, upstream, scope and actual human decisions'}
+
+
+def _store(root, path, old, value):
+    value = _selected_only(value)
+    if old is not None and _load(old) == value:
+        return {'ok': True, 'changed': False, 'manifest': str(path.relative_to(root))}
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lock = path.with_name(path.name + '.lock')
+    try:
+        fd = os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError as error:
+        raise ValueError('handoff writer is busy; leave existing files unchanged') from error
+    os.close(fd)
+    temporary = None
+    try:
+        if (path.read_bytes() if path.exists() else None) != old:
+            raise ValueError('manifest changed since read; stop and re-read')
+        history = None
+        if old is not None:
+            history = _manifest_path(root, str(path.parent / 'history' / (path.stem + '-' + uuid.uuid4().hex + '.json')))
+            history.parent.mkdir(exist_ok=True)
+            history.write_bytes(old)
+        fd, name = tempfile.mkstemp(prefix=path.name + '.', suffix='.tmp', dir=path.parent)
+        temporary = Path(name)
+        with os.fdopen(fd, 'w', encoding='utf-8') as stream:
+            json.dump(value, stream, ensure_ascii=False, indent=2)
+            stream.write('\n'); stream.flush(); os.fsync(stream.fileno())
+        if (path.read_bytes() if path.exists() else None) != old:
+            raise ValueError('manifest changed during update; stop without replacing it')
+        if old is None:
+            os.link(temporary, path)
+        else:
+            os.replace(temporary, path)
+        if _load(path.read_bytes()) != value:
+            raise ValueError('saved manifest readback differs')
+        result = {'ok': True, 'changed': True, 'manifest': str(path.relative_to(root))}
+        if history:
+            result['history'] = str(history.relative_to(root))
+        return result
+    finally:
+        if temporary and temporary.exists():
+            temporary.unlink()
+        lock.unlink()
+
+
+def execute(project_root, manifest, action, *, work=None, role=None, path=None,
+            capability_id=None, prd_id=None, manual=()):
+    root = Path(project_root).resolve()
+    if not root.is_dir():
+        raise ValueError('explicit project root must already exist')
+    if action == 'resolve':
+        if manifest:
+            target = _manifest_path(root, manifest)
+            if not target.is_file():
+                raise ValueError('manifest missing; no automatic creation in read-only resolve')
+            value = _load(target.read_bytes())
+            if work is not None and work != value['scope']['work']:
+                raise ValueError('manifest belongs to a different work scope')
+        elif manual and isinstance(work, str) and work.strip():
+            value = {'schemaVersion': 1, 'scope': {'work': work}, 'selected': {}}
+        else:
+            raise ValueError('resolve requires an explicit manifest or manual references with work scope')
+        return _resolve(root, value, capability_id, prd_id, manual)
+    target = _manifest_path(root, manifest)
+    old = target.read_bytes() if target.is_file() else None
+    if action == 'init':
+        if not isinstance(work, str) or not work.strip():
+            raise ValueError('init requires the actual work scope')
+        value = _load(old) if old is not None else {'schemaVersion': 1, 'scope': {'work': work}, 'selected': {}}
+        if value['scope']['work'] != work:
+            raise ValueError('existing manifest belongs to a different work scope')
+        return _store(root, target, old, value)
+    if action == 'select':
+        if manual:
+            raise ValueError('manual overrides are read-only resolve inputs')
+        if old is None:
+            raise ValueError('manifest missing; initialize the explicit work first or use manual resolve')
+        value = _load(old)
+        if work is not None and work != value['scope']['work']:
+            raise ValueError('manifest belongs to a different work scope')
+        reference = _reference(root, role, path, capability_id, prd_id)
+        _assign(value['selected'], reference)
+        return _store(root, target, old, value)
+    raise ValueError('handoff operation not implemented in this increment')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action', choices=['init', 'select', 'resolve'])
+    parser.add_argument('--project-root', required=True)
+    parser.add_argument('--manifest')
+    parser.add_argument('--work')
+    parser.add_argument('--role', choices=sorted(GLOBAL_ROLES | TOPIC_ROLES))
+    parser.add_argument('--path')
+    parser.add_argument('--capability-id')
+    parser.add_argument('--prd-id')
+    parser.add_argument('--manual', action='append', default=[], metavar='ROLE=PATH')
+    args = parser.parse_args()
+    try:
+        result = execute(args.project_root, args.manifest, args.action, work=args.work,
+                         role=args.role, path=args.path, capability_id=args.capability_id,
+                         prd_id=args.prd_id, manual=args.manual)
+    except (OSError, ValueError, UnicodeError) as error:
+        print(json.dumps({'ok': False, 'error': str(error)}, ensure_ascii=False))
+        return 1
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/skills/i3-enterprise-sop/references/lifecycle-contract.md

@@ -0,0 +1,91 @@
+# 新增、修改、撤销需求与功能退役合同
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+合同版本：v0.1.1；资源组合：0.6.1。仅为明确企业作业使用的自有资料规则，不是新Skill／命令、JSON程序或工程执行器。资源定位见[入口](readme.md)，引用字段见[交接合同](handoff-contract.md)，文档职责见[共用合同](template-contracts.md)。三份合同共同使用，业务JSON仍schemaVersion1，无新增必填状态字段。
+
+## 1. 先分清意图和事实
+
+| 意图 | 本次规格责任 | 工程责任 |
+| --- | --- | --- |
+| 新增 | 同主题补行为或为独立目标新建prdId；复用相容BRD／公共规范，不按页面拆PBC | 本主题足以交接后增量交原Plan，不重新生成整个工程 |
+| 修改 | 先读现稿、人工修改与真实来源，保留稳定需求／AC，输出完整当前目标和新增／修改／保留／撤销映射 | 核配套、任务、已实现和消费者影响；文字更正不机械全链升版 |
+| 撤销需求 | 明确单项、部分范围或整个主题；保留仍有效内容与撤销依据 | 未实施取消待办，进行中核真实进展，已实现部分需要新的移除／迁移任务 |
+| 功能退役 | 已实现或运行功能的停止／替代目标；假设与真实状态分开 | 新的兼容、移除、数据／任务迁移和回归；删PRD文件不表示代码或生产已退役 |
+
+当前有效目标、任务实际状态、已发生工程事实分别从真实来源回读。selected仅表示明确采用的输入，不证明运行已切换或测试通过；工程及报告沿用原方法，不回写delivery。讨论、status、review／recheck和只读预览零项目写入。
+
+## 2. 各阶段承接及来源
+
+| 产物 | 必须核对的本阶段责任 |
+| --- | --- |
+| BRD | 业务目标／能力边界／跨PBC责任改变才修订；同PBC新增主题可复用已有BRD，不补造认可 |
+| PRD | 固定capabilityId／prdId与仍有效FR／AC；完整当前目标、新旧映射、直接来源；部分撤销不删整个主题 |
+| AD | 对应一份明确主题PRD，保留技术／功能／ER三图及详设；准确公共规范、正式契约、数据owner、消费者、实际骨架及影响／恢复 |
+| TestCase | 同时核产品预期及AD技术判据；新增／变更、撤销后不可用或替代、迁移／失败恢复、保留行为和跨主题回归 |
+
+一能力一目录，主题独立版本、配套不强制同号。允许同路径人工编辑，先读当前正文、旧稿和真实变更依据；不强制SHA、不恢复发行模板，不仅凭路径／版本继承旧认可。没有旧稿或未知业务决定，只限制依赖范围，不编造历史。
+
+公共规范、共享契约、数据与状态有各自权威，必要直接及传递消费者明确；一个主题变化不自动改全部AD或删除共享底座。原型按需、AD可并行，已采用原型核appliesTo及影响，不借SOP改其登记。TestCase是Plan可选输入，验证要求须足够，缺文件可安排设计补齐，不取消企业测试设计交付。
+
+## 3. 选用引用与需求变更
+
+| 时点／对象 | 处理 |
+| --- | --- |
+| 本次生成或修订 | 完成后回读、保存并展示真实路径，按原方法交审；不自动更新JSON |
+| 新主题／新版本 | 文档保留独立版本，明确采用后才登记selected；不自动替换Plan，不预填未来配套 |
+| 明确选择 | 核正文和实际配套，保留选择前清单；不适用的旧配套移出本次选择并报缺口，不假配新PRD |
+| 部分需求撤销 | 由完整新PRD表达撤销编号和保留行为，不删除整个topic；明确选用后再更新引用 |
+| 整个未实施主题撤销 | 核任务与消费者，只处理本主题明确需要撤销的当前选择；其他主题及仍被消费的公共引用保持 |
+| 已实现功能退役 | 选择真实退役目标，不用selected证明生产停用；保留旧运行依据、工程根和真实报告 |
+| 已选路径缺失／移动 | 报具体断引用；新位置实际回读后才更新，缺失不推定撤销，不猜最高版或找history兜底 |
+
+业务JSON不加approved／cancelled／完成率；理由和旧新映射可在项目已有PRD、AD影响表、Plan／唯一tracker或已有决定记录中表达，不强制新变更文件。清单只保存引用，不接管任务状态或生产状态。物理删除需要明确文件操作任务和引用／保留检查，不能顺带删除仍被Plan／报告引用的文件。
+
+本资源不实现登记：S06／S08另建有限辅助并验证。文档成功、登记失败保留文档和旧清单，后续只补引用；只读作业不能补写清单。多个作业无整体事务保证，写前回读并发变化则停覆盖、保留差异；不凭提示词宣称消除竞态。
+
+## 4. 原Plan与任务状态
+
+Plan仍是tasks/plan.md，任务仍为默认tasks/todo.md或项目明确指定唯一tracker。原方法已有“同一工作重规划原位更新；不同工作存在未完计划时停止处理冲突”，不得覆盖／搬走旧计划、批量关闭其他工作或复制竞争待办。
+
+| 实际任务状态 | 增量交接要求 |
+| --- | --- |
+| 已完成 | 原ID、来源、完成状态及证据保留；要移除该功能时新建退役任务，不撤勾或改写成按新版本完成 |
+| 未开始且仍有效 | 保留；只对受影响来源、依赖、范围与验收作获准调整，不无故重建全部ID |
+| 未开始且明确取消 | 退出有效未完集合，保留原ID、取消依据和依赖处理；不勾为完成，不让下一次Build误领 |
+| 进行中／部分实现 | 核真实文件、进展、副作用和未知，停在受影响安全边界，保留人工工作；不自动reset／回滚／删工程 |
+| 其他未完工作 | 原方法停止说明冲突，由用户决定范围，不越权修改 |
+
+默认Markdown取消记录可用同一Plan／todo的独立文字区，不使用待办或完成复选框；具体形态须在S11实际验证Build不会误领。外部tracker按其真实支持及本次授权表达取消／不实施，不能当Done，也不复制本地状态表。恢复同语义需求是新的明确变更，保留恢复关系，不复用旧取消任务当新完成证据。
+
+资料作业只交本次变更意图、准确文档及范围、现有代码／任务事实、受影响／保留需求和AC、共享消费者、验证／恢复与Q。后续明确调用原Plan才修订计划；任务记录实际路径及编号，不只留下可变JSON链接。只改JSON不算任务已取消，资料作业不直接修改Plan／tracker。
+
+## 5. 原Build、工程与退役
+
+Build按获准Plan的具体任务回读实际来源。新候选、selected改变或同路径改稿不自动切设计；下一受影响任务前核计划差量，未调整时不按旧稿实现撤销内容，也不偷偷按新稿施工。无关且已获准任务按依赖及原方法可继续，不全量重置。没有监测／锁能力时不承诺即时中断其他会话；在实际检查点处理，S11验证真实接点。
+
+AD选择真实骨架，Plan安排，获准Build才应用／验证。保留pbc-composite／agent-standalone及frontend／backend／agents／jobs、contracts／shared／tests／delivery职责，既有人工代码、原始生成基线和有效工程锁不整仓覆盖。JSON或AD修改不证明工程已生成／更新；I4／I5实际工程与存量更新另验。
+
+退役按实际适用范围明确：入口和替代／拒绝行为；API／事件及已知提供消费双方、兼容窗口／在途请求；共享数据、保留／迁移和权限；jobs／队列／Agent工具与重试；工程配置／部署／观察；恢复点、补偿和不可逆限制。未知结果先调查，不盲重试迁移或写操作。代码回滚不等于已删数据恢复，撤销需求不授权删库；具体工程／生产动作按真实授权和原风险停点执行。
+
+## 6. 测试、审查和Ship
+
+TestCase为设计，原TDD／适用测试及test负责真实测试代码／运行，原代码review保持自身方法；不把企业只读文档审查套到原review。文档审查只读标注真实问题、位置、来源、影响和最小建议；用户可人工修订、明确委托、有据不采纳或保留Q，不自动改实例或取消任务。
+
+正式撤销／退役后，原正向测试可按真实新目标更新，但保留旧用例／原始报告和变更依据，补停用／拒绝／替代、迁移／恢复及未受影响回归。不能删失败用例、改阈值或降低覆盖制造通过，不以mock关闭必需真实集成。
+
+报告绑定实际runId、输入／配套、代码或制品、环境／依赖、执行主体、原始证据和缺陷；失败、阻断、未运行、未知分别保留。审查报告由获准调用者按原约定另存，不要求在JSON重复登记。Ship GO只说明就绪，实际发布／部署／生产退役许可和回执分别取证。
+
+## 7. 手动方式和任务结束
+
+无JSON时仍可原命令／适用Skill＋明确任务＋真实路径，读取原文和变更依据，不强制建清单、补BRD、安装登记程序或修改项目默认。不增加add／delete／retire操作；未来/i3-sop和显式Skill共用相同阶段规则，using不增路由，跨阶段auto留3.1.0。
+
+本次结束说明真实文档／来源／读写、意图与影响、文档存在／选用／任务／运行事实、Q和未执行范围。原方法的澄清、内容、工具、认可和停轮保留；一次单阶段作业不自动连改下一文档、Plan、代码、生产或发布。资源、严格读取、完整生成、独立审查、实际工程、人审和发布各自取证，规则存在不等于已实现稳定自动化。
+
+B05收口补充：影响结论绑定实际核查范围；对未知消费者、历史数据和恢复条件保留待核，不写成无消费者／无需迁移。回读完成以[共用合同](template-contracts.md)末次编辑后全文要求为准，外层工具仅校验证据，不授予JSON、任务、代码或生产写入。

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

@@ -0,0 +1,73 @@
+# SOP Plan：选定规格交给原规划能力
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+合同版本：v0.2.2。`/i3-sop plan` 与显式 i3-enterprise-sop 的plan动作共用本合同，只做一次明确规划。四阶段文档仍由原Spec生成／修订；plan不生成第五份规格，不调用Build、测试执行、提交或发布。普通标准 `/i3-plan` 保持原入口，不强制读取本资料或handoff。
+
+**统一读取准备：**JSON与手动路径共用同一准备环节；手动只免JSON解析，不免共用规则。先从项目实际采用记录确定所选资料根；没有选定副本时，从本次实际加载的SOP Skill目录下references/进入。CodeBuddy以 `.codebuddy/.i3-composer-agent.json` 的name／version／scope、catalog.skills及当前Skill精确assets核身份，不用resources.references推导SOP根。原 `/i3-plan` 命令可用 `.codebuddy/commands/*plan*` 定位；无项目安装才查同宿主真实全局登记，不读其他宿主副本。
+
+**首批必读：**完整Read原 `/i3-plan` 命令正文，以及所选根readme.md、stages.json、template-contracts.md、handoff-contract.md、本plan-handoff.md。索引planHandoff.requiredResourceReads是共用文件名的同一清单，调用者和外层验证据此固定实际路径；不能只读最后一份，不用用户补内部路径。必要正文仍由模型实际读取，脚本解析索引不能冒充读取回执。项目自改资料优先，未确认完整覆盖时仍读其选定原件，不回退发行副本。
+
+资料和目录定位用Read／Glob／Grep，不调用ls／find／mkdir等shell探测或试验权限。解析辅助仅在本次真实工具许可范围内使用，不将工具名可见视作任意命令获准；失败尝试保留且准确报告。此处约束SOP准备环节，不改原规划方法或增加权限。
+
+**进入原规划前的检查点：**共用文件及原命令全文已读→准确业务／技术输入已读且身份／直接上游无冲突→实际加载原规划Skill成功→允许原plan／todo写入。缺读／部分读／失败先补齐，未齐停止；身份或上游冲突按§2.1先停，不因打算写待审稿绕过。原Skill已加载、命令名称或自述合规均不代替其他条件。最终列出实际共用读取、原命令路径及真实失败。此检查点统一既有要求，不新增用户必填参数、通用拦截器或业务JSON字段。
+
+## 1. 对象明确后再规划
+
+只读核当前项目与已采用规则、输入选择、真实资料和现有任务目标。用户可只输入 `/i3-sop plan`，或加一句主题；唯一材料与有效选择足够时直接承接，不要求再写长提示词或内部路径。多清单／多主题、动作正文矛盾、关键缺口或不同工作的未完计划，先说明实际选项、原因和建议并等待。无答复或取消零写入，不能按最大版本、目录顺序或模型推荐代选。
+
+先区分清单路径交接和手动方式。显式给清单、项目实际采用记录或当前唯一且适用的清单均须真实读取；清单存在本身不改变标准流程或证明业务认可。损坏、不可读或未知格式先报告，不静默换源或退回手动掩盖。没有清单时可请用户明确实际AD及其配套或选择已有手动材料，不强制创建JSON、补BRD或重走前序。范围选择仅为本次会话，不写入永久偏好。
+
+资源按本次明确材料→项目已采用自改副本→同宿主项目安装→同宿主可读全局定位。已选项目源失效就报告，不探读低优先级根来替代；不能确认自改合同已覆盖时完整读项目选定原件，不恢复发行副本。当前项目实际采用的CONSTRAINTS／ADR／技术规则照常有效。
+
+## 2. 只读解析并实际读原文
+
+先完成首批必读，再区分JSON解析和手动路径读取。两种方式均读所选根README、本索引stages.json、template-contracts.md、handoff-contract.md和本合同；生命周期或恢复有实质影响时读其适用约定。plan不加载BRD／PRD／AD／TestCase模板及其生成／审查提示词。项目规则及真实业务／技术依据必须实际回读。
+
+复用[handoff.py](handoff.py)的 `resolve`，先核实际 `--help`；相对路径以明确的业务项目根解析，不以清单目录解析。以capabilityId＋prdId识别本主题，明确组合逐主题解析；不以单个AD或JSON代替完整规格。工具返回路径不证明模型已读、配套正确或获得批准。
+
+清单顶层仍仅schemaVersion、scope、selected。读取selected.technicalBaseline和本主题prd／ad／contracts／engineeringSkeleton及适用testCase／prototype；BRD按追溯需要读。不调用init／select／改选，不写JSON、审批、delivery、candidates、activeTopic或任务状态。
+
+Python不可用时直接按用户明确的手动路径及准确引用读取，不安装环境或改JSON。手动输入可临时覆盖相同角色，但须说明与既有选择的差异，不持久化selected。现有resolve不做语义验证；身份、文件与正文版本、直接上游、共享权威与消费者影响由本次实际材料核对。
+
+| 必要输入 | 如何核对 |
+| --- | --- |
+| 当前主题PRD＋配套AD | 完整读取本次有效正文，核能力／主题、独立版本、AD直接上游和需求／AC；不猜高版本、不读另一主题替代 |
+| 已采用技术规约与质量边界 | 真实文档或适用CONSTRAINTS／ADR；不是空模板。若已由AD／项目规则完整承载，不强制另建总规约 |
+| 必要共享契约 | 当前接口、事件、数据责任、兼容／迁移和实际权威；跨主题只读所依赖定义，不全量加载所有AD或历史 |
+| 工程采用／骨架来源 | 准确采用说明、来源版本、目录／模块责任和已有结构映射；规范不冒充可运行工程；初始化、调整或迁移按实际缺口排任务 |
+| 相关代码及工程事实 | 实际完整读取相关源码及本项目依赖／构建配置，按真实技术栈定位，例如Node项目package.json；不能以AD／规范里的命令代替读取现有配置。核真实测试命令及示例，区分拟建与已有，不虚构已构建成功 |
+| TestCase／原型 | 已形成且适用就核准确配套和范围。没有独立TestCase不统一阻断Plan，测试策略从AD／实际规范承接并排必要补齐；原型按需，无界面不强制补画 |
+| 当前Plan／唯一任务目标 | 实际读取；不同工作未完先问，不覆盖或静默另起权威；同工作修订保留人工内容及已完成事实 |
+
+逐项定位原SPEC六项：目标、完整可执行命令、项目结构、代码风格及示例、测试策略、Always／Ask first／Never工程边界。关键缺口先说明依赖影响；只有§2.1身份与直接上游已核一致后，非阻断缺口才可在明确范围内规划独立部分，不能用此条跨过身份停点或杜撰技术决定。长文按段覆盖并记录范围，摘要只导航，不以省上下文省略必要业务依据，不承诺固定耗时。
+
+### 2.1 身份或直接上游冲突先停
+
+对照本次准确PRD、AD正文的能力／主题标识、AD声明的直接上游路径与PRD版本，以及适用清单／手动选择。已声明内容互相矛盾时先报告冲突，不加载原规划、不创建或修改plan／todo，也不另存候选计划。即使AD正文功能一致、模型判断头部疑似笔误，身份仍不能由模型自行裁定；只给原文证据、影响、建议和可选操作，等待人工处理后重新核对，不修业务稿或JSON。选择了某个文件路径不等于确认了文件内部矛盾。
+
+PRD与AD各自独立版本不必相同，例如PRD v0.0.1与AD v0.0.3明确引用该PRD v0.0.1是允许的；AD改引另一主题、错误路径或不同PRD版本则须先停。缺独立TestCase／原型仍按需处理，不扩大为统一规划前置。无冲突后的非阻断Q保留人工空间，不要求问题清零。
+
+## 3. 实际复用原Plan
+
+依据本宿主真实安装清单／命令目录定位原 `/i3-plan`（TOML宿主可能登记为planning），实际读当前命令义务；不要复制一份删减规则或写死开发工作区路径。加载原 [i3-planning-and-task-breakdown Skill](../../i3-planning-and-task-breakdown/SKILL.md)并取得本宿主正式机制的成功回执，再执行原方法。资源版本与安装位置须以实际文件核对。
+
+有正式命令转交能力时记录真实转交；只有Skill工具时实际加载该Skill并履行原命令义务。两者如实区分，不能把Skill加载称为执行另一个slash命令。调用拒绝／失败或没有正式机制时停止，不裸跑生成计划；当前主会话阅读本说明不构成原规划已调用证据。
+
+把上述实际引用、本次目标和必要澄清组织为内部规划任务，直接交原规划方法，不要求用户再复制提示词。原Plan负责只读理解、依赖图、纵向切片、AC／验证步骤、检查点和风险；本合同不重写其算法。计划文件的保存仍按原规则允许，不把“只读理解”误作不能写规划产物。
+
+## 4. 原产物与停点
+
+保持原默认 `tasks/plan.md` 与 `tasks/todo.md`，或项目已有明确且原规则允许的外部唯一任务目标。不得改原命令、另建SOP任务格式或覆盖不同工作的未完计划。计划内保留实际来源路径、正文版本、主题、FR／AC、必要共享依赖和验证依据；不能只留下一个可变JSON链接。
+
+来源表列本次实际使用的PRD、AD、技术规范、共享契约、工程采用说明的完整项目相对路径和文档版本；明确项目外来源才用绝对路径。AD_v…、契约简称或JSON位置不代替准确来源。最终回读时逐项对照实际读取集合，缺引用先补齐原Plan再全文回读交审，不能只在会话报告补路径；不据此改写输入业务稿。
+
+本动作只允许原规划产物，不改业务稿、JSON、采用记录、工程配置或代码。最后写入后完整回读实际plan与唯一任务目标，核覆盖和差量；来源在执行中变化须报告，不把旧任务套新设计。展示实际路径、未决项和范围，交人工审阅并停轮，不代批或自动Build。
+
+使用者另行批准后调用原 `/i3-build` 或 `/i3-build auto`。有效规格路径、Git基线、完整计划明确认可、逐任务测试／构建／提交和风险停点均保留。未提交JSON、项目指引等仍可能触发原Git停点，不自动ignore、不擅自提交来规避；非默认位置与auto有冲突时如实说明。企业跨阶段auto属于3.1.0，不能由plan暗中启动。

package/skills/i3-enterprise-sop/references/prd/assets-manifest.json

@@ -0,0 +1,109 @@
+{
+  "schemaVersion": 1,
+  "resourceId": "i3-enterprise-sop-prd",
+  "resourceVersion": "0.3.3",
+  "status": "local-resources-only-not-released",
+  "source": {
+    "path": "skills/i3-enterprise-sop/references/prd/templates/prd.md",
+    "templateVersion": "v0.0.4",
+    "sha256": "1c728d4865ae1ad3936a735d3543c21f4a06fd195f7f94c5ac721d560ca10aee",
+    "resourcePath": "templates/prd.md",
+    "distributionRendering": "Existing branding pipeline adds one standard i3:zh-guide block; remaining template bytes preserved."
+  },
+  "designEvidence": {
+    "path": "artifacts/verification/i1-full-handoff-20261017/REPORT.md",
+    "scope": "historical direct-Skill PRD verification; not included; PRD command needs separate evidence",
+    "sha256": "853be438ef3f41a0a0b2be9f0f307a2f947f3655939acb346b440feb996f3304",
+    "included": false
+  },
+  "prompts": {
+    "generate": "prompts/01-generate.md",
+    "review": "prompts/02-review.md",
+    "revise": "prompts/03-revise.md",
+    "recheck": "prompts/04-recheck.md"
+  },
+  "files": [
+    {
+      "path": "readme.md",
+      "sourceSha256": "60603eaa38487fa2eb6ead60378ba4f832830c2dafc4fee612dac3a0679a05e3",
+      "sha256": "c9667e22973d6c7b2a5e14d8fa6311fd99192a46404339e9cab5d044fc6038da",
+      "role": "project-owned-guidance"
+    },
+    {
+      "path": "prompts/01-generate.md",
+      "sourceSha256": "93ebe9f47214915f1043ca602c378b10a7f08be02462b5eb516032f4ed884a35",
+      "sha256": "5911edae8792a9a7e939f579de95ef237b577252e5bfae9a3ee5ebee7533da3a",
+      "role": "project-owned-guidance"
+    },
+    {
+      "path": "prompts/02-review.md",
+      "sourceSha256": "83b03378d7dec4a18217571e777b715a8aba02443ac453f3a5e118f114882f09",
+      "sha256": "03278975fb19b69d9023ec834c450322582d92672422f4b04e555cac8472b07e",
+      "role": "project-owned-guidance"
+    },
+    {
+      "path": "prompts/03-revise.md",
+      "sourceSha256": "f8dff8e817dad56552fd30e46d187c8515546b2f9c6e43a49c471f100711f6e5",
+      "sha256": "b2a1cf49d651e655fa28e81e5ce7771731d6a3f7c9ddd64a0c8e33b8c359732e",
+      "role": "project-owned-guidance"
+    },
+    {
+      "path": "prompts/04-recheck.md",
+      "sourceSha256": "33f6d6f20b2c08daaf6ec833fd775c3ad73fa70803c7e386f8f27395e46521ae",
+      "sha256": "bb457ebaadf55edd0aa913c4228b66786d2727c1b91d81abd4e8c3a2e5e22638",
+      "role": "project-owned-guidance"
+    },
+    {
+      "path": "template-contracts.md",
+      "sourceSha256": "2f822f9143284579977fe69dff1ce2d2854bb5107e737765ea3c27093d801a63",
+      "sha256": "30b64ac1b7f37b79ac6c1249d8e01cca53a5bd29b7442791a2a0af5cf917dca9",
+      "role": "project-owned-guidance"
+    },
+    {
+      "path": "templates/ad.md",
+      "sourceSha256": "f729203478a7bfb42451b053b8f4c7a0b1ce81ac666690e83176c5b02679b28e",
+      "sha256": "4cb36de42a3a27004f7dcc8f5669a6823307f0fe9e6e731d668373cb91a06d1a",
+      "role": "handoff-note-not-template"
+    },
+    {
+      "path": "templates/prd.md",
+      "sourceSha256": "1c728d4865ae1ad3936a735d3543c21f4a06fd195f7f94c5ac721d560ca10aee",
+      "sha256": "22f7b09d1b9914975d602e24f39ce7e63d945493f55a4654b6484a8569b73a8a",
+      "role": "exact-source-template-branded-guide-only"
+    }
+  ],
+  "designSources": [
+    {
+      "path": "docs/sop-design/template-contracts.md",
+      "sha256": "b8aca73f3e8f70fc3b62df1aefdb8fb89097f7b896197e8d036948639e5e2609",
+      "included": false,
+      "role": "maintenance provenance only; not a readable bundled dependency",
+      "documentVersion": "v0.0.2",
+      "versionEvidence": "document header"
+    }
+  ],
+  "projectDiscovery": {
+    "entryRelativeToReferences": "readme.md",
+    "codebuddyFragmentRelativeToReferences": "codebuddy-project-guide.md",
+    "activation": "explicit-enterprise-task-or-applicable-recorded-selection",
+    "ordinaryInstallEnablesEnterpriseWorkflow": false,
+    "resourceRoot": "actual-loaded-sop-skill/references"
+  },
+  "dependencies": [
+    {
+      "path": "../template-contracts.md",
+      "role": "shared-contract",
+      "resolutionBoundary": "selected-enterprise-sop-root"
+    },
+    {
+      "path": "../handoff-contract.md",
+      "role": "shared-handoff-contract",
+      "resolutionBoundary": "selected-enterprise-sop-root"
+    },
+    {
+      "path": "../lifecycle-contract.md",
+      "role": "shared-lifecycle-contract",
+      "resolutionBoundary": "selected-enterprise-sop-root"
+    }
+  ]
+}

package/skills/i3-enterprise-sop/references/prd/prompts/01-generate.md

@@ -0,0 +1,64 @@
+# PRD 生成任务
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+原方法调用：本次起草必须先成功加载原 `i3-spec-driven-development` Skill；宿主支持Skill工具时取得成功回执，再按其外部格式／存储能力使用本模板和唯一目标。不是调用原/i3-spec包装后改写其根SPEC.md规则，也不让using把Spec变成可选。方法不可用或真实冲突时报告，不裸跑写稿；内容、认可、保存后停轮保留。
+
+目录与上下文：新项目无已采用输出约定时默认 `spec/{能力名称}/`，同PBC多主题PRD独立版本，AD／TestCase固定本次直接上游；已有位置不自动迁移。只读本主题完整来源及必要共享依赖，不全量载入候选／历史，摘要不替代正文。最后回读后原方法要求立即停轮时，报告候选实际路径和待登记事项，后续获准作业补JSON，不自动调用Plan／Build。
+
+
+此提示词是提供给现有 `i3-spec-driven-development` 的企业任务说明。它不新增技能、命令或自动调度。通过已启用项目指引定位到本文件后，模型从实际读取的项目采用记录、选定清单及业务材料补齐任务卡；用户不必逐项填写路径。仅在材料缺失、存在歧义、真实冲突或覆盖风险时澄清，不猜路径或业务答案。未明确选择企业 SOP 时不应用本提示词。
+
+## 本次任务卡（模型据已读材料整理，缺口向调用者澄清）
+
+- 任务：只起草一个 PBC 的一个 PRD 主题。
+- EBC / PBC：`{capabilityId、名称、边界的实际确认状态}`。
+- PRD：`{稳定 prdId、需求主题、独立业务版本}`。
+- 唯一输出：`{项目内完整目标路径}`。
+- 输出约定依据：`{实际已读的项目根README或其明确引用条目，目录及文件名约定；无约定则说明拟建，不伪称已有}`。
+- 文件名占位符对照：`{按项目实际命名式逐项列：PBC名称、capabilityId、主题名称、prdId、业务版本；区分名称与标识，写明本式实际采用哪些字段及来源}`。
+- 资源指南：`{本次采用的 readme.md 路径}`。
+- PRD 模板：`{本次采用的 templates/PRD.md 路径、模板版本及采用记录}`。
+- 固定业务输入：`{BRD及必要的业务答复、规则、历史文档；每项路径/固定版本/条目；标明有效目标、上下文或仅比较}`。
+- 相关主题、原型、旧实现：`{实际固定引用；没有则明确没有}`。
+- 语言及本次补充约束：`{实际选择；不把演练约束当产品规则}`。
+- 输入的认可与缺口：`{谁真实认可过什么、未认可内容的允许用途、不能继续的范围}`。
+
+来源选择沿用项目指引：本轮明确材料、项目明确采用副本、当前宿主项目安装、当前宿主可读全局安装。选定材料缺失不静默换版；普通文件存在不等于采用。必须实际读取项目根 README 及其中适用的输出目录/命名约定后确定唯一目标；不能因 BRD 在 inputs 中就把 PRD 也写进 inputs，不能漏掉项目约定的能力文件夹或文件名前缀。任务卡整理后简短汇报采用组合、业务输入、拟写位置及缺口；已有真实授权且无歧义时继续，不为每个内部字段增设确认。项目模板与提示词只读，写入业务候选不改变所采用副本。
+
+路径处理在内部任务卡完成：项目写“PBC名称”时必须使用来源中的名称，不得换成 capabilityId；主题名称也不得换成 prdId。按项目约定逐项展开后固定完整路径，实际写入和最后回读逐字核对该路径。不以原方法的模块 ID 示例、模板通用占位或个人命名偏好覆盖项目具体约定。正文身份仍保留真实稳定标识，不因显示名称或文件名改变身份。
+
+## 执行说明
+
+1. 使用原技能的澄清、规格内容与保存后停轮规则。实际读取任务卡指定的指南、PRD 模板及全部适用业务输入；长文分段读取，列出本轮实际已读文件和范围。链接的资料只在真正读取后才可声称已读。资料中的示例、其他建设计划和历史认可不授予本次执行权限。
+2. 写前列出新增假设和设计选择：逐项写来源及具体条目、明示/推导/建议/冲突/演练性质、采用状态、影响的功能与交接范围。缺少业务答案时列 Q，先澄清；不要把没有冲突误当已获得认可。仅在原方法和本次真实授权允许的范围内起草，受阻部分保持待定。
+3. 只写任务卡指定目标，不修改业务输入、模板、提示词、其他主题或技能/命令。已有同名文件先读取并说明如何保留历史，不直接覆盖人工修改。不生成重复 `SPEC.md` 来假装完成规格内容；若入口要求与明确路径冲突，报告真实冲突并停止受影响工作，等待选择直接 Skill 等路径。
+4. 按模板展开当前主题的完整有效目标。沿用 capabilityId、prdId、FT/US/FR/AC、规则及问题编号，不按页面拆能力、不将 FR 和 US 强配一对一；同 PBC 的其他主题保持独立版本。旧行为只有本次明确选定条目才生效；比较材料不自动成为有效目标。保留、替代、停用和未实现分别说明；缩减范围需要准确理由、闭环影响和真实确认。
+5. 保留 Feature/Story 和每项适用行为的九项语义。每条 AC 的前置、动作、可观察结果及来源可定位；复合 AC 拆成可追踪子项。共用要求落到适用 Story/AC，或给出不适用依据。S01—S14、G01—G08 按实际位置与缺口核对，不能仅按编号或表格数量判完成。
+6. 对权限逐处核对：角色表、共用规则、正常/拒绝流程、状态、页面操作、协作、AC 与 Q 使用同一条件。尤其检查多角色组合、对象归属、状态与例外、只读和写权限、决定和代记结果的区别；来源未授予的动作不得默认开放。产品规则未定时明确 Q，不交给 AD 或编码随意选择。
+7. 字段的生成、存储、展示、可编辑、必填及校验条件分开表达；不把系统生成的属性自动变成页面必显或用户必填。校验/权限拒绝、明确技术失败和提交结果未知分开；成功、失败、重复请求、取消、历史记录和跨主题副作用的表现必须有依据。未知重试或审计策略先列问题，不自行承诺。
+8. 最终稿每条新增规范性要求逐条回查来源，检查原意、条件、例外和要求强度；推导或建议保持标记。全文表格逐行核对表头列数及列义，防止内容落入相邻列；不可用总行数、关键词命中或自称检查代替实际核对。
+9. 最后一次写入/修改后实际回读最终目标，复核来源、权限、AC、表格与受影响引用；后续若再修改，须在最后一次修改后重新分段完整回读最终目标，不能只回读局部。声明哪些核查实际执行、哪些未验证，不把本轮补读追认成过去已读。
+10. 汇报目标路径、文档身份/版本、实际输入和采用情况、自查结果、Q 及具体受阻范围。请求人工审阅并结束当前轮。不得自动进入原型、AD、TestCase、Plan、Build 或发布；本份 PRD 不等于原 SPEC 六项齐备、业务认可或开发准入。
+
+## B05 生命周期与必要读取
+
+按选定资源索引实际读lifecycleContract及共用模板／交接合同；先列本次必读路径和用途，实际核所选正文及必要依赖，未读／失败／部分读照实。只加载本次generate动作，不加载其他动作或低优先级源兜底。
+
+保持主题、FR／AC身份和完整当前目标；明确新增／修改／保留／撤销及真实来源，部分撤销不删整个主题，已实现事实不因目标撤销消失。
+
+只写本次明确文档目标，先读现稿与人工修改并保留历史；最后编辑后实际回读。JSON、Plan、任务、代码和生产不是本次写入范围；生成文档后展示路径并交审，不自动登记JSON；用户明确选用后才登记selected，原方法停轮仍保持。
+
+当前目标、任务与已实现事实分开；已完成任务保留，未实施取消不记完成，进行中保留真实工作，已实现退役通过新任务。原Plan／Build实际消费须按本轮证据核验，JSON最小辅助已提供但不在本次文稿写入权限内，不自动下阶段、工程、提交或发布。
+
+## B05-r2 最后修改后的全文回读
+
+全部Write／Edit结束后，必须使用读取工具分段完整覆盖最终目标正文，超出工具截断就续读剩余段。已全文读过但之后又Edit时，须再次完整覆盖最终稿，不能只回读改动行并声称“末次修改后全文已核”。本次必要输入清单中仍有未读／失败／部分读时，先报告准确缺口，不写成已全部读取；补读不是过去已读。
+
+未完成收尾就保留实际稿和未核范围，不删除稿件、不补造通过，不登记为已完成回读的完整候选。收尾不改写业务决定，不自动进入下一阶段；只读review／recheck依然零项目写入。