@givolt/i3-composer-agent 3.0.0 → 3.2.1

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

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""Business-document SOP handoff for one EBC per project.
+
+Pass spec/handoff.json explicitly for new manifests; relative references use the project root.
+Never writes documents or approvals.
+"""
+import argparse
+import copy
+import json
+import os
+from pathlib import Path
+import tempfile
+import uuid
+
+VERSION = '0.4.0'
+GLOBAL_ROLES = {'brd'}
+TOPIC_ROLES = {'prd', 'ad', 'testCase'}
+DOCUMENT_ROLES = GLOBAL_ROLES | TOPIC_ROLES
+TOPIC_IDENTITY = ('pbcId', 'pbcName', 'prdId')
+
+
+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 _required_text(value, label):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(label + ' must be a nonempty string')
+    return value
+
+
+def _only_fields(value, allowed, label):
+    if not isinstance(value, dict):
+        raise ValueError(label + ' must be an object')
+    unexpected = set(value) - set(allowed)
+    if unexpected:
+        raise ValueError('unrecognized ' + label + ' fields; preserve the original and resolve their purpose: '
+                         + ', '.join(sorted(unexpected)))
+
+
+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')
+    _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')
+    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)
+        if not roles:
+            raise ValueError('topic must contain at least one selected PRD, AD or TestCase path')
+        for role in roles:
+            _required_text(topic[role], 'topic.' + role)
+    return value
+
+
+def _load(raw):
+    return _validate(json.loads(raw, object_pairs_hook=_unique, parse_constant=_nonstandard))
+
+
+def _selected_only(value):
+    """Validate the complete v2 record before any canonical write; never discard fields."""
+    _validate(value)
+    return {key: copy.deepcopy(value[key]) for key in ('schemaVersion', 'scope', 'selected')}
+
+
+def _check_scope(value, ebc_id, ebc_name):
+    if value['scope']['ebcId'] != ebc_id:
+        raise ValueError('manifest belongs to a different EBC scope')
+    if ebc_name is not None and _required_text(ebc_name, 'ebcName') != value['scope']['ebcName']:
+        raise ValueError('ebcName conflicts with the selected EBC; verify the document identity before updating')
+
+
+def _topic_name(selected, pbc_id, prd_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]
+    if pbc_name is None:
+        if not matches:
+            raise ValueError('new topic requires an explicit pbcName')
+        pbc_name = matches[0]['pbcName']
+    _required_text(pbc_name, 'pbcName')
+    if any(x['pbcId'] == pbc_id and x['pbcName'] != pbc_name for x in topics):
+        raise ValueError('pbcName conflicts with the selected PBC; verify the document identity before updating')
+    return pbc_name
+
+
+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, pbc_id=None, prd_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')
+    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 not resolved.is_file():
+        raise ValueError('reference missing or unreadable: ' + raw)
+    if not resolved.read_text(encoding='utf-8').strip():
+        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)
+    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 matches:
+            target = matches[0]
+        else:
+            target = {k: reference[k] for k in TOPIC_IDENTITY}
+            topics.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')
+    target[role] = path
+    return previous_path
+
+
+def _resolve(root, value, pbc_id, prd_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_name is not None:
+        _topic_name(selected, pbc_id, prd_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]
+    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']))
+    for reference in references:
+        path = Path(reference['path'])
+        reference['resolvedPath'] = str(path if path.is_absolute() else root / path)
+    result = {'ok': True, 'changed': False, 'source': 'manual' if manual else 'manifest',
+              'scope': copy.deepcopy(value['scope']), 'references': references,
+              '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}
+    return result
+
+
+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, *, ebc_id=None, ebc_name=None, role=None, path=None,
+            pbc_id=None, pbc_name=None, prd_id=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'}:
+        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())
+            _check_scope(value, ebc_id, ebc_name)
+        elif manual:
+            value = {'schemaVersion': 2,
+                     'scope': {'ebcId': ebc_id, 'ebcName': _required_text(ebc_name, 'ebcName')},
+                     'selected': {'topics': []}}
+        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
+    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': []}}
+        _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
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action', choices=['init', 'select', 'resolve'])
+    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('--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('--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)
+    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/read_text.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Return one bounded UTF-8 text page; use nextOffset unchanged for the next page."""
+import argparse
+import json
+from pathlib import Path
+
+
+def render(path, text, start, end):
+    return json.dumps({'path': str(path), 'offset': start, 'nextOffset': end,
+                       'eof': end == len(text), 'text': text[start:end]},
+                      ensure_ascii=False, separators=(',', ':'))
+
+
+def read_page(path, offset=0, max_chars=6000):
+    if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+        raise ValueError('offset must be a nonnegative integer')
+    if not isinstance(max_chars, int) or isinstance(max_chars, bool) or not 512 <= max_chars <= 10000:
+        raise ValueError('max-chars must be an integer from 512 to 10000')
+    source = Path(path).resolve(strict=True)
+    text = source.read_bytes().decode('utf-8')
+    if not text.strip():
+        raise ValueError('selected text file is empty')
+    if offset > len(text):
+        raise ValueError('offset is beyond the selected text; use the preceding nextOffset')
+    low, high = offset, min(len(text), offset + max_chars)
+    if len(render(source, text, offset, offset)) + 1 > max_chars:
+        raise ValueError('max-chars is too small for the path metadata')
+    while low < high:
+        end = (low + high + 1) // 2
+        if len(render(source, text, offset, end)) + 1 <= max_chars:
+            low = end
+        else:
+            high = end - 1
+    end = low
+    if end == offset and offset < len(text):
+        raise ValueError('max-chars leaves no room for text')
+    if end < len(text):
+        newline = text.rfind('\n', offset, end)
+        if newline >= offset:
+            end = newline + 1
+    return render(source, text, offset, end)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--path', required=True)
+    parser.add_argument('--offset', type=int, default=0, help='Character cursor returned by the preceding page; initial value 0')
+    parser.add_argument('--max-chars', type=int, default=6000, help='Maximum serialized page length, including metadata and trailing newline')
+    args = parser.parse_args()
+    try:
+        page = read_page(args.path, args.offset, args.max_chars)
+    except (OSError, ValueError, UnicodeError) as error:
+        print(json.dumps({'ok': False, 'error': str(error)}, ensure_ascii=False))
+        return 1
+    print(page)
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())