@event4u/agent-config 6.1.0 → 7.0.1

package/dist/agent-src/templates/scripts/work_engine/migration/v0_to_v1.py

@@ -1,231 +0,0 @@
-"""Migrate a v0 ``DeliveryState`` JSON file to the v1 schema.
-
-The v0 era used ``.implement-ticket-state.json`` and stored the ticket
-under a flat ``ticket`` key. v1 wraps the payload under ``input.kind``
-/ ``input.data`` and adds ``intent``, ``directive_set``, and
-``version``. The default destination is ``.work-state.json`` next to
-the v0 file; the v0 file is renamed to ``.implement-ticket-state.json.bak``
-to preserve the rollback surface.
-
-The module is both importable and runnable:
-
-    python3 -m work_engine.migration.v0_to_v1 .implement-ticket-state.json
-
-Idempotency: ``migrate_payload`` accepts a payload that already looks
-like v1 and returns it unchanged. ``migrate_file`` refuses to migrate
-twice — if the destination already exists it raises rather than
-silently overwriting work.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import shutil
-import sys
-from pathlib import Path
-from typing import Any, Sequence
-
-from ..state import (
-    DEFAULT_DIRECTIVE_SET,
-    DEFAULT_INTENT,
-    SCHEMA_VERSION,
-    SchemaError,
-)
-
-DEFAULT_V0_FILENAME = ".implement-ticket-state.json"
-"""Path the dispatcher used while the engine still lived under
-``implement_ticket``. The migration looks here when no source path is
-passed on the CLI."""
-
-DEFAULT_V1_FILENAME = ".work-state.json"
-"""Canonical filename for the v1 wire format."""
-
-BACKUP_SUFFIX = ".bak"
-"""Appended to the v0 source path when the migration archives it.
-
-If the ``.bak`` slot is already taken (re-running the migration after
-an aborted run, manual rollback, etc.) the rotator falls back to
-``.bak.1``, ``.bak.2``, ... — see :func:`_rotate_backup_path`. The
-migration never silently overwrites an existing backup."""
-
-_MAX_BACKUP_ROTATIONS = 999
-"""Hard ceiling on rotated backup filenames; surfaces an explicit
-:class:`SchemaError` instead of looping forever if a checkout has
-hundreds of stale backups."""
-
-
-def _rotate_backup_path(source: Path) -> Path:
-    """Return the next free ``.bak`` slot for ``source``.
-
-    Tries ``source.bak`` first, then ``source.bak.1``,
-    ``source.bak.2``, ... up to :data:`_MAX_BACKUP_ROTATIONS`. The
-    rotator only inspects existence — collision-safe by construction —
-    and never deletes or overwrites prior backups.
-    """
-    primary = source.with_suffix(source.suffix + BACKUP_SUFFIX)
-    if not primary.exists():
-        return primary
-    for index in range(1, _MAX_BACKUP_ROTATIONS + 1):
-        candidate = primary.with_suffix(primary.suffix + f".{index}")
-        if not candidate.exists():
-            return candidate
-    raise SchemaError(
-        f"refusing to rotate backup for {source}: more than "
-        f"{_MAX_BACKUP_ROTATIONS} stale .bak files already exist; "
-        "clean them up before re-running the migration",
-    )
-
-
-def migrate_payload(payload: Any) -> dict[str, Any]:
-    """Return the v1 form of ``payload``.
-
-    A payload that already declares ``version: 1`` is returned
-    unchanged (deep-copied via ``json.loads(json.dumps(...))`` so the
-    caller cannot accidentally mutate the input). Anything else is
-    treated as v0 and wrapped: ``ticket`` becomes ``input.data``,
-    ``input.kind`` is set to ``"ticket"``, and the engine defaults are
-    filled in.
-
-    Raises
-    ------
-    SchemaError
-        If the payload is not a dict, declares a higher version than
-        this migration knows about, or lacks a ``ticket`` key.
-    """
-    if not isinstance(payload, dict):
-        raise SchemaError(
-            f"v0 state must be a JSON object; got {type(payload).__name__}",
-        )
-
-    declared_version = payload.get("version")
-    if declared_version == SCHEMA_VERSION:
-        return json.loads(json.dumps(payload))
-    if declared_version is not None:
-        raise SchemaError(
-            f"cannot migrate from version {declared_version!r} to "
-            f"{SCHEMA_VERSION}; this script only handles v0 (no version key)",
-        )
-
-    if "ticket" not in payload:
-        raise SchemaError(
-            "v0 state must carry a 'ticket' key; got keys: "
-            f"{sorted(payload.keys())}",
-        )
-    ticket = payload["ticket"]
-    if not isinstance(ticket, dict):
-        raise SchemaError(
-            f"v0 state.ticket must be a JSON object; got {type(ticket).__name__}",
-        )
-
-    return {
-        "version": SCHEMA_VERSION,
-        "input": {"kind": "ticket", "data": ticket},
-        "intent": DEFAULT_INTENT,
-        "directive_set": DEFAULT_DIRECTIVE_SET,
-        "persona": payload.get("persona", "senior-engineer"),
-        "memory": list(payload.get("memory", [])),
-        "plan": payload.get("plan"),
-        "changes": list(payload.get("changes", [])),
-        "tests": payload.get("tests"),
-        "verify": payload.get("verify"),
-        "outcomes": dict(payload.get("outcomes", {})),
-        "questions": list(payload.get("questions", [])),
-        "report": payload.get("report", ""),
-    }
-
-
-def migrate_file(
-    source: Path,
-    *,
-    destination: Path | None = None,
-    backup: bool = True,
-) -> Path:
-    """Migrate the v0 state file at ``source`` and write the v1 result.
-
-    ``destination`` defaults to :data:`DEFAULT_V1_FILENAME` next to
-    ``source``. When ``backup`` is true (the default) the original
-    file is renamed with :data:`BACKUP_SUFFIX` appended; when false,
-    the original is left untouched. The destination must not exist —
-    refusing to overwrite is the safety net against accidental
-    double-migration on CI.
-
-    Returns the destination path on success.
-    """
-    if not source.is_file():
-        raise SchemaError(f"v0 state file not found: {source}")
-
-    raw = source.read_text(encoding="utf-8")
-    try:
-        payload = json.loads(raw)
-    except json.JSONDecodeError as exc:
-        raise SchemaError(f"invalid JSON in {source}: {exc}") from exc
-
-    target = destination or source.with_name(DEFAULT_V1_FILENAME)
-    if target.exists():
-        raise SchemaError(
-            f"refusing to overwrite existing destination {target}; "
-            "delete or rename it first",
-        )
-
-    migrated = migrate_payload(payload)
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(
-        json.dumps(migrated, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-
-    if backup:
-        backup_path = _rotate_backup_path(source)
-        shutil.move(str(source), str(backup_path))
-
-    return target
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    """CLI entry point — ``python3 -m work_engine.migration.v0_to_v1``.
-
-    Exits ``0`` on success, ``2`` on any :class:`SchemaError` so the
-    invoking shell can branch on the failure category.
-    """
-    parser = argparse.ArgumentParser(
-        prog="work_engine.migration.v0_to_v1",
-        description="Migrate a legacy .implement-ticket-state.json file to "
-        "the v1 .work-state.json schema.",
-    )
-    parser.add_argument(
-        "source",
-        type=Path,
-        nargs="?",
-        default=Path(DEFAULT_V0_FILENAME),
-        help=f"Path to the v0 state file (default: {DEFAULT_V0_FILENAME}).",
-    )
-    parser.add_argument(
-        "--destination",
-        type=Path,
-        default=None,
-        help="Path to write the v1 file to "
-        f"(default: {DEFAULT_V1_FILENAME} next to source).",
-    )
-    parser.add_argument(
-        "--no-backup",
-        action="store_true",
-        help="Do not rename the v0 source to .bak after migration.",
-    )
-    args = parser.parse_args(argv)
-
-    try:
-        target = migrate_file(
-            args.source,
-            destination=args.destination,
-            backup=not args.no_backup,
-        )
-    except SchemaError as exc:
-        print(f"error: {exc}", file=sys.stderr)
-        return 2
-
-    print(f"migrated {args.source} → {target}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/dist/agent-src/templates/scripts/work_engine/orchestration.py

@@ -1,193 +0,0 @@
-"""State machine stub for the ``/orchestrate`` command.
-
-Reads a pipeline file conforming to
-``docs/contracts/orchestration-dsl-v1.md`` and produces an ordered
-sequence of step descriptors the agent dispatches one at a time.
-The runtime itself is **not** in Python — each step is executed by the
-agent via skill / command / persona / subagent dispatch. This module
-holds the deterministic bookkeeping:
-
-- load + interpolate
-- step iteration with success / failure / when-guard tracking
-- output-map resolution at the end
-
-Design constraints (R1 carve-outs from
-``road-to-distribution-and-adoption.md``):
-
-- No external dependencies. YAML loading reuses the dispatcher's
-  loader so the runtime sees what the linter sees.
-- No side effects. The state machine never edits files, runs commands,
-  or emits hooks of its own. Audit emission is the caller's job.
-- Forward-ref free. ``steps[].with`` references can only reach
-  earlier steps; this is enforced both by the linter and at runtime.
-"""
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Iterator
-
-_INTERP_RE = re.compile(
-    r"\$\{\{\s*(inputs|steps)\.([a-z0-9_-]+)(?:\.output)?\s*\}\}"
-)
-
-
-@dataclass
-class StepResult:
-    """One step's record after dispatch."""
-    step_id: str
-    kind: str
-    ref: str
-    success: bool = False
-    output: str = ""
-    error: str | None = None
-
-
-@dataclass
-class PipelineState:
-    """Bookkeeping for a single ``/orchestrate`` run."""
-    name: str
-    inputs: dict[str, str]
-    results: dict[str, StepResult] = field(default_factory=dict)
-    halted: bool = False
-    halt_reason: str | None = None
-
-
-def _load_pipeline(path: Path) -> dict[str, Any]:
-    """Reuse the linter's loader so the runtime accepts the same shape.
-
-    Walks parents to find ``scripts/hooks/dispatch_hook.py`` so the
-    loader is reachable both when this module runs from the consumer
-    projection (``dist/agent-src/templates/scripts/work_engine/``) and
-    from the source-of-truth tree
-    (``packages/<pack>/.agent-src.uncondensed/templates/scripts/work_engine/``).
-    Loaded via ``importlib.util`` by file path to avoid namespace
-    collisions with test packages named ``hooks``.
-    """
-    import importlib.util
-    here = Path(__file__).resolve()
-    candidate: Path | None = None
-    # Layout-agnostic: the dispatcher sits at `scripts/hooks/` in a consumer
-    # install + the `dist/agent-src/` projection, and at `src/scripts/hooks/` in the
-    # maintainer source tree (6.0.0-D moved the tooling under `src/`). Probe both
-    # per parent so the loader resolves regardless of where this template runs.
-    rel_candidates = (
-        Path("scripts") / "hooks" / "dispatch_hook.py",
-        Path("src") / "scripts" / "hooks" / "dispatch_hook.py",
-    )
-    for parent in here.parents:
-        for rel in rel_candidates:
-            probe = parent / rel
-            if probe.is_file():
-                candidate = probe
-                break
-        if candidate is not None:
-            break
-    if candidate is None:
-        raise RuntimeError(
-            "could not locate scripts/hooks/dispatch_hook.py (or "
-            f"src/scripts/hooks/dispatch_hook.py) from {here}"
-        )
-    spec = importlib.util.spec_from_file_location(
-        "_work_engine_dispatch_hook", candidate
-    )
-    if spec is None or spec.loader is None:
-        raise RuntimeError(f"cannot load spec for {candidate}")
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    doc = module._load_yaml(path)
-    if not isinstance(doc, dict):
-        raise ValueError(f"{path}: top-level must be a mapping")
-    return doc
-
-
-def _interpolate(value: Any, state: PipelineState) -> Any:
-    """Substitute ``${{ inputs.X }}`` / ``${{ steps.Y.output }}`` in a
-    nested value. Unknown references raise — the linter should have
-    caught them, but the runtime double-checks."""
-    if isinstance(value, str):
-        def replace(match: re.Match[str]) -> str:
-            ns, ident = match.group(1), match.group(2)
-            if ns == "inputs":
-                if ident not in state.inputs:
-                    raise KeyError(f"unknown input '{ident}'")
-                return state.inputs[ident]
-            if ident not in state.results:
-                raise KeyError(f"unknown step '{ident}'")
-            return state.results[ident].output
-        return _INTERP_RE.sub(replace, value)
-    if isinstance(value, dict):
-        return {k: _interpolate(v, state) for k, v in value.items()}
-    if isinstance(value, list):
-        return [_interpolate(v, state) for v in value]
-    return value
-
-
-def _when_passes(when: str | None, state: PipelineState) -> bool:
-    """Evaluate the limited ``when`` mini-language. Supports
-    ``steps.X.success`` / ``steps.X.failure`` and equality on a
-    single ``${{ steps.X.output }}`` template against a literal."""
-    if not when:
-        return True
-    when = when.strip()
-    m = re.fullmatch(r"steps\.([a-z0-9_-]+)\.(success|failure)", when)
-    if m:
-        sid, kind = m.group(1), m.group(2)
-        if sid not in state.results:
-            return False
-        return state.results[sid].success if kind == "success" else not state.results[sid].success
-    m = re.fullmatch(r'\$\{\{\s*steps\.([a-z0-9_-]+)\.output\s*\}\}\s*==\s*"([^"]*)"', when)
-    if m:
-        sid, literal = m.group(1), m.group(2)
-        return state.results.get(sid, StepResult(sid, "", "")).output == literal
-    raise ValueError(f"unsupported when expression: {when!r}")
-
-
-def iter_steps(path: Path, inputs: dict[str, str]) -> Iterator[dict[str, Any]]:
-    """Yield interpolated step descriptors in order.
-
-    Caller dispatches each descriptor via skill / command / persona /
-    subagent and feeds the result back via :func:`record_result`.
-    """
-    doc = _load_pipeline(path)
-    merged_inputs = {
-        inp["id"]: inputs.get(inp["id"], inp.get("default", ""))
-        for inp in (doc.get("inputs") or [])
-        if isinstance(inp, dict) and isinstance(inp.get("id"), str)
-    }
-    state = PipelineState(name=doc.get("name", ""), inputs=merged_inputs)
-    for step in doc.get("steps") or []:
-        if state.halted:
-            break
-        if not _when_passes(step.get("when"), state):
-            continue
-        yield {
-            "id": step["id"],
-            "kind": step["kind"],
-            "ref": step["ref"],
-            "with": _interpolate(step.get("with") or {}, state),
-            "_state": state,
-        }
-
-
-def record_result(descriptor: dict[str, Any], *, success: bool, output: str = "", error: str | None = None) -> None:
-    """Caller hands the descriptor + outcome back so subsequent steps
-    can see ``${{ steps.<id>.output }}``."""
-    state: PipelineState = descriptor["_state"]
-    state.results[descriptor["id"]] = StepResult(
-        step_id=descriptor["id"], kind=descriptor["kind"], ref=descriptor["ref"],
-        success=success, output=output, error=error,
-    )
-    if not success:
-        state.halted = True
-        state.halt_reason = f"step {descriptor['id']} failed"
-
-
-def resolve_outputs(path: Path, state: PipelineState) -> dict[str, str]:
-    """Resolve the pipeline's ``outputs:`` map against the captured
-    step outputs. Returns an empty map if the pipeline declares no
-    outputs."""
-    doc = _load_pipeline(path)
-    raw = doc.get("outputs") or {}
-    return {k: _interpolate(v, state) for k, v in raw.items()}

package/dist/agent-src/templates/scripts/work_engine/persona_policy.py

@@ -1,85 +0,0 @@
-"""Persona policy — behavioural parameters resolved from ``state.persona``.
-
-Three personas ship today, each keyed by the string already carried
-on ``DeliveryState.persona`` (see
-``docs/contracts/implement-ticket-flow.md#personas``):
-
-``senior-engineer``
-    Default. Runs every step. No test widening.
-``qa``
-    Runs every step but widens the ``test`` scope to the full suite
-    (``scope=full`` in the ``run-tests`` directive) so regressions
-    outside the changed paths are caught.
-``advisory``
-    Plan-only mode. ``implement``, ``test``, and ``verify`` short-
-    circuit to SUCCESS without doing work — the flow produces a
-    delivery report whose value is the plan itself, and next-command
-    suggestions are suppressed (nothing was committed).
-
-Unknown persona names fall back to ``senior-engineer`` rather than
-raising, so a mistyped value never aborts a run mid-flight. The
-caller is responsible for validating the string at the state-
-construction boundary if strict behaviour is needed.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any
-
-DEFAULT_PERSONA = "senior-engineer"
-"""Name used when ``state.persona`` is empty or unrecognised."""
-
-
-@dataclass(frozen=True)
-class PersonaPolicy:
-    """Behavioural flags read by individual step handlers.
-
-    Frozen so a step cannot mutate the policy mid-run by accident —
-    policy is resolved once and treated as read-only configuration.
-    """
-
-    name: str
-    allows_implement: bool = True
-    allows_test: bool = True
-    allows_verify: bool = True
-    widen_tests: bool = False
-    suggests_next_commands: bool = True
-
-
-_POLICIES: dict[str, PersonaPolicy] = {
-    "senior-engineer": PersonaPolicy(name="senior-engineer"),
-    "qa": PersonaPolicy(name="qa", widen_tests=True),
-    "advisory": PersonaPolicy(
-        name="advisory",
-        allows_implement=False,
-        allows_test=False,
-        allows_verify=False,
-        suggests_next_commands=False,
-    ),
-}
-
-
-def resolve_policy(persona: Any) -> PersonaPolicy:
-    """Return the policy for ``persona``; fall back to the default on miss.
-
-    ``persona`` is typed ``Any`` because it originates from
-    ``DeliveryState.persona`` which the dataclass declares as ``str``
-    but does not enforce — a caller may set it to ``None`` while
-    wiring up a partial state in tests.
-    """
-    if isinstance(persona, str) and persona in _POLICIES:
-        return _POLICIES[persona]
-    return _POLICIES[DEFAULT_PERSONA]
-
-
-def known_personas() -> tuple[str, ...]:
-    """Return the persona names shipped today, in insertion order."""
-    return tuple(_POLICIES.keys())
-
-
-__all__ = [
-    "DEFAULT_PERSONA",
-    "PersonaPolicy",
-    "known_personas",
-    "resolve_policy",
-]

package/dist/agent-src/templates/scripts/work_engine/resolvers/__init__.py

@@ -1,22 +0,0 @@
-"""Input resolvers — turn raw user-supplied payloads into envelopes.
-
-A resolver wraps a typed source (a free-form prompt, a diff, a file
-reference) into the canonical :class:`work_engine.state.Input` shape so
-the dispatcher only ever speaks one schema. The R1 ticket flow does not
-need a resolver — ticket payloads arrive pre-structured from
-``/implement-ticket``; R2 introduces :mod:`.prompt`; R3 Phase 1 adds
-:mod:`.diff` and :mod:`.file` for the UI-improve track ("improve this
-screen via diff/PR" and "improve this existing component/page").
-
-Resolvers are deliberately thin: they normalize, they do not interpret.
-Reconstruction of acceptance criteria + assumptions + confidence is the
-job of the ``refine-prompt`` skill (R2 Phase 3) called from the
-``refine`` step, not the resolver. Keeping the split sharp means the
-envelope shape stays cheap to round-trip through state and the heavy
-lifting stays with the agent-directive halt where it belongs.
-"""
-from __future__ import annotations
-
-from . import diff, file, prompt
-
-__all__ = ["diff", "file", "prompt"]

package/dist/agent-src/templates/scripts/work_engine/resolvers/diff.py

@@ -1,106 +0,0 @@
-"""Diff resolver — wrap a unified-diff payload as an :class:`Input` envelope.
-
-The resolver is the R3 Phase 1 entry point for the "improve this screen via
-diff/PR" surface: a user (or `/work` adapter) hands the engine a patch text,
-the resolver normalises it, and the dispatcher routes it through the UI-track
-``ui-improve`` directive set.
-
-Like :mod:`work_engine.resolvers.prompt`, this module is intentionally thin:
-it normalises and rejects garbage payloads, nothing more. Reconstruction of
-acceptance criteria + assumptions + confidence is the job of the
-``refine-prompt`` skill (R2 Phase 3) running against the diff once the engine
-hits the ``refine`` step. Keeping the split sharp means the envelope shape
-stays cheap to round-trip through state and the heavy lifting stays with the
-agent-directive halt where it belongs.
-
-The envelope mirrors the prompt resolver's shape so a single refiner code
-path can read both — ``{raw, reconstructed_ac, assumptions}``. The only
-material difference is the heuristic header check that rejects payloads
-that obviously are not unified-diff text.
-"""
-from __future__ import annotations
-
-import re
-
-from ..state import Input
-
-KIND = "diff"
-"""Wire value carried in :attr:`work_engine.state.Input.kind`."""
-
-_MIN_DIFF_LEN = 1
-"""Minimum non-whitespace character count before the heuristic runs.
-
-The resolver is not a *quality* gate; it only rejects literally empty payloads
-and obvious non-diffs. A semantically empty diff (e.g., headers but no hunks)
-is still accepted so the refiner can score its tractability and surface a
-``low``-band halt where appropriate."""
-
-_DIFF_MARKERS = (
-    re.compile(r"^diff --git ", re.MULTILINE),
-    re.compile(r"^--- ", re.MULTILINE),
-    re.compile(r"^\+\+\+ ", re.MULTILINE),
-    re.compile(r"^@@ ", re.MULTILINE),
-    re.compile(r"^Index: ", re.MULTILINE),
-)
-"""Heuristic markers that flag a payload as a unified or git-style diff.
-
-A payload qualifies if **any** marker matches — the resolver accepts unified
-diffs (``--- ``/``+++ ``/``@@ ``), ``git diff`` output (``diff --git``), and
-the legacy ``Index: `` SVN/CVS header. The match is anchored at line start so
-quoted snippets inside prose ("the function `--- foo` failed") do not pass
-the gate."""
-
-
-class DiffResolverError(ValueError):
-    """Raised when a payload cannot be resolved into a diff envelope."""
-
-
-def build_envelope(raw: str) -> Input:
-    """Return an :class:`Input` carrying the raw diff + empty refinement slots.
-
-    Parameters
-    ----------
-    raw:
-        The user-supplied diff text. Whitespace is preserved verbatim — the
-        refiner reads original spacing/casing when scoring goal clarity, and
-        a unified-diff round-trip cannot tolerate normalised whitespace.
-
-    Returns
-    -------
-    Input
-        Envelope of shape
-        ``{"kind": "diff", "data": {"raw": <raw>, "reconstructed_ac": [],
-        "assumptions": []}}``. The two empty lists are placeholders the
-        ``refine-prompt`` skill writes into on the rebound from ``refine``.
-
-    Raises
-    ------
-    DiffResolverError
-        If ``raw`` is not a string, contains no non-whitespace characters,
-        or does not match any :data:`_DIFF_MARKERS`. The marker check guards
-        against accidentally routing free-form prose through the diff path.
-    """
-    if not isinstance(raw, str):
-        raise DiffResolverError(
-            f"diff must be a string; got {type(raw).__name__}",
-        )
-    if len(raw.strip()) < _MIN_DIFF_LEN:
-        raise DiffResolverError(
-            "diff is empty or whitespace-only — nothing to resolve",
-        )
-    if not any(marker.search(raw) for marker in _DIFF_MARKERS):
-        raise DiffResolverError(
-            "payload does not look like a unified diff — expected one of "
-            "'diff --git', '--- ', '+++ ', '@@ ', or 'Index: ' headers",
-        )
-    return Input(
-        kind=KIND,
-        data={
-            "raw": raw,
-            "reconstructed_ac": [],
-            "assumptions": [],
-        },
-    )
-
-
-__all__ = ["KIND", "DiffResolverError", "build_envelope"]