@givolt/i3-composer-agent 2.3.7 → 3.0.0

package/references/enterprise-sop-resources/verification/check_reads.py

@@ -0,0 +1,348 @@
+"""Read-only checker for CodeBuddy stream-json evidence. No project or report writes."""
+import json,re
+from pathlib import Path
+
+def assess(project_root, scope, events):
+    root=Path(project_root).resolve()
+    def relative(raw):
+        p=Path(raw);p=(p if p.is_absolute() else root/p).resolve()
+        return str(p.relative_to(root)) if p.is_relative_to(root) else str(p)
+    calls=[];results={};finals=[]
+    for seq,event in enumerate(events):
+        if event.get('type')=='result':finals.append(event)
+        message=event.get('message',{})
+        if not isinstance(message,dict):continue
+        for block in message.get('content',[]):
+            if not isinstance(block,dict):continue
+            if event.get('type')=='assistant' and block.get('type')=='tool_use':
+                calls.append({**block,'event':seq})
+            if event.get('type')=='user' and block.get('type')=='tool_result':
+                results[block['tool_use_id']]={**block,'receiptEvent':seq}
+    reads=[];writes=[];errors=[]
+    for call in calls:
+        inp=call.get('input',{});result=results.get(call['id'])
+        raw=inp.get('file_path') or inp.get('path')
+        path=relative(raw) if raw else None
+        success=result is not None and not result.get('is_error',False)
+        item={'tool':call['name'],'path':path,'event':call['event'],
+              'receiptEvent':result['receiptEvent'] if result else float('inf'),'successful':success}
+        if call['name']=='Read':
+            data=result.get('content',[]) if result else []
+            text=data if isinstance(data,str) else '\n'.join(x.get('text','') for x in data if isinstance(x,dict))
+            reads.append({**item,'lines':[int(n) for n in re.findall(r'^\s*(\d+)→',text,re.M)]})
+        elif call['name'] in ['Write','Edit','Bash','PowerShell','NotebookEdit','Skill','Task','Agent']:
+            writes.append(item)
+        if result and result.get('is_error'):errors.append(item)
+    allowed={relative(p) for p in scope.get('allowedWrites',[])}
+    first_write=min((x['event'] for x in writes if x['successful']),default=float('inf'))
+    coverage=[]
+    for raw in scope['requiredReads']:
+        path=relative(raw);p=root/path
+        count=scope.get('beforeLineCounts',{}).get(raw)
+        if count is None:count=len(p.read_text().splitlines()) if p.is_file() else None
+        observed=[x for x in reads if x['path']==path and x['successful'] and x['receiptEvent']<first_write]
+        lines={n for x in observed for n in x['lines']}
+        full=count is not None and bool(observed) and all(n in lines for n in range(1,count+1))
+        coverage.append({'path':path,'exists':p.is_file(),'expectedLines':count,'successfulRead':bool(observed),'fullRead':full})
+    missing=[x['path'] for x in coverage if not x['successfulRead']]
+    partial=[x['path'] for x in coverage if x['successfulRead'] and not x['fullRead']]
+    explicit_external={relative(p) for p in scope['requiredReads'] if Path(relative(p)).is_absolute()}
+    forbidden=[]
+    for read in reads:
+        p=read['path']
+        if read['successful'] and ((Path(p).is_absolute() and p not in explicit_external) or any(p==relative(x) or p.startswith(relative(x).rstrip('/')+'/') for x in scope.get('forbiddenAccessPrefixes',[]))):forbidden.append(p)
+    targets=[]
+    for path in sorted(allowed):
+        p=root/path;changes=[x for x in writes if x['path']==path and x['successful'] and x['tool'] in ['Write','Edit']]
+        last=max((x['receiptEvent'] for x in changes),default=float('inf'))
+        final_reads=[x for x in reads if x['path']==path and x['successful'] and x['event']>last and x['receiptEvent']>last]
+        count=len(p.read_text().splitlines()) if p.is_file() else None
+        lines={n for x in final_reads for n in x['lines']}
+        full=bool(changes and final_reads) and count is not None and all(n in lines for n in range(1,count+1))
+        targets.append({'path':path,'lastWriteEvent':last if changes else None,'finalLines':count,'fullReadAfterLastEdit':full})
+    failures=[]
+    if not finals or finals[-1].get('is_error',False):failures.append('native_final_not_proven')
+    if missing:failures.append('required_read_missing')
+    if partial:failures.append('required_read_incomplete')
+    if forbidden:failures.append('forbidden_source_read')
+    if any(x['tool'] not in ['Write','Edit'] or x['path'] not in allowed for x in writes):failures.append('tool_or_write_boundary')
+    if any(not x['fullReadAfterLastEdit'] for x in targets):failures.append('final_full_read_incomplete')
+    return {'format':'i3-read-evidence/v1','passed':not failures,'failures':failures,'requiredReadCoverage':coverage,
+            'missingReads':missing,'partialReads':partial,'forbiddenReads':sorted(set(forbidden)),'targetChecks':targets,
+            'observedReads':reads,'observedWrites':writes,'toolErrors':errors,
+            'proofScope':'actual native reads and final read coverage only; not semantic correctness, approval or runtime interception'}
+
+def _schema_errors(value, node, schema, location='$'):
+    """Validate only the keywords used by our bundled contract, without dependencies.
+
+    This is not a general JSON Schema engine. Unknown keywords fail closed.
+    """
+    supported = {'$schema', '$id', 'title', 'description', 'type', 'required', 'properties',
+                 'additionalProperties', 'items', 'minItems', 'minimum', 'minLength',
+                 'enum', '$ref', '$defs'}
+    if set(node) - supported:
+        raise ValueError('unsupported bundled schema keyword at ' + location)
+    if '$ref' in node:
+        prefix = '#/$defs/'
+        ref = node['$ref']
+        if not ref.startswith(prefix):
+            raise ValueError('only bundled local schema references are supported')
+        return _schema_errors(value, schema['$defs'][ref[len(prefix):]], schema, location)
+    types = {'object': lambda x: isinstance(x, dict), 'array': lambda x: isinstance(x, list),
+             'string': lambda x: isinstance(x, str), 'integer': lambda x: type(x) is int}
+    kind = node.get('type')
+    if kind and (kind not in types or not types[kind](value)):
+        return [location + ': expected ' + str(kind)]
+    errors = []
+    if 'enum' in node and value not in node['enum']:
+        errors.append(location + ': value outside enum')
+    if kind == 'object':
+        properties = node.get('properties', {})
+        errors += [location + '.' + key + ': missing' for key in node.get('required', []) if key not in value]
+        if node.get('additionalProperties') is False:
+            errors += [location + '.' + key + ': unknown field' for key in value if key not in properties]
+        for key in value.keys() & properties.keys():
+            errors += _schema_errors(value[key], properties[key], schema, location + '.' + key)
+    elif kind == 'array':
+        if len(value) < node.get('minItems', 0):
+            errors.append(location + ': too few items')
+        for index, item in enumerate(value):
+            errors += _schema_errors(item, node.get('items', {}), schema, f'{location}[{index}]')
+    elif kind == 'string' and len(value.strip()) < node.get('minLength', 0):
+        errors.append(location + ': empty string')
+    elif kind == 'integer' and value < node.get('minimum', value):
+        errors.append(location + ': below minimum')
+    return errors
+
+
+def _source_role_bindings(scope):
+    """One caller-owned role table for both schema generation and evidence checks."""
+    if not isinstance(scope, dict):
+        raise ValueError('review scope must be an object')
+    roles = scope.get('sourceRoles', {})
+    required = scope.get('requiredSourceRoles', [])
+    if (not isinstance(roles, dict)
+            or not all(isinstance(k, str) and isinstance(v, str) and k.strip() and v.strip() for k, v in roles.items())
+            or not isinstance(required, list)
+            or any(not isinstance(k, str) or k not in roles for k in required)):
+        raise ValueError('sourceRoles/requiredSourceRoles must be explicit caller bindings')
+    return dict(roles), list(required)
+
+
+def build_review_schema(scope):
+    """Build a fresh CLI-compatible job schema from the bundled schema and scope.
+
+    Role enums are bound before generation. No project, scope or report writes.
+    The evidence validator uses the same _source_role_bindings function.
+    """
+    roles, _ = _source_role_bindings(scope)
+    schema = json.loads(Path(__file__).with_name('review-output.schema.json').read_text())
+    properties = schema['$defs']['reference']['properties']
+    if roles:
+        properties['role']['enum'] = sorted(roles)
+    else:
+        properties.pop('role', None)
+
+    def inline(node):
+        if isinstance(node, list):
+            return [inline(x) for x in node]
+        if not isinstance(node, dict):
+            return node
+        if '$ref' in node:
+            prefix = '#/$defs/'
+            if not node['$ref'].startswith(prefix):
+                raise ValueError('only bundled local schema references are supported')
+            return inline(schema['$defs'][node['$ref'][len(prefix):]])
+        return {k: inline(v) for k, v in node.items() if k not in ['$defs', '$schema', '$id']}
+    return inline(schema)
+
+
+def _unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError('duplicate JSON key: ' + key)
+        result[key] = value
+    return result
+
+
+def _invalid_constant(value):
+    raise ValueError('nonstandard JSON constant: ' + value)
+
+
+def check_review(project_root, events, assessment, scope=None):
+    scope = scope or {}
+    issues, checked = [], []
+    def fail(code, detail):
+        issues.append({'code': code, 'detail': detail})
+    def result(**extra):
+        return {'passed': not issues, 'errors': [x['detail'] for x in issues],
+                'errorCodes': sorted({x['code'] for x in issues}), 'issues': issues,
+                'quotes': checked, 'contract': 'i3-enterprise-sop-review-output/v1', **extra}
+    finals = [x for x in events if x.get('type') == 'result']
+    text = finals[-1].get('result', '') if finals else ''
+    carrier = scope.get('reviewCarrier', 'text')
+    if carrier not in ['text', 'structured_output']:
+        fail('review_carrier_invalid', 'unsupported explicitly selected review carrier')
+        return result()
+    if carrier == 'structured_output':
+        if not finals or 'structured_output' not in finals[-1]:
+            fail('review_output_missing', 'requested native structured_output missing; no text fallback')
+            return result()
+        payload = finals[-1]['structured_output']
+        calls, successful = {}, set()
+        for event in events:
+            message = event.get('message', {})
+            content = message.get('content', []) if isinstance(message, dict) else []
+            if not isinstance(content, list):
+                continue
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                if block.get('type') == 'tool_use' and block.get('name') == 'StructuredOutput':
+                    calls[block.get('id')] = block.get('input')
+                elif block.get('type') == 'tool_result' and not block.get('is_error', False):
+                    successful.add(block.get('tool_use_id'))
+        if not any(tool_id in successful and value == payload for tool_id, value in calls.items()):
+            fail('review_structured_output_unproven', 'no matching successful native StructuredOutput tool/result pair')
+            return result()
+        try:
+            raw = json.dumps(payload, ensure_ascii=False, allow_nan=False)
+        except (ValueError, TypeError) as error:
+            fail('review_json_invalid', str(error))
+            return result()
+    else:
+        if not isinstance(text, str) or not text.strip():
+            fail('review_output_missing', 'native final report text missing')
+            return result()
+        blocks = re.findall(r'```json[ \t]*\r?\n(.*?)\r?\n```', text, re.S)
+        if len(blocks) > 1:
+            fail('review_json_ambiguous', 'expected one JSON object, found multiple JSON blocks')
+            return result()
+        raw = blocks[0] if blocks else text.strip()
+    try:
+        report = json.loads(raw, object_pairs_hook=_unique_object, parse_constant=_invalid_constant)
+    except (ValueError, TypeError) as error:
+        fail('review_json_invalid', str(error))
+        return result(parseError={'message': str(error), 'line': getattr(error, 'lineno', None),
+                                  'column': getattr(error, 'colno', None), 'position': getattr(error, 'pos', None)})
+    checked_report = check_report(project_root, report, assessment, scope)
+    checked_report['carrier'] = carrier
+    checked_report['nativeCarrierProven'] = carrier == 'structured_output'
+    return checked_report
+
+
+def check_report(project_root, report, assessment, scope=None):
+    """Check report content against source/read evidence; no native-origin claim.
+
+    The caller must record the origin of a separately corrected report. Calling
+    this function does not turn that report into a new native model result.
+    """
+    root = Path(project_root).resolve()
+    scope = scope or {}
+    carrier = 'report-object'
+    issues, checked = [], []
+    def fail(code, detail):
+        issues.append({'code': code, 'detail': detail})
+    def result(**extra):
+        return {'passed': not issues, 'errors': [x['detail'] for x in issues],
+                'errorCodes': sorted({x['code'] for x in issues}), 'issues': issues,
+                'quotes': checked, 'contract': 'i3-enterprise-sop-review-output/v1', **extra}
+    try:
+        schema = json.loads(Path(__file__).with_name('review-output.schema.json').read_text())
+        schema_errors = _schema_errors(report, schema, schema)
+    except (ValueError, KeyError, OSError) as error:
+        fail('review_contract_invalid', str(error))
+        return result()
+    if not schema_errors:
+        for group in ['findings', 'checkedFacts']:
+            ids = [x['id'] for x in report[group]]
+            if len(ids) != len(set(ids)):
+                schema_errors.append(group + ': duplicate stable ID')
+    if schema_errors:
+        for error in schema_errors:
+            fail('review_schema_invalid', error)
+        return result()
+
+    def relative(raw_path):
+        p = Path(raw_path)
+        p = (p if p.is_absolute() else root / p).resolve()
+        return str(p.relative_to(root)) if p.is_relative_to(root) else str(p)
+    try:
+        roles, required_roles = _source_role_bindings(scope)
+    except ValueError as error:
+        fail('review_role_scope_invalid', str(error))
+        return result()
+    roles = {name: relative(path) for name, path in roles.items()}
+    read_lines = {}
+    for item in assessment['observedReads']:
+        if item['successful']:
+            read_lines.setdefault(item['path'], set()).update(item['lines'])
+    proven_roles = set()
+    for group in ['findings', 'checkedFacts']:
+        for index, item in enumerate(report[group]):
+            for side in ['target', 'source']:
+                ref = item[side]
+                label = f'{group}[{index}].{side}'
+                path = relative(ref['path'])
+                start, end = ref['startLine'], ref.get('endLine', ref['startLine'])
+                bound_role = ref.get('role')
+                role_matches = bound_role is None
+                if bound_role is not None:
+                    if bound_role not in roles:
+                        fail('review_source_role_unbound', label + ': unbound role ' + bound_role)
+                    elif roles[bound_role] != path:
+                        fail('review_source_role_mismatch', label + ': role does not match caller-bound path')
+                    else:
+                        role_matches = True
+                observed = start <= end and all(n in read_lines.get(path, set()) for n in range(start, end + 1))
+                quote_matches = False
+                if start > end:
+                    fail('review_reference_range_invalid', label + ': endLine precedes startLine')
+                else:
+                    # Do not open an arbitrary external path merely because the model cites it.
+                    p = root / path
+                    explicit_external = {relative(x) for x in scope.get('requiredReads', [])}
+                    permitted = p.is_relative_to(root) or path in explicit_external
+                    try:
+                        lines = p.read_text().splitlines() if permitted and p.is_file() else []
+                        quote_matches = end <= len(lines) and ref['quote'] in '\n'.join(lines[start-1:end])
+                    except (OSError, UnicodeError):
+                        pass
+                    if not quote_matches:
+                        fail('review_quote_mismatch', label + ': quote does not match referenced current file/lines')
+                if not observed:
+                    fail('review_reference_not_read', label + ': cited lines lack successful native Read evidence')
+                if bound_role and role_matches and observed and quote_matches:
+                    proven_roles.add(bound_role)
+                checked.append({'group': group, 'index': index, 'role': side, 'path': path,
+                                'sourceRole': bound_role, 'quoteMatches': quote_matches,
+                                'citedLinesActuallyRead': observed, 'sourceRoleMatches': role_matches})
+    for name in required_roles:
+        if name not in proven_roles:
+            fail('review_source_role_missing', 'required role lacks proven reference: ' + name)
+    return result(verdict=report['verdict'], carrier=carrier, sourceRoleEvidence=sorted(proven_roles),
+                  scope='structure, exact quotes, actual Read ranges and caller-bound roles only; not semantic correctness or approval')
+
+def main():
+    import argparse,sys
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--project-root',required=True)
+    parser.add_argument('--scope',required=True,help='Verification scope only; not business handoff.json')
+    parser.add_argument('--trace',required=True,help='CodeBuddy stream-json trace')
+    parser.add_argument('--review-quotes',action='store_true')
+    args=parser.parse_args()
+    try:
+        scope=json.loads(Path(args.scope).read_text())
+        events=[json.loads(line) for line in Path(args.trace).read_text().splitlines() if line.strip()]
+        if not isinstance(scope.get('requiredReads'),list):raise ValueError('scope.requiredReads must be a list')
+        result=assess(args.project_root,scope,events)
+        if args.review_quotes:
+            quote_check=check_review(args.project_root,events,result,scope);result['reviewQuoteCheck']=quote_check
+            if not quote_check['passed']:result['failures'].extend(quote_check['errorCodes']);result['passed']=False
+    except (ValueError,KeyError,TypeError,OSError,UnicodeError) as error:
+        result={'format':'i3-read-evidence/v1','passed':False,'failures':['invalid_or_unsupported_evidence'],'detail':str(error)}
+    print(json.dumps(result,ensure_ascii=False,indent=2))
+    return 0 if result['passed'] else 1
+
+if __name__=='__main__':raise SystemExit(main())

package/references/enterprise-sop-resources/verification/review-output.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:i3:i3-enterprise-sop:review-output:v1",
+  "title": "企业 SOP 只读文档审查会话输出 v1",
+  "description": "只约束审查报告结构；不是业务 handoff.json、批准或测试结果。",
+  "type": "object",
+  "required": [
+    "verdict",
+    "findings",
+    "checkedFacts",
+    "unread"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "verdict": {
+      "type": "string",
+      "enum": [
+        "交人工审阅",
+        "可交人工审阅",
+        "需修订",
+        "无法判断"
+      ]
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/finding"
+      }
+    },
+    "checkedFacts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/fact"
+      }
+    },
+    "unread": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "$defs": {
+    "reference": {
+      "type": "object",
+      "required": [
+        "path",
+        "startLine",
+        "quote"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "quote": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1,
+          "description": "可选的机器来源标识。实际作业必须由build_review_schema(scope)注入sourceRoles键的枚举；普通资料引用省略role，资料性质写入reason或conclusion。"
+        }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": [
+        "id",
+        "severity",
+        "target",
+        "source",
+        "reason",
+        "suggestion"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "severity": {
+          "type": "string",
+          "enum": [
+            "low",
+            "medium",
+            "high",
+            "critical"
+          ]
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "contradiction",
+            "evidence-gap",
+            "clarification",
+            "optional"
+          ]
+        },
+        "target": {
+          "$ref": "#/$defs/reference"
+        },
+        "source": {
+          "$ref": "#/$defs/reference"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "suggestion": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "fact": {
+      "type": "object",
+      "required": [
+        "id",
+        "target",
+        "source",
+        "conclusion"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "target": {
+          "$ref": "#/$defs/reference"
+        },
+        "source": {
+          "$ref": "#/$defs/reference"
+        },
+        "conclusion": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}