@givolt/i3-composer-agent 3.2.1 → 4.0.0

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

@@ -12,11 +12,11 @@ from pathlib import Path
 import tempfile
 import uuid
 
-VERSION = '0.4.0'
+VERSION = '0.5.0'
 GLOBAL_ROLES = {'brd'}
-TOPIC_ROLES = {'prd', 'ad', 'testCase'}
-DOCUMENT_ROLES = GLOBAL_ROLES | TOPIC_ROLES
-TOPIC_IDENTITY = ('pbcId', 'pbcName', 'prdId')
+PBC_ROLES = {'prd', 'ad', 'testCase'}
+DOCUMENT_ROLES = GLOBAL_ROLES | PBC_ROLES
+PBC_IDENTITY = ('pbcId', 'pbcName')
 
 
 def _unique(pairs):
@@ -49,41 +49,40 @@ def _only_fields(value, allowed, label):
 
 def _validate(value):
     if not isinstance(value, dict) or type(value.get('schemaVersion')) is not int:
-        raise ValueError('unsupported handoff schemaVersion; expected integer 2')
-    if value['schemaVersion'] == 1:
-        raise ValueError('legacy handoff schemaVersion 1; preserve the original, verify EBC/PBC identities '
-                         'and document references before an explicitly requested update; no automatic migration')
-    if value['schemaVersion'] != 2:
-        raise ValueError('unsupported handoff schemaVersion; expected 2; no automatic migration')
+        raise ValueError('unsupported handoff schemaVersion; expected integer 3')
+    if value['schemaVersion'] in (1, 2):
+        raise ValueError('legacy handoff schemaVersion; preserve the original and review each PBC document set; '
+                         'no automatic migration or merging of partial PRDs')
+    if value['schemaVersion'] != 3:
+        raise ValueError('unsupported handoff schemaVersion; expected 3; no automatic migration')
     _only_fields(value, {'schemaVersion', 'scope', 'selected'}, 'handoff')
     scope = value.get('scope')
     _only_fields(scope, {'ebcId', 'ebcName'}, 'scope')
     for key in ('ebcId', 'ebcName'):
         _required_text(scope.get(key), 'scope.' + key)
     selected = value.get('selected')
-    _only_fields(selected, GLOBAL_ROLES | {'topics'}, 'selected')
+    _only_fields(selected, GLOBAL_ROLES | {'pbcs'}, 'selected')
     for role in GLOBAL_ROLES & set(selected):
         _required_text(selected[role], 'selected.' + role)
-    topics = selected.get('topics')
-    if not isinstance(topics, list):
-        raise ValueError('selected.topics must be an array')
-    seen = set()
-    names = {}
-    for topic in topics:
-        _only_fields(topic, set(TOPIC_IDENTITY) | TOPIC_ROLES, 'topic')
-        for key in TOPIC_IDENTITY:
-            _required_text(topic.get(key), 'topic.' + key)
-        identity = (topic['pbcId'], topic['prdId'])
-        if identity in seen:
-            raise ValueError('ambiguous duplicate topic selection')
-        seen.add(identity)
-        if names.setdefault(topic['pbcId'], topic['pbcName']) != topic['pbcName']:
-            raise ValueError('conflicting pbcName for pbcId: ' + topic['pbcId'])
-        roles = TOPIC_ROLES & set(topic)
+    pbcs = selected.get('pbcs')
+    if not isinstance(pbcs, list):
+        raise ValueError('selected.pbcs must be an array')
+    identities, names = set(), set()
+    for pbc in pbcs:
+        _only_fields(pbc, set(PBC_IDENTITY) | PBC_ROLES, 'pbc')
+        for key in PBC_IDENTITY:
+            _required_text(pbc.get(key), 'pbc.' + key)
+        if pbc['pbcId'] in identities:
+            raise ValueError('duplicate pbcId; one current document set per PBC')
+        if pbc['pbcName'] in names:
+            raise ValueError('different PBC identities cannot share a name and default directory')
+        identities.add(pbc['pbcId'])
+        names.add(pbc['pbcName'])
+        roles = PBC_ROLES & set(pbc)
         if not roles:
-            raise ValueError('topic must contain at least one selected PRD, AD or TestCase path')
+            raise ValueError('PBC must contain at least one selected PRD, AD or TestCase path')
         for role in roles:
-            _required_text(topic[role], 'topic.' + role)
+            _required_text(pbc[role], 'pbc.' + role)
     return value
 
 
@@ -92,7 +91,7 @@ def _load(raw):
 
 
 def _selected_only(value):
-    """Validate the complete v2 record before any canonical write; never discard fields."""
+    """Validate the complete v3 record before writing; never discard unknown fields."""
     _validate(value)
     return {key: copy.deepcopy(value[key]) for key in ('schemaVersion', 'scope', 'selected')}
 
@@ -104,18 +103,18 @@ def _check_scope(value, ebc_id, ebc_name):
         raise ValueError('ebcName conflicts with the selected EBC; verify the document identity before updating')
 
 
-def _topic_name(selected, pbc_id, prd_id, pbc_name):
+def _pbc_name(selected, pbc_id, pbc_name):
     _required_text(pbc_id, 'pbcId')
-    _required_text(prd_id, 'prdId')
-    topics = selected['topics']
-    matches = [x for x in topics if x['pbcId'] == pbc_id and x['prdId'] == prd_id]
+    matches = [x for x in selected['pbcs'] if x['pbcId'] == pbc_id]
     if pbc_name is None:
         if not matches:
-            raise ValueError('new topic requires an explicit pbcName')
-        pbc_name = matches[0]['pbcName']
+            raise ValueError('a new PBC requires an explicit pbcName')
+        return matches[0]['pbcName']
     _required_text(pbc_name, 'pbcName')
-    if any(x['pbcId'] == pbc_id and x['pbcName'] != pbc_name for x in topics):
+    if matches and matches[0]['pbcName'] != pbc_name:
         raise ValueError('pbcName conflicts with the selected PBC; verify the document identity before updating')
+    if any(x['pbcId'] != pbc_id and x['pbcName'] == pbc_name for x in selected['pbcs']):
+        raise ValueError('pbcName already belongs to a different PBC; default paths would collide')
     return pbc_name
 
 
@@ -136,11 +135,10 @@ def _manifest_path(root, raw):
     return path
 
 
-def _reference(root, role, raw, pbc_id=None, prd_id=None, pbc_name=None):
+def _reference(root, role, raw, pbc_id=None, pbc_name=None):
     if role not in DOCUMENT_ROLES:
         raise ValueError('unknown reference role')
-    if not isinstance(raw, str) or not raw.strip():
-        raise ValueError('reference path must be explicit')
+    _required_text(raw, 'reference path')
     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):
@@ -151,26 +149,22 @@ def _reference(root, role, raw, pbc_id=None, prd_id=None, pbc_name=None):
         raise ValueError('empty document is not a complete handoff reference')
     result = {'role': role,
               'path': resolved.relative_to(root).as_posix() if resolved.is_relative_to(root) else str(resolved)}
-    if role in TOPIC_ROLES:
-        for key, item in [('pbcId', pbc_id), ('pbcName', pbc_name), ('prdId', prd_id)]:
-            result[key] = _required_text(item, key)
+    if role in PBC_ROLES:
+        result.update(pbcId=_required_text(pbc_id, 'pbcId'), pbcName=_required_text(pbc_name, 'pbcName'))
     return result
 
 
 def _assign(selected, reference, *, transient=False, replace_document=False):
     role, path = reference['role'], reference['path']
     target = selected
-    if role in TOPIC_ROLES:
-        topics = selected['topics']
-        _topic_name(selected, reference['pbcId'], reference['prdId'], reference['pbcName'])
-        matches = [x for x in topics if x['pbcId'] == reference['pbcId'] and x['prdId'] == reference['prdId']]
-        if len(matches) > 1:
-            raise ValueError('ambiguous duplicate topic selection')
+    if role in PBC_ROLES:
+        _pbc_name(selected, reference['pbcId'], reference['pbcName'])
+        matches = [x for x in selected['pbcs'] if x['pbcId'] == reference['pbcId']]
         if matches:
             target = matches[0]
         else:
-            target = {k: reference[k] for k in TOPIC_IDENTITY}
-            topics.append(target)
+            target = {k: reference[k] for k in PBC_IDENTITY}
+            selected['pbcs'].append(target)
     previous_path = target.get(role)
     if not transient and previous_path is not None and previous_path != path and not replace_document:
         raise ValueError('updating a selected document requires --ebc-id matching scope.ebcId')
@@ -178,42 +172,30 @@ def _assign(selected, reference, *, transient=False, replace_document=False):
     return previous_path
 
 
-def _resolve(root, value, pbc_id, prd_id, pbc_name, manual):
+def _resolve(root, value, pbc_id, pbc_name, manual):
     selected = copy.deepcopy(value['selected'])
-    topics = selected['topics']
-    if (pbc_id is None) != (prd_id is None):
-        raise ValueError('provide both pbcId and prdId')
-    if pbc_id is not None:
-        _required_text(pbc_id, 'pbcId')
-        _required_text(prd_id, 'prdId')
-    elif len(topics) == 1:
-        pbc_id, prd_id = topics[0]['pbcId'], topics[0]['prdId']
+    if pbc_id is None and len(selected['pbcs']) == 1:
+        pbc_id = selected['pbcs'][0]['pbcId']
     if pbc_name is not None:
-        _topic_name(selected, pbc_id, prd_id, pbc_name)
+        _pbc_name(selected, pbc_id, pbc_name)
     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)
-        name = _topic_name(selected, pbc_id, prd_id, pbc_name) if role in TOPIC_ROLES else None
-        reference = _reference(root, role, path, pbc_id, prd_id, name)
-        _assign(selected, reference, transient=True)
-    topics = selected['topics']
-    if pbc_id is None and len(topics) > 1:
-        raise ValueError('multiple topics; explicitly choose pbcId 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['pbcId'] == pbc_id and x['prdId'] == prd_id]
+        name = _pbc_name(selected, pbc_id, pbc_name) if role in PBC_ROLES else None
+        _assign(selected, _reference(root, role, path, pbc_id, name), transient=True)
+    if pbc_id is None and len(selected['pbcs']) > 1:
+        raise ValueError('multiple PBCs; explicitly choose pbcId')
+    references = [_reference(root, role, selected[role]) for role in sorted(GLOBAL_ROLES) if role in selected]
+    matches = [x for x in selected['pbcs'] if x['pbcId'] == pbc_id]
     if pbc_id is not None 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
-            references.append(_reference(root, role, topic[role], pbc_id, prd_id, topic['pbcName']))
+        raise ValueError('requested PBC is not selected; no highest-version fallback')
+    for pbc in matches:
+        for role in sorted(PBC_ROLES):
+            if role in pbc:
+                references.append(_reference(root, role, pbc[role], pbc_id, pbc['pbcName']))
     for reference in references:
         path = Path(reference['path'])
         reference['resolvedPath'] = str(path if path.is_absolute() else root / path)
@@ -222,7 +204,56 @@ def _resolve(root, value, pbc_id, prd_id, pbc_name, manual):
               'proof': 'document paths read now; caller must verify document identities, versions, upstream '
                        'and adopted attachments against the declared EBC/PBC scope and actual human decisions'}
     if matches:
-        result['topic'] = {key: matches[0][key] for key in TOPIC_IDENTITY}
+        result['pbc'] = {key: matches[0][key] for key in PBC_IDENTITY}
+    return result
+
+
+def _component(value, label):
+    _required_text(value, label)
+    if value != value.strip() or value in {'.', '..'} or any(c in value for c in '/\\<>:"|?*') or any(ord(c) < 32 for c in value):
+        raise ValueError(label + ' is not a safe name for a new path; ask for the intended name, do not rename silently')
+    return value
+
+
+def _prepare(root, value, role, pbc_id, pbc_name, path, version):
+    if role not in DOCUMENT_ROLES | {'spec'}:
+        raise ValueError('prepare requires a document role or spec')
+    selected = value['selected']
+    target = selected
+    if role == 'brd' and (pbc_id is not None or pbc_name is not None):
+        raise ValueError('BRD belongs to the EBC, not a PBC')
+    if role != 'brd':
+        if pbc_id is None and len(selected['pbcs']) == 1:
+            pbc_id = selected['pbcs'][0]['pbcId']
+        pbc_name = _pbc_name(selected, pbc_id, pbc_name)
+        target = next((x for x in selected['pbcs'] if x['pbcId'] == pbc_id), {})
+    chosen = path or target.get(role)
+    source = 'explicit' if path else 'selected' if chosen else 'default'
+    if not chosen:
+        name = _component(value['scope']['ebcName'] if role == 'brd' else pbc_name, 'ebcName' if role == 'brd' else 'pbcName')
+        if role == 'spec':
+            chosen = 'spec/SPEC-' + name + '.md'
+        else:
+            tag = _component(_required_text(version, 'business version').removeprefix('v'), 'business version')
+            suffix = {'brd': 'BRD', 'prd': 'PRD', 'ad': 'AD', 'testCase': 'TestCase'}[role]
+            filename = name + '-' + suffix + '_v' + tag + '.md'
+            chosen = 'spec/' + ('' if role == 'brd' else name + '/') + filename
+    raw = Path(chosen)
+    actual = raw if raw.is_absolute() else root / raw
+    if actual.exists():
+        if not actual.is_file() or not actual.read_text(encoding='utf-8').strip():
+            raise ValueError('target is not a readable nonempty document; inspect before writing')
+        if not raw.is_absolute() and not actual.resolve().is_relative_to(root):
+            raise ValueError('relative target escapes project root')
+    else:
+        _manifest_path(root, chosen)
+    resolved = actual.resolve()
+    result = {'ok': True, 'changed': False, 'scope': copy.deepcopy(value['scope']), 'role': role,
+              'source': source, 'path': resolved.relative_to(root).as_posix() if resolved.is_relative_to(root) else str(resolved),
+              'resolvedPath': str(resolved), 'exists': actual.exists(),
+              'proof': 'names and target checked; no directory or document written; existing files require authorized revision'}
+    if role != 'brd':
+        result['pbc'] = {'pbcId': pbc_id, 'pbcName': pbc_name}
     return result
 
 
@@ -270,73 +301,71 @@ def _store(root, path, old, value):
 
 
 def execute(project_root, manifest, action, *, ebc_id=None, ebc_name=None, role=None, path=None,
-            pbc_id=None, pbc_name=None, prd_id=None, manual=()):
+            pbc_id=None, pbc_name=None, version=None, manual=()):
     root = Path(project_root).resolve()
     if not root.is_dir():
         raise ValueError('explicit project root must already exist')
     _required_text(ebc_id, 'ebcId')
-    if action not in {'init', 'select', 'resolve'}:
+    if action not in {'init', 'select', 'resolve', 'prepare'}:
         raise ValueError('unknown handoff action')
     if action != 'resolve' and manual:
         raise ValueError('manual overrides are read-only resolve inputs')
-    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())
+    target = _manifest_path(root, manifest) if manifest else None
+    old = target.read_bytes() if target and target.is_file() else None
+    if action in {'resolve', 'prepare'}:
+        if old is not None:
+            value = _load(old)
             _check_scope(value, ebc_id, ebc_name)
-        elif manual:
-            value = {'schemaVersion': 2,
+        elif action == 'prepare' or (manual and not manifest):
+            value = {'schemaVersion': 3,
                      'scope': {'ebcId': ebc_id, 'ebcName': _required_text(ebc_name, 'ebcName')},
-                     'selected': {'topics': []}}
+                     'selected': {'pbcs': []}}
         else:
-            raise ValueError('resolve requires an explicit manifest or manual references with EBC identity')
-        return _resolve(root, value, pbc_id, prd_id, pbc_name, manual)
-    target = _manifest_path(root, manifest)
-    old = target.read_bytes() if target.is_file() else None
+            raise ValueError('manifest missing; use explicit manual resolve or return to T1; no automatic creation')
+        if action == 'prepare':
+            return _prepare(root, value, role, pbc_id, pbc_name, path, version)
+        return _resolve(root, value, pbc_id, pbc_name, manual)
+    if target is None:
+        raise ValueError('an explicit manifest path is required for this operation')
     if action == 'init':
         _required_text(ebc_name, 'ebcName')
         value = _load(old) if old is not None else {
-            'schemaVersion': 2, 'scope': {'ebcId': ebc_id, 'ebcName': ebc_name}, 'selected': {'topics': []}}
+            'schemaVersion': 3, 'scope': {'ebcId': ebc_id, 'ebcName': ebc_name}, 'selected': {'pbcs': []}}
         _check_scope(value, ebc_id, ebc_name)
         return _store(root, target, old, value)
-    if action == 'select':
-        if old is None:
-            raise ValueError('manifest missing; initialize the explicit EBC first or use manual resolve')
-        value = _load(old)
-        _check_scope(value, ebc_id, ebc_name)
-        if role in GLOBAL_ROLES and any(item is not None for item in (pbc_id, pbc_name, prd_id)):
-            raise ValueError('BRD selection belongs to the EBC and does not take PBC or PRD identity')
-        name = _topic_name(value['selected'], pbc_id, prd_id, pbc_name) if role in TOPIC_ROLES else None
-        reference = _reference(root, role, path, pbc_id, prd_id, name)
-        previous_path = _assign(value['selected'], reference, replace_document=True)
-        result = _store(root, target, old, value)
-        if previous_path is not None and previous_path != reference['path']:
-            result['updatedSelection'] = dict(reference, previousPath=previous_path)
-        return result
+    if old is None:
+        raise ValueError('manifest missing; initialize the explicit EBC first or use manual resolve')
+    value = _load(old)
+    _check_scope(value, ebc_id, ebc_name)
+    if role in GLOBAL_ROLES and (pbc_id is not None or pbc_name is not None):
+        raise ValueError('BRD selection belongs to the EBC and does not take PBC identity')
+    name = _pbc_name(value['selected'], pbc_id, pbc_name) if role in PBC_ROLES else None
+    reference = _reference(root, role, path, pbc_id, name)
+    previous_path = _assign(value['selected'], reference, replace_document=True)
+    result = _store(root, target, old, value)
+    if previous_path is not None and previous_path != reference['path']:
+        result['updatedSelection'] = dict(reference, previousPath=previous_path)
+    return result
 
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('action', choices=['init', 'select', 'resolve'])
+    parser.add_argument('action', choices=['init', 'select', 'resolve', 'prepare'])
     parser.add_argument('--project-root', required=True, help='Explicit business project root; one EBC per project')
-    parser.add_argument('--manifest', help='Explicit manifest path; new projects use spec/handoff.json; '
-                                          'omit only for resolve with manual inputs')
+    parser.add_argument('--manifest', help='Explicit manifest path; new projects use spec/handoff.json')
     parser.add_argument('--ebc-id', required=True, help='Expected EBC identity; checked on every operation')
-    parser.add_argument('--ebc-name', help='Required for init and manual resolve without a manifest')
-    parser.add_argument('--role', choices=sorted(DOCUMENT_ROLES))
-    parser.add_argument('--path', help='Explicit saved document path; new BRD: spec/<EBC-name>-BRD_v<version>.md; '
-                                     'new PRD/AD/TestCase: spec/<PBC-name>/...; relative to the business project root')
-    parser.add_argument('--pbc-id')
-    parser.add_argument('--pbc-name', help='Required when creating a topic; existing names must match')
-    parser.add_argument('--prd-id')
+    parser.add_argument('--ebc-name', help='Required for init and when no manifest exists')
+    parser.add_argument('--role', choices=sorted(DOCUMENT_ROLES | {'spec'}))
+    parser.add_argument('--path', help='Explicit adopted document or authorized new target; relative to the project root')
+    parser.add_argument('--pbc-id', help='PBC identity; no separate PRD theme identity')
+    parser.add_argument('--pbc-name', help='Required for a new PBC; existing names must match')
+    parser.add_argument('--version', help='Business document version for prepare when no path is selected; optional for spec')
     parser.add_argument('--manual', action='append', default=[], metavar='ROLE=PATH')
     args = parser.parse_args()
     try:
         result = execute(args.project_root, args.manifest, args.action, ebc_id=args.ebc_id,
                          ebc_name=args.ebc_name, role=args.role, path=args.path,
-                         pbc_id=args.pbc_id, pbc_name=args.pbc_name, prd_id=args.prd_id, manual=args.manual)
+                         pbc_id=args.pbc_id, pbc_name=args.pbc_name, version=args.version, manual=args.manual)
     except (OSError, ValueError, UnicodeError) as error:
         print(json.dumps({'ok': False, 'error': str(error)}, ensure_ascii=False))
         return 1

package/skills/i3-enterprise-sop/references/technical-baseline/baselines/enterprise-application-technical-baseline-v0-0-4.md

@@ -31,30 +31,30 @@
 | 来源 | 本次使用内容 | 整理后的维护位置 |
 | --- | --- | --- |
 | 软件架构设计 Specification 模板 v0.6，第 3—4 章 | 架构边界、已明确技术方向、按需选型、版本与兼容要求 | 本文件第 1—2 节 |
-| 同一来源，第 6—11 章 | 数据、接口、前端、Agent、集成、权限及恢复的共用约束 | 本文件第 1、3—5 节；主题接口、实体和流程由各 AD 详设 |
+| 同一来源，第 6—11 章 | 数据、接口、前端、Agent、集成、权限及恢复的共用约束 | 本文件第 1、3—5 节；各PBC的接口、实体和流程由各 AD 详设 |
 | 同一来源，第 12—17 章及附录 | 工程质量、环境、流水线、实施交接、验证与未决事项 | 本文件第 6—9 节 |
 | 使用者本轮逐项确认（2026-10-20） | 共用基线定位、Java／Spring Boot、前端工具链、MaxKey／OIDC、接口惯例、目录采用、部署分工及按项目落实的规则 | 对应第2—9节；不扩展为版本兼容、业务批准或实际环境就绪 |
 | 2026-10-21官方资料核对、本机只读检查与使用者确认 | 固定首套版本选择、保留K8s 1.28及现有GitLab；记录兼容范围与真实验证边界 | 本文件§2.3—§2.6及Q02—Q06、Q09；不自动执行升级或替项目采用 |
-| [公共技术规约资料](../readme.md) | 已有规范优先、公共规则与主题设计分工、候选与真实采用分开 | 本文件的范围、采用和版本规则 |
-| [当前 AD 模板](../../templates/ad.md) §0.3、§2.2、§9.6 | 基线引用、技术落实和真实骨架来源 | 各主题 AD 的对应条款 |
+| [公共技术规约资料](../readme.md) | 已有规范优先、公共规则与PBC设计分工、候选与真实采用分开 | 本文件的范围、采用和版本规则 |
+| [当前 AD 模板](../../templates/ad.md) §0.3、§2.2、§9.6 | 基线引用、技术落实和真实骨架来源 | 各PBC的 AD 的对应条款 |
 | [本 Skill 工程交接说明](../../../SKILL.md) 中的 T2／T3 | 选定 AD及必要配套形成工程 SPEC，再交原 Plan及获准 Build；原命令等效规格方式保留 | 本文件第9节及本 Skill T2／T3；具体技术规则未改 |
 | [目录规范1.0.0](../../engineering-skeleton/directory-standard.md) | 工程目录与职责、AD映射、原Plan任务路径、获准Build的实际文件落点 | 本文件第1、6—9节；目录规范可先采用，不要求预先取得代码框架模板 |
 | 原Ship命令及原Spec的内容要求（通过实际宿主发现；[调用边界](../../../SKILL.md)） | 发布前检查／决策／回滚，及原SPEC六项的工程命令和项目依据 | 本文件第6—7、9节；原命令与Skill未改 |
 
-源材料沿用总体 `design.md` 和旧 MVP 产物组织。本文件只提取其中适用的技术内容，并按当前已确认的“公共规约＋多主题 PRD／AD”组织；不恢复旧 MVP 流程，不改动源文件，不要求把公共规则复制到每份 AD。原文要求明确写出规则的目的继续保留：AD 必须指出准确规则、适用范围和落实位置，不能只写“沿用旧规范”。
+源材料沿用总体 `design.md` 和旧 MVP 产物组织。本文件只提取其中适用的技术内容，并按当前已确认的“公共规约＋各PBC的一套PRD／AD”组织；不恢复旧 MVP 流程，不改动源文件，不要求把公共规则复制到每份 AD。原文要求明确写出规则的目的继续保留：AD 必须指出准确规则、适用范围和落实位置，不能只写“沿用旧规范”。
 
 本规约保留已确认技术条款及其来源说明，仅分发当前版本；工程组织统一采用同一SOP Skill内的1.0.0目录规范，采用信息由AD现有表格记录。来源材料或发行资源后续修改，不自动改变项目已经采用的版本。
 
 ## 1. 共用架构与工程边界
 
-| 条款 | 共用规则 | 主题 AD 的落实责任 |
+| 条款 | 共用规则 | PBC的 AD 落实责任 |
 | --- | --- | --- |
-| ARC-01 | 根据真实业务目标确定逻辑模块、工程、运行应用和部署单元；一个 PBC 不自动等于一个微服务、仓库或数据库 | 明确本主题组件职责、依赖、运行单元和部署关系，以及采用或拆分理由 |
+| ARC-01 | 根据真实业务目标确定逻辑模块、工程、运行应用和部署单元；一个 PBC 不自动等于一个微服务、仓库或数据库 | 明确本PBC的组件职责、依赖、运行单元和部署关系，以及采用或拆分理由 |
 | ARC-02 | 前端负责交互与呈现；业务服务负责正式业务规则、最终授权、状态及数据；Agent 负责其获准的分析或工具执行；任务工程负责实际选择的触发、执行与恢复职责 | 给出三图和详设，绑定实际组件及数据维护责任；按需采用工程类型，不为凑目录新增服务 |
 | ARC-03 | 前端临时状态、Agent 会话或执行结果、工作流历史、任务状态与正式业务状态分别维护 | 写清各类状态的存储、可信来源、标识映射及最终业务完成条件 |
 | ARC-04 | Dapr 的运行支撑能力与项目业务授权、数据责任及人工决定分开设计 | 明确所用能力、组件、调用方向、业务校验和失败责任；服务能够互通不代表用户获准操作 |
 | ARC-05 | 缓存、向量检索、消息、GIS、三维、多 Agent 等按实际需求选择 | 给出需求来源、用途和选型；不使用时说明理由，未知时列为待确认 |
-| ARC-06 | 消费外部能力应依据正式契约，不复制提供方内部实现作为本主题权威 | 固定提供／消费关系和版本；分别记录已可用、待核实、待接入及真实联调条件 |
+| ARC-06 | 消费外部能力应依据正式契约，不复制提供方内部实现作为本PBC权威 | 固定提供／消费关系和版本；分别记录已可用、待核实、待接入及真实联调条件 |
 
 来源：软件技术说明第3、5、8—11章；现有工程骨架目录方案及目录规范1.0.0的职责分工。
 
@@ -209,7 +209,7 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 
 ### 4.1 已确认的接口与数据惯例
 
-| 范围 | 共用约定 | 项目及主题AD补充内容 |
+| 范围 | 共用约定 | 项目及PBC的AD补充内容 |
 | --- | --- | --- |
 | API字段命名 | 本项目自有API字段使用camelCase | 外部契约或既有系统沿用其真实定义，适配处写明映射与例外 |
 | 数据库字段命名 | 本项目新建数据库字段使用snake_case | 保留存量字段，具体表名、约束、索引及schema按工程实际明确 |
@@ -234,9 +234,9 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 | AGT-03 | 模型、Prompt、工具描述与流程版本分别追踪；不能暗中替换模型。知识检索、记忆和多 Agent 按需设计，资料与工具返回不能修改系统权限 |
 | AGT-04 | 定义模型／工具调用、Token、时长、并发和循环预算，以及超限、取消和人工处理行为；具体数值依据业务和工程事实，不能由模板填造 |
 
-来源：软件技术说明第 7、9、10 章。具体业务接口、事件、工具和模型尚未提供；它们属于对应主题 AD 及正式契约的后续设计内容。
+来源：软件技术说明第 7、9、10 章。具体业务接口、事件、工具和模型尚未提供；它们属于对应PBC的 AD 及正式契约的后续设计内容。
 
-## 5. 数据、状态与跨主题责任
+## 5. 数据、状态与跨PBC责任
 
 - DATA-01：每项正式业务实体、共享字段、状态及共享文件明确唯一逻辑维护责任与受控读写边界。共用数据库实例不代表允许跨模块任意读写。
 - DATA-02：业务数据、执行历史、Agent 会话、缓存和检索索引分别说明权威来源、保存范围、过期语义、恢复及清理责任；临时或派生数据不能冒充正式结果。
@@ -245,7 +245,7 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 - DATA-05：状态迁移、终态、撤销、重开、删除和保留要求来自 PRD 及实际项目决定；不能用技术规约新增权限、删除能力或保留期限。
 - DATA-06：索引根据真实查询和数据特征设计，并核写入及维护成本；迁移、初始化、回填、备份、应用回滚和数据恢复分别说明。
 
-命名、跨端大整数标识、时间点和错误关联的共用惯例按§4.1执行。主键生成、审计字段、实际时区／格式、删除方式和保留期按项目与业务依据落实，见Q07、Q10；具体实体及提供／消费责任从选定PRD和主题AD形成，见Q12，不要求提前填入通用规约。来源：软件技术说明第6—7、9、11、13章、当前AD模板及使用者确认。
+命名、跨端大整数标识、时间点和错误关联的共用惯例按§4.1执行。主键生成、审计字段、实际时区／格式、删除方式和保留期按项目与业务依据落实，见Q07、Q10；具体实体及提供／消费责任从选定PRD和PBC的AD形成，见Q12，不要求提前填入通用规约。来源：软件技术说明第6—7、9、11、13章、当前AD模板及使用者确认。
 
 ## 6. 工程组织、质量与原方法衔接
 
@@ -254,7 +254,7 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 - ENG-01：工程骨架沿用现有[目录规范1.0.0](../../engineering-skeleton/directory-standard.md)。`pbc-composite`与`agent-standalone`是组织方式，frontend、backend、agents、jobs及配套契约、共享代码、测试和交付位置按需采用；内部遵循实际语言／框架惯例。
 - ENG-02：目录规范是实际可读的设计输入，可以在工程创建前采用。AD记录规范来源／版本、业务项目根、已有／拟建工程和模块映射；未采用代码框架模板时如实说明，不要求预先取得企业代码模板或冻结首套完整技术栈。
 - ENG-03：AD §9.2明确源码、模块、配置、测试、契约及装配位置，§9.6说明已有工程与拟建内容；原Plan把预计新增／修改文件路径、依赖和验证写入任务；获准的Build在这些位置生成实际内容，核对文件落点并执行原有测试／构建。
-- ENG-04：共享底座、契约和文件只有一处维护责任及实际任务来源，其他主题引用依赖；新增 PRD 不自动复制底座。再次生成或更新时保留人工修改、历史及已完成任务，冲突先核范围。
+- ENG-04：共享底座、契约和文件只有一处维护责任及实际任务来源，其他PBC引用依赖；新增 PRD 不自动复制底座。再次生成或更新时保留人工修改、历史及已完成任务，冲突先核范围。
 - ENG-05：目录规范不要求另建project.yaml、templates.lock、contracts.lock、生成记录库或代码模板三方升级流程。已有项目或工具确有这些文件时按其实际用途保留；项目另行要求复用特定代码模板时，才取得该模板及所需版本、应用和验证依据。
 
 可以在现有AD的骨架栏目写明“目录规范已采用；工程拟建；未采用代码框架模板”，不能据此声称“可运行代码模板已取得”或“代码已生成”。实际目录来源为本资源附带的1.0.0定版资料；资源目录和i3维护工作区均不是业务工程输出根。
@@ -289,7 +289,7 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 
 ## 7. 版本兼容、交付与恢复
 
-- DEL-01：文档、正式契约、代码提交、依赖、制品、配置和运行环境分别定位版本；不强制所有主题 PRD／AD 同号，也不机械升级无关主题。
+- DEL-01：文档、正式契约、代码提交、依赖、制品、配置和运行环境分别定位版本；不强制所有PBC的 PRD／AD 同号，也不机械升级无关PBC。
 - DEL-02：GitLab 实例、仓库、保护规则、MR、Runner、CI 模板、镜像库、变量及环境权限按实际资源填写。设计方案、资源存在、配置完成和真实验证分开记录；企业 GitLab 方向不改动 i3 工具仓库自身的 GitHub 工作流。
 - DEL-03：流水线按项目实际组合变更检查、测试／评测、构建、迁移／部署、部署后验证及放行。每项明确触发、身份、输入、通过条件、失败处理和证据；本文件不宣称这些流水线已经存在。
 - DEL-04：K8s／Dapr 配置基于所选版本和实际需求确定工作负载、入口、运行身份、组件作用域、资源、探针、优雅退出、网络及密钥引用。端口、实例数和部署工具未定时不得猜测。
@@ -318,12 +318,12 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 | Q04 | Dapr／Agent按实际需要的能力建立组合版本和验证安排 | 按§2.3固定所用版本；在保留的K8s 1.28上验证实际安装、必要业务链、中断恢复、重复与授权失效，离线渲染不替代运行证据 | 依赖相关能力的设计／工程阶段分别核实 |
 | Q05 | PostgreSQL优先兼容企业已有受支持版本，逻辑责任与恢复分别设计 | 先定位已有服务端；17.11仅是无既有约束的新建候选，驱动42.7.14已定，扩展／实例／迁移／DDL／恢复仍须真实证据 | 数据工程设计、迁移及运行前 |
 | Q06 | 统一身份采用MaxKey，通过OIDC接入；业务服务执行最终授权 | 4.1.12为首轮接入基线，投产前核4.2.0安全更新；取得实际实例／类型、应用注册、映射、退出撤权及配置引用，不虚构claims或可用能力 | 身份相关契约和实现前 |
-| Q07 | API camelCase、数据库snake_case、跨端大整数ID字符串、明确时间点时区、稳定业务码与关联标识 | 正式契约补精确字段、分页上限、格式／精度、主键生成、审计及存量映射，避免擅改已有契约 | 相关公共契约及主题AD定稿前 |
+| Q07 | API camelCase、数据库snake_case、跨端大整数ID字符串、明确时间点时区、稳定业务码与关联标识 | 正式契约补精确字段、分页上限、格式／精度、主键生成、审计及存量映射，避免擅改已有契约 | 相关公共契约及PBC的AD定稿前 |
 | Q08 | 引用现有目录规范1.0.0，沿用原AD→Plan→Build的目录映射链 | 明确业务根及真实／拟建路径；目录规范可先采用，实际代码由获准Build生成验证；只有另行要求特定代码模板才须取得该模板 | AD映射、Plan任务文件路径、Build实际落点依次核对 |
 | Q09 | AD规定部署要求，Plan安排任务，Build形成配置，Ship核验汇总部署准备 | K8s 1.28和GitLab 19.2.4为使用者提供的环境；补完整集群信息、Runner及实际资源／权限／配置，部署资料不冒充平台已就绪 | 构建、联调、部署和发布按需落实 |
 | Q10 | 保留已有质量下限，新增指标从PRD或真实工程决定取得 | 质量、容量、恢复、预算、保留、告警与适用要求的具体值和测量方法属于项目；不得填造通用数字 | 对应测试设计、处理数据或放行前 |
 | Q11 | 根据实际情况填写各工程命令、cwd、前提、成功依据和风格 | 已有工程读取真实配置；新工程按任务创建并验证，未验证保持实际状态；不要求用户预先写假命令 | 本次规划与任务执行按依赖补足 |
-| Q12 | 具体业务主题及数据／契约责任从选定PRD和各主题AD形成 | 绑定实际接口、事件、工具、实体和提供／消费方；不把它们作为通用规约必须提前填完的内容 | 每个主题AD与必要关联契约设计时 |
+| Q12 | 具体PBC及数据／契约责任从选定PRD和各PBC的AD形成 | 绑定实际接口、事件、工具、实体和提供／消费方；不把它们作为通用规约必须提前填完的内容 | 每个PBC的AD与必要关联契约设计时 |
 
 上述共用规则及处理方式不再保持“全部待确认”。项目采用、具体版本、配置和运行结果仍需各自真实依据，不能因使用者同意规则就自动关闭。缺项只限制依赖它的范围，不无差别阻断AD起草或不相关的准备任务；也不能因文档生成完成而填造工程结果。
 
@@ -334,7 +334,7 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 ### 9.1 进入 AD
 
 1. 使用 i3-enterprise-sop生成AD时，项目未另有明确规约就默认读取本规约和目录规范，在AD记录路径、版本及范围；已有明确规约优先，冲突先说明。
-2. 选定准确 PRD 主题和版本。起草／修订 AD 必须按企业入口加载原 Spec Skill，使用完整 AD 模板；本公共规约本身不替代主题规格。
+2. 选定PBC的准确PRD和版本。起草／修订 AD 必须按企业入口加载原 Spec Skill，使用完整 AD 模板；本公共规约本身不替代PBC规格。
 3. AD §0.3登记本规约及目录规范的来源和版本，§2.2落实技术选择，§9.2映射工程及模块位置，§9.6区分现有工程和拟建内容；目录规范可在代码生成前采用，保留三图和全部详设责任。
 4. 原型按需，可与 AD 并行。记录假设和受影响未决；候选生成、完整回读和人工认可分别处理，保存后遵守原 Spec 停轮。
 
@@ -343,25 +343,25 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 ```text
 使用 i3-enterprise-sop 的 ad 动作。
 将自带《企业应用公共技术规约 v0.0.4》和目录规范作为默认输入；项目已有明确规约时优先沿用。
-先确定当前业务项目、我已选定的 PRD 主题和准确版本；存在歧义先问。
-实际读取这份规约、其引用的工程目录规范1.0.0及本次必要来源，列出适用条款、已有规范冲突和影响本主题的项目缺口。
-按原 Spec Skill 和完整 AD 模板生成本主题设计，保留三图、工程细节和 SPEC 六项。
+先确定当前业务项目、我已选定PBC的PRD和准确版本；存在歧义先问。
+实际读取这份规约、其引用的工程目录规范1.0.0及本次必要来源，列出适用条款、已有规范冲突和影响本PBC的项目缺口。
+按原 Spec Skill 和完整 AD 模板生成本PBC设计，保留三图、工程细节和 SPEC 六项。
 沿用§2.3已确认的版本矩阵，保留既有K8s 1.28与GitLab 19.2.4；逐项区分目标与实装，未验证的兼容性、具体字段和工程映射按实际来源补足。
-按现有目录规范明确本主题源码、模块、配置、测试和契约的已有／拟建位置，不要求预先提供一套代码框架模板，也不宣称工程已生成。
+按现有目录规范明确本PBC源码、模块、配置、测试和契约的已有／拟建位置，不要求预先提供一套代码框架模板，也不宣称工程已生成。
 保留已有人工修改，回读最终稿，交我审阅后停轮，不进入 Plan 或 Build。
 ```
 
 ### 9.2 交原 Plan
 
-以选定AD为入口，读取其准确PRD、本规约适用条款、共享契约、目录规范及AD工程映射和已有代码；尚无代码时如实记录拟建，不虚构工程根。按主题加载完整必要内容，核本范围SPEC六项和FR／AC；Plan任务保留真实／拟建文件路径及验证依据，不全量注入无关AD和历史。
+以选定AD为入口，读取其准确PRD、本规约适用条款、共享契约、目录规范及AD工程映射和已有代码；尚无代码时如实记录拟建，不虚构工程根。按PBC加载完整必要内容，核本范围SPEC六项和FR／AC；Plan任务保留真实／拟建文件路径及验证依据，不全量注入无关AD和历史。
 
-本规约的来源标识、准确路径或URL、文内版本或固定提交、适用条款、采用范围与例外、实际读取及缺口，统一记录在AD §0.3；工程映射与实际模板／骨架来源由AD §9.6承接。后续工程SPEC／Plan沿AD引用读取准确原件，不再将规约路径或采用信息写入 `handoff.json`，也不另建采用说明。`handoff.json`仅记录EBC／PBC身份及已选BRD／PRD／AD／TestCase文档路径，主题AD仍按相应文档角色登记。可以手动给出准确路径，不强制创建清单；引用或登记不证明已读，也不表示文档获批。
+本规约的来源标识、准确路径或URL、文内版本或固定提交、适用条款、采用范围与例外、实际读取及缺口，统一记录在AD §0.3；工程映射与实际模板／骨架来源由AD §9.6承接。后续工程SPEC／Plan沿AD引用读取准确原件，不再将规约路径或采用信息写入 `handoff.json`，也不另建采用说明。`handoff.json`仅记录EBC／PBC身份及已选BRD／PRD／AD／TestCase文档路径，PBC的AD仍按相应文档角色登记。可以手动给出准确路径，不强制创建清单；引用或登记不证明已读，也不表示文档获批。
 
 ```text
 /i3-plan
 以我本轮明确选定的AD为规划入口，实际读取它引用的PRD、公共技术规约适用条款、共享契约、工程目录规范及已有代码。
 公共技术规约按AD §0.3采用记录中的准确路径、文内版本及适用条款回读，不以AD引用或清单存在代替正文读取；规约采用信息不写入handoff.json。
-核对本主题需求、验收条件、SPEC 六项、共享依赖和未决影响；TestCase 按需引用。
+核对本PBC需求、验收条件、SPEC 六项、共享依赖和未决影响；TestCase 按需引用。
 按AD的工程／模块映射，将每项任务预计新增或修改的文件路径、真实来源、初始化或增量内容及验证依据保留在原计划和唯一任务目标中，交我审阅，暂不实施。
 ```
 
@@ -375,6 +375,6 @@ PostgreSQL已定位的是Homebrew libpq 18.3工具。在已查常见路径、进
 
 本版保留2026-10-20／21确认的共用规则、技术版本矩阵、本机及既有平台事实、官方依据与V01—V06验证安排，并按2026-10-22确认采用工程目录规范1.0.0，本副本的采用信息直接由AD记录。Q02—Q06、Q09区分已选择版本与仍待取得的环境／运行证据；其他已确认规则保留。K8s 1.28继续保留，三组Dapr离线渲染不作为真实集群通过证明。
 
-本文件可供人工审阅，并可在明确选用后作为 AD 的公共输入。它不证明某项目的整体技术设计已经批准，也不证明所有主题可交 Plan、可直接 Build 或已通过运行验收。
+本文件可供人工审阅，并可在明确选用后作为 AD 的公共输入。它不证明某项目的整体技术设计已经批准，也不证明所有PBC可交 Plan、可直接 Build 或已通过运行验收。
 
 版本记录：v0.0.4（2026-10-22）统一SOP Skill内的工程目录来源1.0.0及资源引用，技术选型、版本矩阵和验证边界保留。通用模板、AD模板、原版Skill／命令、已有UI原型能力与业务稿未改。未执行技术栈安装、升级、部署或npm发布，i3发行版本未调整。