@givolt/i3-composer-agent 2.3.6 → 3.0.0

package/references/enterprise-sop-resources/selection_handoff.py

@@ -0,0 +1,225 @@
+"""One-topic path selection, used only after controlled readonly preflight.
+
+Business documents and Plan are never written. Source quotes bind paths, not
+business compatibility or approval. Existing handoff storage remains canonical.
+"""
+import copy
+import importlib.util
+import json
+from pathlib import Path
+import re
+import sys
+import uuid
+
+sys.dont_write_bytecode = True
+RESOURCES = Path(__file__).resolve().parent
+
+
+def _module(name, file):
+    spec = importlib.util.spec_from_file_location(name, file)
+    module = importlib.util.module_from_spec(spec); spec.loader.exec_module(module)
+    return module
+
+
+handoff = _module('selection_json', RESOURCES/'handoff.py')
+native = _module('selection_native', RESOURCES/'verification/check_native_execution.py')
+ROLES = {'prd', 'ad', 'testCase', 'prototype'}
+PAIRS = {('ad', 'prd'), ('testCase', 'prd'), ('testCase', 'ad'), ('prototype', 'prd')}
+
+
+def _file(root, raw):
+    if not isinstance(raw, str) or not raw.strip():
+        raise ValueError('selection requires an explicit file path')
+    path = (root/raw).resolve()
+    if not path.is_relative_to(root) or not path.is_file() or not path.read_text(encoding='utf-8').strip():
+        raise ValueError('selection source missing, empty or outside project: '+raw)
+    return str(path.relative_to(root))
+
+
+def plan(project_root, request):
+    root = Path(project_root).resolve()
+    fields = {'schemaVersion', 'operation', 'work', 'manifest', 'capabilityId', 'prdId', 'target', 'links', 'inputs', 'task', 'preview'}
+    if not isinstance(request, dict) or set(request)-fields or type(request.get('schemaVersion')) is not int or request['schemaVersion'] != 1:
+        raise ValueError('selection request contract differs')
+    if request.get('operation') not in ('selection-preview', 'selection-switch'):
+        raise ValueError('explicit selection operation required')
+    if not all(isinstance(request.get(k), str) and request[k].strip() for k in ('work', 'capabilityId', 'prdId', 'task')):
+        raise ValueError('explicit work and selected topic identity required')
+    mf = handoff._manifest_path(root, request.get('manifest'))
+    before_bytes = mf.read_bytes(); raw = before_bytes.decode('utf-8')
+    before = handoff._load(before_bytes)
+    if before['scope']['work'] != request['work']:
+        raise ValueError('selection manifest belongs to another work')
+    matches = [t for t in before['selected'].get('topics', []) if all(t[k] == request[k] for k in ('capabilityId', 'prdId'))]
+    if len(matches) != 1:
+        raise ValueError('explicit topic is not uniquely selected; no latest-version fallback')
+    old_topic = matches[0]; topic = copy.deepcopy(old_topic)
+    target = request.get('target')
+    if not isinstance(target, dict) or set(target)-ROLES or not isinstance(target.get('prd'), str):
+        raise ValueError('target must explicitly name PRD and only local companion roles')
+    for role, path in target.items():
+        if path is None and role != 'prd': topic.pop(role, None)
+        else: topic[role] = _file(root, path)
+    expected = handoff._selected_only(before)
+    expected['selected']['topics'][before['selected']['topics'].index(old_topic)] = topic
+    # The selected scope supplies shared dependencies; no unrelated topic is loaded.
+    selected = handoff._resolve(root, before, request['capabilityId'], request['prdId'], ())['references']
+    paths = [_file(root, item['path']) for item in selected]
+    paths += [_file(root, topic[role]) for role in sorted(ROLES) if role in topic]
+    inputs = request.get('inputs', [])
+    if not isinstance(inputs, list): raise ValueError('inputs must be explicit paths')
+    paths += [_file(root, p) for p in inputs]
+    delivery = before.get('delivery', {})
+    if not isinstance(delivery, dict): raise ValueError('delivery must remain an object')
+    plan_paths = [_file(root, delivery[k]) for k in ('plan', 'taskTarget') if k in delivery]
+    plan_paths += [_file(root, p) for p in ('tasks/plan.md', 'tasks/todo.md') if (root/p).exists()]
+    paths = list(dict.fromkeys(paths+plan_paths))
+    links = request.get('links', [])
+    if not isinstance(links, list): raise ValueError('links must be a caller supplied source-evidence array')
+    by_pair = {}
+    for link in links:
+        if not isinstance(link, dict) or set(link) != {'role', 'upstreamRole', 'line', 'quote'}:
+            raise ValueError('source evidence needs role/upstreamRole/line/quote')
+        pair = (link['role'], link['upstreamRole'])
+        if pair not in PAIRS or pair in by_pair: raise ValueError('ambiguous or unsupported companion source evidence')
+        by_pair[pair] = link
+    gaps = []; checks = []
+    for role, upstream_role in sorted(PAIRS):
+        if role not in topic: continue
+        link = by_pair.get((role, upstream_role)); upstream = topic.get(upstream_role)
+        lines = (root/topic[role]).read_text().splitlines(); passed = False
+        if link and upstream and type(link['line']) is int and 1 <= link['line'] <= len(lines):
+            quote = lines[link['line']-1]
+            tokens = re.findall(r'`([^`]+)`|\]\(([^)]+)\)', quote)
+            passed = quote == link['quote'] and any(upstream == token for pair in tokens for token in pair if token)
+        check = {'role': role, 'path': topic[role], 'upstreamRole': upstream_role, 'upstreamPath': upstream,
+                 'passed': passed, 'evidence': link, 'semanticCompatibility': 'requires-human-review'}
+        checks.append(check)
+        if not passed: gaps.append({'code': 'companion_source_unconfirmed', **check})
+    diff = [{'role': role, 'before': old_topic.get(role), 'after': topic.get(role)}
+            for role in sorted(ROLES) if old_topic.get(role) != topic.get(role)]
+    tasks = []; mentions = []
+    changed_paths = {x[k] for x in diff for k in ('before', 'after') if x[k]}
+    for path in list(dict.fromkeys(plan_paths+[p for p in paths if p.startswith('tasks/')])):
+        for n, line in enumerate((root/path).read_text().splitlines(), 1):
+            checkbox = re.match(r'^\s*[-*]\s+\[([ xX])\]\s+(.+)', line)
+            if checkbox:
+                tasks.append({'path': path, 'line': n, 'state': 'completed' if checkbox[1].lower() == 'x' else 'unfinished', 'text': checkbox[2]})
+            found = sorted(p for p in changed_paths if p in line)
+            if found: mentions.append({'path': path, 'line': n, 'text': line, 'references': found})
+    base_request = {'schemaVersion': 1, 'operation': 'manual', 'work': request['work'],
+        'manifest': str(mf.relative_to(root)), 'reference': {'role': 'prd', 'path': topic['prd'],
+            'capabilityId': request['capabilityId'], 'prdId': request['prdId']},
+        'inputs': paths, 'task': request['task']+' 仅只读改选预检；不得自行登记、改稿或调整Plan。'}
+    return {'projectRoot': str(root), 'manifest': str(mf.relative_to(root)), 'request': request,
+        'beforeText': raw, 'expected': expected, 'beforeTopic': old_topic, 'afterTopic': topic,
+        'diff': diff, 'sourceChecks': checks, 'gaps': gaps, 'preflightRequest': base_request,
+        'sharedReferences': [x for x in selected if x['role'] not in ROLES],
+        'planImpact': {'paths': list(dict.fromkeys(plan_paths)), 'tasks': tasks, 'mentions': mentions,
+            'automaticallyUpdated': False, 'completionEvidence': 'checkbox text only; not execution proof',
+            'nextAction': '将选定AD及准确来源显式交原Plan核影响；修改计划与开工认可另行处理。'},
+        'engineeringReady': False, 'businessApproved': False}
+
+
+def freeze(selection, files):
+    """Outside-project preview evidence, not an approval or business JSON field."""
+    return {'schemaVersion': 1, 'kind': 'i3-sop-selection-preview', 'id': str(uuid.uuid4()),
+            'plan': copy.deepcopy(selection), 'files': copy.deepcopy(files)}
+
+
+def _intent(selection):
+    request = selection['request']
+    return {'projectRoot': selection['projectRoot'], 'manifest': selection['manifest'],
+            **{k: request[k] for k in ('work', 'capabilityId', 'prdId', 'links', 'inputs') if k in request},
+            'target': {k: selection['afterTopic'].get(k) for k in request['target']}}
+
+
+def apply(project_root, selection, receipt, *, authorized=False, on_store=None):
+    if authorized is not True: raise ValueError('exact selection authorization required')
+    root = Path(project_root).resolve()
+    if (receipt.get('schemaVersion') != 1 or receipt.get('kind') != 'i3-sop-selection-preview'
+            or not isinstance(receipt.get('id'), str) or not isinstance(receipt.get('files'), dict)):
+        raise ValueError('valid saved selection preview required')
+    saved = receipt['plan']
+    if (_intent(saved) != _intent(selection) or saved['expected'] != selection['expected']
+            or saved['projectRoot'] != str(root)):
+        raise ValueError('preview does not name this exact selection')
+    if saved['gaps'] or selection['gaps']: raise ValueError('companion source evidence unresolved')
+    mf = handoff._manifest_path(root, selection['manifest'])
+    current = mf.read_bytes(); before_files = native.inventory(root)
+    delta = [p for p in set(before_files)|set(receipt['files']) if before_files.get(p) != receipt['files'].get(p)]
+    if delta:
+        # A repeated, already-applied exact switch is a no-op. No new business
+        # content or other topic change may ride along with the old preview.
+        history = [p for p in delta if p != selection['manifest']]
+        history_parent = mf.parent/'history'
+        repeated = (handoff._load(current) == saved['expected'] and len(history) == 1
+                    and selection['manifest'] in delta and history[0] not in receipt['files'])
+        if repeated:
+            hp = handoff._manifest_path(root, history[0])
+            repeated = (hp.parent == history_parent and hp.name.startswith(mf.stem+'-')
+                        and hp.suffix == '.json' and hp.read_bytes() == saved['beforeText'].encode('utf-8'))
+        if repeated: return {'ok': True, 'changed': False, 'readbackPassed': True, 'changedFiles': []}
+        raise ValueError('project changed since preview; re-read and create a new preview')
+    if current != saved['beforeText'].encode('utf-8'):
+        raise ValueError('manifest changed since preview')
+    if on_store: on_store()
+    result = handoff._store(root, mf, current, saved['expected'])
+    after_files = native.inventory(root)
+    changed = sorted(p for p in set(before_files)|set(after_files) if before_files.get(p) != after_files.get(p))
+    allowed = [selection['manifest'], result['history']] if result['changed'] else []
+    if (set(changed) != set(allowed) or handoff._load(mf.read_bytes()) != saved['expected']
+            or (result['changed'] and (root/result['history']).read_bytes() != current)):
+        raise ValueError('selection postcheck failed; retain actual files for human review, no automatic rollback')
+    return {**result, 'readbackPassed': True, 'changedFiles': changed}
+
+
+def finish(prepared, evidence, *, authorized, response):
+    """Called after real native receipts and current file boundaries pass."""
+    root = Path(prepared['root']); proposal = prepared['selection']; request = prepared['request']
+    summary = {k: proposal[k] for k in ('diff', 'sourceChecks', 'gaps', 'sharedReferences', 'planImpact', 'engineeringReady')}
+    out = response('needs_confirmation', 'selection_confirmation_required',
+                   '改选预检完成；请核配套及Plan影响，再明确选择该组路径。',
+                   recommendation='核对预览；配套未确认先补证据或明确解除引用，保留文档原件。')
+    out['selection'] = summary
+    out['options'] = [{'id': 'keep-selection', 'label': '保留当前选择'},
+                      {'id': 'prepare-companions', 'label': '补齐配套或明确解除引用后重新预览'},
+                      {'id': 'manual-handoff', 'label': '本次手动交接路径'},
+                      {'id': 'stop', 'label': '暂停并保留现场'}]
+    if request['operation'] == 'selection-preview':
+        preview = freeze(proposal, prepared['scope']['files'])
+        (evidence/'selection-preview.json').write_text(json.dumps(preview, ensure_ascii=False, indent=2)+'\n')
+        out['preview'] = {'id': preview['id'], 'path': str(evidence/'selection-preview.json')}
+    else:
+        preview = prepared['selectionReceipt']
+        if native.loads(Path(request['preview']).read_text()) != preview:
+            return response('blocked', 'selection_preview_changed', '预览证据已改变；保留现场并重新预览。')
+        out['preview'] = {'id': preview.get('id'), 'path': request['preview']}
+    if proposal['gaps']:
+        out['reason']['code'] = 'selection_companions_unconfirmed'
+        out['reason']['message'] = '现有配套或调用方原文证据不能绑定目标上游；本次不改选。'
+        out['recommendation']['id'] = 'prepare-companions'
+        return out
+    out['options'].insert(1, {'id': 'authorize-selection', 'label': '明确委托切换到此预览的准确组合'})
+    out['recommendation']['id'] = 'authorize-selection'
+    if request['operation'] != 'selection-switch' or not authorized:
+        return out
+    registration = {'attempted': False, 'attempts': 0, 'kind': 'direct-python-api',
+                    'entry': 'selection_handoff.apply -> handoff._store', 'shell': False, 'previewId': preview.get('id')}
+    def on_store():
+        registration.update(attempted=True, attempts=1)
+        (evidence/'selection-registration.json').write_text(json.dumps(registration, indent=2)+'\n')
+    try:
+        result = apply(root, proposal, preview, authorized=True, on_store=on_store)
+        registration['result'] = result
+        (evidence/'selection-readback.json').write_text(json.dumps(result, ensure_ascii=False, indent=2)+'\n')
+        out = response('selected' if result['changed'] else 'unchanged', 'selection_applied',
+                       '准确组合及差量已回读；业务稿、其他主题和原Plan保持，后续规划认可另行处理。')
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        registration['error'] = str(exc)
+        out = response('blocked', 'selection_not_applied', str(exc),
+                       recommendation='保留当前内容；核对变化或锁后用新预览处理，不自动重试或回滚。')
+    out['registration'] = registration
+    out['selection'] = summary
+    (evidence/'selection-registration.json').write_text(json.dumps(registration, ensure_ascii=False, indent=2)+'\n')
+    return out

package/references/enterprise-sop-resources/stages.json

@@ -0,0 +1,262 @@
+{
+  "schemaVersion": 1,
+  "resourceId": "i3-enterprise-sop",
+  "resourceVersion": "0.16.2",
+  "status": "local-short-command-plan-candidate",
+  "activation": "explicit-enterprise-task-or-applicable-recorded-selection",
+  "ordinaryInstallEnablesEnterpriseWorkflow": false,
+  "sharedContract": "template-contracts.md",
+  "integrityManifest": "assets-manifest.json",
+  "stagePathBase": "this-index-directory",
+  "stageFilePathBase": "selected-stage-manifest-directory",
+  "stages": {
+    "brd": {
+      "documentType": "BRD",
+      "resourceRoot": "brd",
+      "manifest": "brd/assets-manifest.json",
+      "resourceVersion": "0.2.3",
+      "templateVersion": "v0.0.3",
+      "templateRole": "complete-document-template",
+      "actions": [
+        "generate",
+        "review",
+        "revise",
+        "recheck"
+      ]
+    },
+    "prd": {
+      "documentType": "PRD",
+      "resourceRoot": "prd",
+      "manifest": "prd/assets-manifest.json",
+      "resourceVersion": "0.3.3",
+      "templateVersion": "v0.0.4",
+      "templateRole": "complete-document-template",
+      "actions": [
+        "generate",
+        "review",
+        "revise",
+        "recheck"
+      ]
+    },
+    "ad": {
+      "documentType": "AD",
+      "resourceRoot": "ad",
+      "manifest": "ad/assets-manifest.json",
+      "resourceVersion": "0.3.3",
+      "templateVersion": "v0.0.4",
+      "templateRole": "complete-document-template",
+      "actions": [
+        "generate",
+        "review",
+        "revise",
+        "recheck"
+      ]
+    },
+    "testcase": {
+      "documentType": "TestCase",
+      "resourceRoot": "testcase",
+      "manifest": "testcase/assets-manifest.json",
+      "resourceVersion": "0.3.4",
+      "templateVersion": "v0.0.4",
+      "templateRole": "complete-document-template",
+      "actions": [
+        "generate",
+        "review",
+        "revise",
+        "recheck"
+      ]
+    }
+  },
+  "existingPrdSubtreePreserved": false,
+  "sopCommandImplemented": true,
+  "autoSupported": false,
+  "engineeringAssetsIncluded": false,
+  "projectModifiedCopiesPreserved": true,
+  "handoffContract": "handoff-contract.md",
+  "projectGuide": "codebuddy-project-guide.md",
+  "auxiliaryResources": {
+    "technical-baseline": {
+      "resourceRoot": "technical-baseline",
+      "manifest": "technical-baseline/assets-manifest.json",
+      "resourceVersion": "0.2.0",
+      "templateVersion": "v0.0.1",
+      "businessStage": false,
+      "role": "shared-engineering-guidance",
+      "baselineCatalog": "technical-baseline/assets-manifest.json",
+      "explicitAdoptionRequired": true
+    }
+  },
+  "manualHandoffSupported": true,
+  "jsonRegistrationImplemented": true,
+  "lifecycleContract": "lifecycle-contract.md",
+  "existingPrdTemplatePreserved": true,
+  "candidateRevision": "20261021-plan-gates-r4",
+  "readEvidenceChecker": {
+    "entry": "verification/README.md",
+    "script": "verification/check_reads.py",
+    "traceFormat": "codebuddy-stream-json",
+    "automaticActivation": false,
+    "writesProjectFiles": false,
+    "version": "0.3.1",
+    "reviewOutputContract": "verification/review-output.schema.json",
+    "roleBindings": "caller-verification-scope-only",
+    "schemaBuilder": {
+      "module": "verification/check_reads.py",
+      "function": "build_review_schema"
+    },
+    "reportContentChecker": "check_report"
+  },
+  "sopSkillImplemented": true,
+  "sopSkillScope": "explicit-single-stage-native-spec-or-planning-and-reference-handoff",
+  "handoffHelper": {
+    "script": "handoff.py",
+    "version": "0.2.0",
+    "operations": [
+      "init",
+      "select",
+      "resolve"
+    ],
+    "selection": "initial-or-same-only; exact same-topic replacement via controlled preview",
+    "manualSupported": true,
+    "python": "3.9+",
+    "semanticOrApprovalValidation": false,
+    "originalPlanBuildConsumptionVerified": false,
+    "manifestFields": [
+      "schemaVersion",
+      "scope",
+      "selected"
+    ]
+  },
+  "executionEvidenceChecker": {
+    "script": "verification/check_execution.py",
+    "version": "0.1.0",
+    "automaticActivation": false,
+    "writesProjectFiles": false,
+    "reportContract": "handoff-contract.md#9-真实调用与执行报告",
+    "profile": "CodeBuddy stream-json/direct-python3-helper",
+    "verdictDoesNotApproveBusiness": true
+  },
+  "generation": {
+    "requiredSkill": "i3-spec-driven-development",
+    "wrapperCommandUnchanged": true,
+    "nativeStopPreserved": true
+  },
+  "businessDocuments": {
+    "defaultRoot": "spec",
+    "layout": "one-capability-one-directory",
+    "existingAdoptedPathsPreserved": true,
+    "resourceRootUnchanged": true,
+    "engineeringEntry": "selected AD plus explicitly referenced selected sources",
+    "context": "selected topic and required shared dependencies"
+  },
+  "nativeHandoff": {
+    "plan": "SPEC.md or equivalent; original outputs and approval unchanged",
+    "build": "approved next task",
+    "buildAuto": "original spec, git, plan approval and per-task loop unchanged",
+    "manifestAutomaticallyConsumedByOriginalCommands": false,
+    "manualSupported": true,
+    "verification": "see current independent evidence; not inferred from index"
+  },
+  "nativeExecutionEvidenceChecker": {
+    "script": "verification/check_native_execution.py",
+    "version": "0.1.1",
+    "profiles": [
+      "generation",
+      "status",
+      "plan",
+      "auto-preflight",
+      "standard"
+    ],
+    "automaticActivation": false,
+    "writesProjectFiles": false,
+    "helperCheckerUnchanged": true,
+    "createsApproval": false,
+    "reportContract": "verification/README.md#原生方法与执行报告"
+  },
+  "recoveryContract": "recovery-contract.md",
+  "minimalRecovery": {
+    "implemented": "owned skill procedure reusing handoff.py",
+    "documentWrites": false,
+    "newHelperOperations": false,
+    "draftCompletionValidation": "caller actual task and final full read; not helper nonempty-path check",
+    "supports": [
+      "readonly-partial-draft-assessment",
+      "explicit-selected-reference-backfill",
+      "idempotent-registration",
+      "human-edit-protection"
+    ],
+    "selectionReplacementImplemented": true,
+    "crossEditorTransactionGuaranteed": false,
+    "selectionReplacementScope": "one-existing-topic PRD and explicit local companions; shared sources unchanged",
+    "topicCancellationImplemented": false
+  },
+  "controlledHandoff": {
+    "script": "controlled_handoff.py",
+    "contract": "controlled-handoff.md",
+    "version": "0.4.0",
+    "host": "codebuddy-cli-project",
+    "activation": "explicit-single-task",
+    "nativeReadOnlyPreflight": true,
+    "automaticHook": false,
+    "businessApproval": false,
+    "enterpriseAuto": false,
+    "selection": {
+      "module": "selection_handoff.py",
+      "contract": "selection-handoff.md",
+      "operations": [
+        "selection-preview",
+        "selection-switch"
+      ],
+      "exactPreviewRequired": true,
+      "topicScope": "one-existing-topic",
+      "changesSharedSources": false,
+      "writesBusinessDocumentsOrPlan": false,
+      "semanticCompatibility": "caller-source-quotes-and-human-review"
+    },
+    "auditBeforeSelectedWrite": true
+  },
+  "independentReview": {
+    "contract": "review-handoff.md",
+    "script": "verification/review_handoff.py",
+    "version": "0.2.0",
+    "host": "codebuddy-cli",
+    "activation": "explicit-single-review-or-recheck",
+    "freshSession": true,
+    "projectWrites": false,
+    "businessApproval": false,
+    "missingHost": "new-session-task",
+    "selectedOnlyRegistrationValidation": "pending-S10",
+    "contextProfile": "fixed-review-context-v1",
+    "modelReads": "full stage README, template, unique action, review contract and necessary actual project/business sources; full selected fallback for unknown/custom combinations",
+    "outerChecks": "metadata resolution and source snapshots retained; never model-read evidence"
+  },
+  "planHandoff": {
+    "contract": "plan-handoff.md",
+    "requiredSkill": "i3-planning-and-task-breakdown",
+    "originalCommandObligationsPreserved": true,
+    "defaultOutputs": [
+      "tasks/plan.md",
+      "tasks/todo.md"
+    ],
+    "writesBusinessJson": false,
+    "manualSupported": true,
+    "buildAutomaticallyInvoked": false,
+    "requiredResourceReads": [
+      "README.md",
+      "stages.json",
+      "template-contracts.md",
+      "handoff-contract.md",
+      "plan-handoff.md"
+    ],
+    "identityOrUpstreamConflict": "stop-before-native-planning-and-plan-todo-writes"
+  },
+  "operations": [
+    "brd",
+    "prd",
+    "ad",
+    "testcase",
+    "plan",
+    "review",
+    "status"
+  ]
+}

package/references/enterprise-sop-resources/technical-baseline/README.md

@@ -0,0 +1,132 @@
+# 公共技术规约：采用说明
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+资源版本：0.2.0；通用模板内容版本：v0.0.1；可选企业应用技术规约：v0.0.2。状态：自有分发资源本地候选，尚未发布。实际打包、安装和宿主使用以对应轮次证据为准。
+
+本资源帮助项目固定共用工程约束及其来源。已有规范优先，新项目缺少规范时才起草最小候选。它不是第五个业务阶段、总AD、项目配置或批准记录；不新增Skill、命令、路由和执行器。
+
+## 0. 模板与可选技术规约
+
+| 资料 | 用途与采用边界 |
+| --- | --- |
+| [公共技术规约模板](templates/TECHNICAL-BASELINE.md) v0.0.1 | 根据项目真实资料起草规约，或核对已有规范的覆盖；不默认技术栈 |
+| [企业应用公共技术规约](baselines/企业应用-技术规约_v0.0.2.md) v0.0.2 | 包含已确认的Java／Spring Boot、Vue／TypeScript／Antdv Next、MaxKey／OIDC等技术方向及按需工程约定；项目明确选择后才生效 |
+| [来源与固定依赖说明](baselines/PROVENANCE.md) | 区分来源追溯与运行时资料；附带该规约引用的目录规范／采用说明0.2.0，不自动采用其他会话的新版本 |
+
+随包提供不等于所有项目默认采用。项目已有适用规范时先复用；选择本规约时记录准确路径、文内版本、适用范围及必要差异。多个版本或来源并存且未明确选择时先确认，不按目录最大版本猜选。
+
+项目需要调整时，沿用项目现有规范位置或明确维护项目副本；发行原件与项目规范分别定位。项目自改副本优先，不用发行摘要恢复它，不在升级时覆盖项目规范；不可读或存在冲突时如实报告，不静默切换。
+
+最短任务示例：
+
+```text
+/i3-sop ad
+为当前选定的PRD生成AD，采用随包提供的《企业应用公共技术规约 v0.0.2》。先核项目已有规范和适用范围，按索引定位并完整读取规约及必要目录资料；保留项目自改内容和未决项，生成后交我审阅，暂不进入Plan或Build。
+```
+
+资料由现有入口按阶段索引的auxiliaryResources定位，读取本清单的baselines条目，不要求使用者填写安装内部路径。原版Skill／命令和标准流程保持；本例不构成已完成的宿主生成测试。
+
+## 1. 先核对来源，再选择采用方式
+
+只在用户明确采用企业SOP或明确要求本项技术资料任务时使用。安装、出现PRD字样或发现本文件，不代表项目已启用企业SOP；标准任务继续使用原方法。
+
+先实际读取项目说明、明确提供的规范和已有采用记录；目录列表和自动上下文只能作线索。不扫描全部项目、宿主、历史样例或备份来猜规范。
+
+资源位置与项目规范来源分开判断：
+
+- 对本资源，实际读取本次选定目录的README、清单和所选模板；明确采用的项目自改副本优先，已选根不可读或损坏时报告缺项，不换发行原件或全局新版。
+- 对项目规范，优先复用项目已明确采用且适用的集团／平台／工程规范、CONSTRAINTS、ADR及正式契约。已有代码和锁文件提供实现事实，不自动成为替换规范的决定。
+- 用户本次明确材料与既有采用发生冲突时，同时保留并核对适用范围；本次提供文件不自动授权覆盖原规范、取消约束或切换全项目采用。
+- “规范未提供／未读取”与“项目确认没有规范”分开。不可读、无适用版本或存在冲突时，记录准确缺口及影响；不能从缺文件推断不存在。
+
+## 2. 路径一：已有适用规范
+
+1. 读已有规范及采用记录，固定可回读内容与本项目适用条款。可使用准确版本加固定提交、不可变快照或实际计算的摘要；未计算就明确说明。只有版本标签和可变链接不足以区分内容时，补固定依据。
+2. 用模板核对覆盖，沿用已有位置、身份和格式。内容已完整时，只在现有采用说明或本次唯一明确目标中记录引用及真实缺口；不复制全文、迁移文件或要求填一份同构大文档。
+3. 公共规则直接引用唯一权威。仅当实际存在项目特定约束时补充有来源的差异，注明维护位置和适用范围；有冲突先列Q，不悄悄覆盖。
+4. 记录本次AD如何引用这些规则的方式即可，不自动生成或修改AD。每份AD仍需自己的三图和完整工程设计。
+
+最小采用记录可以使用项目现有表格表达，无需新的registry：
+
+| 记录项 | 需要的实际内容 |
+| --- | --- |
+| 来源与固定内容 | 规范身份、权威位置、版本／固定提交或真实摘要、实际读取范围 |
+| 本次适用 | 项目／工程／主题范围、准确条款、实际采用依据；阅读不等于采用或批准 |
+| 落实与差异 | 项目补充或AD引用位置、例外及真实决定；无差异就直接引用 |
+| 项目本地修改 | 当前副本与发行来源分别记录；同名同版本改变后旧证据不自动沿用 |
+| 缺口与交接 | 未读、未知、冲突、需何答复、只影响哪些动作和独立可继续部分 |
+
+已有文件或人工修改先读并保留，不用发行摘要恢复项目副本。已有采用说明已足够时，可以只提出只读核对结果；是否写入及唯一目标由本次实际授权决定。
+
+## 3. 路径二：缺少规范时起草最小候选
+
+先确认已取得的项目事实与已查范围；未知保持Q。按模板涵盖共用架构、技术工程、身份安全、契约通则、共享数据、工程质量、交付恢复、维护例外八个领域。可以直接固定引用，不强制拆出八份文档或重复已有材料。
+
+沿用项目既有位置；没有约定时，可建议 `docs/engineering/{项目名称}-技术规约_v0.0.1.md` 作为共用辅助文档。建议路径不是已经存在、已采用或可覆盖的事实。核心业务文档的一能力一目录和主题命名保持。
+
+没有事实时，不默认框架、数据库、消息中间件、部署平台、权限、责任人、保留期限、质量数字或命令。项目已明确采用的公共平台约束应引用保留，准确版本和工程细节未取得时列Q，不重新选另一套默认。项目尚未建成时，命令、目录、风格示例和环境可以待定，不编造已运行证据。
+
+最小候选不要求全项目技术问题先清零。AD可先起草独立部分，原型按需并行；共同定义未决时，只限制依赖范围。交原Plan前补齐当前有效规格六项、依赖范围的共用定义和必要真实认可；Plan形成、获准逐任务Build及真实工程验收分别核对，不要求起草规范前已有构建通过。
+
+## 4. 规约、契约、AD与版本
+
+| 内容 | 唯一维护责任与交接 |
+| --- | --- |
+| 公共技术规约 | 维护共用原则或准确权威引用；不替代产品规则、CONSTRAINTS或ADR |
+| 正式接口／事件／数据定义 | 每项一个权威位置，字段与行为分担时明确范围；可先用提供方AD固定章节，不强制新协议或拆文件 |
+| 主题AD | 对应选定PRD完整设计，固定规范版本、条款、提供／消费契约及落实／例外；不包办另一主题PRD |
+| TestCase／实际报告 | 预期直接核PRD，技术判据核AD及契约；候选、真实执行和人工认可分开 |
+| 工程登记与锁 | 记录实际选择、正式采用、应用及验证事实；不另建架构权威或任务tracker |
+
+同一PBC多份主题PRD各自独立版本，每份配套逻辑AD及TestCase；文档不要求同号。规范版本、契约版本、代码／制品和环境分别固定。兼容核实际消费者、字段及语义、迁移和运行组合，不能靠版本号或Schema通过下结论。
+
+共享数据、状态及文件明确唯一逻辑维护责任与受控写入；前端、后端、Agent及jobs各自状态不能代替正式业务结果。具体角色、事务和数据保留必须有产品／规范依据。
+
+变更先固定旧／新内容及来源，定位直接和必要传递的契约、AD、AC、TestCase及真实任务，区分不受影响范围。人可人工修改、明确委托修订、有据不采纳或保持Q；不自动重写全项目、自动升版或承接旧批准。外部契约正式采用与模板实际应用并验证的锁分别留证，本作业不自动创建锁。
+
+## 5. 写入、审查与退出
+
+写前列明项目根、已读资料、已有规范／采用记录、固定来源、假设／Q、唯一目标和本次权限。先读现稿，保留人工内容和原报告；仅写明确获准目标，未知权限或覆盖风险时先说明。
+
+最后编辑后实际回读：新增要求逐条回查来源，规范与权限描述一致，逐表检查表头列数和列义。摘要、版本与内容相符，不要求文档写自身摘要。
+
+审查只标注问题、来源、位置、影响与建议，保留人工修改空间。只有真实独立新上下文才称独立审查，无隔离能力时提供新会话任务；自查不冒称独立。修订另行明确，不为清零代答业务或技术决定。
+
+完成后报告来源／目标、复用方式、补充与Q、实际验证和未执行事项，交人工审阅并停轮，不自动进入AD、Plan、Build、测试执行、提交或发布。
+
+## 6. 可复制任务说明
+
+可明确提供本资源目录或项目已采用副本，也可在明确企业任务后按[上层入口](../README.md)及其索引定位本辅助资源。源码登记不等于宿主自动发现，以下均为明确任务，没有新增slash命令。
+
+已有规范：
+
+```text
+本次只做公共技术规约采用核对。使用我明确提供的公共技术规约资源，先实际读取该目录README、清单和模板，再读取当前项目说明、已有规范及采用记录。
+优先复用项目已采用规范，固定来源、内容与适用条款；已有资料完整时只记录引用和真实缺口，不复制一份新规范，不覆盖原规范或人工修改。
+写前说明事实、假设、未读取项和唯一获准目标。位置按项目已有约定选择；若存在歧义或覆盖风险，先说明，不新建另一套registry。
+不把阅读当采用、把采用当批准；冲突按影响保留Q，不自行改选型或权限。最后回读候选，新增要求逐条回源，权限描述一致，表格逐行核列数与列义。完成后交我审阅并停轮。
+```
+
+新项目或资料不足：
+
+```text
+本次只起草项目公共技术规约候选。先读取我明确提供的资源README、清单、模板及当前项目资料，确认已有规范、已查范围和未取得内容；如果找到适用规范，优先采用它。
+确实缺少规范时，按模板只写当前有依据的最小候选，可用固定引用代替重复正文。框架、版本、责任、权限、质量数字、命令和运行结果没有来源就列Q，不填默认答案。
+沿用项目已有位置和命名，只写本次明确的唯一目标，保护人工内容。草拟不冒充可计划或获准Build；每份主题AD仍须三图及完整设计，原型按需。
+最后实际回读，逐条核新增要求来源、权限一致性及表格列数／列义，列出缺口和未执行事项，交我审阅并停轮。原版技能和命令不动，不写AD、Plan、工程或测试结果，不提交发布。
+```
+
+## 7. 资源范围与后续接入
+
+本子目录包含采用说明、通用模板、可选企业技术基线、其必要的定版目录依赖及局部清单。辅助manifest的entry、template、baselines[].path和files[].path均相对该manifest；基线requiredSources的path也相对同一manifest。来源追溯页不是额外业务阶段或统一必读业务输入。
+
+上层stages.json登记辅助资源根与清单，局部baselines条目列出可选规约的身份、版本和必要来源；不设置默认采用，不增加配置系统、审批字段或自动调度。清单的文件摘要固定发行资料，本轮变化检查不用于恢复或覆盖项目副本。
+
+B01—B05和原S10记录保留各自版本与验证范围。本次只整理分发资源及引用，打包／安装可读性另取新证据；静态、安装、真实模型行为、项目采用与正式发布分别判断。原型仍按需，TestCase不作为Plan统一必需输入，原Spec及Plan／Build停点不变。