@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/templates/scripts/work_engine/state_io.py

@@ -0,0 +1,202 @@
+"""State-file I/O helpers for the CLI entry point.
+
+Extracted from ``cli.py`` in P2.3 of
+``road-to-post-pr29-optimize.md``. Holds the format-preserving
+load/save pair, the v0 legacy serialiser, the JSON reader, the
+``DeliveryState`` projection helpers, and the legacy-file migration
+hint. Behaviour is byte-identical to the pre-split version — Goldens
+stay green.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import state as _state_module
+from .cli_args import DEFAULT_STATE_FILE, LEGACY_STATE_FILE, _FMT_V0, _FMT_V1
+from .delivery_state import DeliveryState
+from .errors import _CLIError
+from .migration.v0_to_v1 import migrate_payload
+from .state import SchemaError, WorkState
+
+
+def _maybe_raise_legacy_hint(state_file: Path) -> None:
+    """Surface a migration hint when only the pre-1.15.0 file is present.
+
+    The dispatcher renamed the default state file from
+    ``.implement-ticket-state.json`` to ``.work-state.json`` in 1.15.0
+    (alongside the ``implement_ticket → work_engine`` package move).
+    Existing checkouts that still carry the legacy file would otherwise
+    fail with a generic "no state file" message. This helper detects
+    the legacy file in the same directory and points the user at the
+    one-shot migration command instead.
+
+    Only fires when ``state_file`` has the canonical default name and
+    sits next to a legacy file — explicit ``--state-file`` overrides
+    bypass the hint so power users can carry their own naming scheme.
+    """
+    if state_file.name != DEFAULT_STATE_FILE.name:
+        return
+    legacy_candidate = state_file.with_name(LEGACY_STATE_FILE.name)
+    if not legacy_candidate.is_file():
+        return
+    raise _CLIError(
+        f"Found legacy state file {legacy_candidate} but no "
+        f"{state_file}. The default state file was renamed in 1.15.0. "
+        f"Run `python3 -m work_engine.migration.v0_to_v1 "
+        f"{legacy_candidate}` to migrate, or pass `--state-file "
+        f"{legacy_candidate}` to keep using the old name. See "
+        "docs/MIGRATION.md.",
+    )
+
+
+def _load(state_file: Path) -> tuple[WorkState, str]:
+    """Load ``state_file`` and tag it with the wire format detected."""
+    data = _read_json(state_file)
+    if not isinstance(data, dict):
+        raise _CLIError(
+            f"State file {state_file} must carry a JSON object; "
+            f"got {type(data).__name__}.",
+        )
+
+    # v1 declares ``version``; v0 has none. Anything else is invalid.
+    if data.get("version") == _state_module.SCHEMA_VERSION:
+        try:
+            return _state_module.from_dict(data), _FMT_V1
+        except SchemaError as exc:
+            raise _CLIError(f"State file shape is invalid: {exc}") from exc
+    if "version" in data:
+        raise _CLIError(
+            f"State file shape is invalid: unsupported version "
+            f"{data.get('version')!r}; expected {_state_module.SCHEMA_VERSION}",
+        )
+    if "ticket" not in data:
+        raise _CLIError(
+            "State file shape is invalid: missing 'ticket' (v0) or "
+            "'version' (v1) — file is neither shape.",
+        )
+    try:
+        migrated = migrate_payload(data)
+        return _state_module.from_dict(migrated), _FMT_V0
+    except SchemaError as exc:
+        raise _CLIError(f"State file shape is invalid: {exc}") from exc
+
+
+def _to_delivery(work: WorkState) -> DeliveryState:
+    """Project ``work`` into a ``DeliveryState`` for handler dispatch.
+
+    R1 P4 S1 (Option A2): handlers continue to consume ``DeliveryState``
+    with ``state.ticket``; the ``WorkState`` wrapper exists at the CLI
+    boundary so the dispatcher's directive-set selection has a v1
+    state object to read ``directive_set`` from. Mutable containers
+    (``memory``, ``changes``, ``outcomes``, ``questions``) are passed
+    by reference — in-place mutations land on both objects without an
+    explicit sync. Reassignments (``state.plan = …``, ``state.report
+    = …``) are mirrored back by :func:`_sync_back`.
+    """
+    return DeliveryState(
+        ticket=work.input.data,
+        persona=work.persona,
+        memory=work.memory,
+        plan=work.plan,
+        changes=work.changes,
+        tests=work.tests,
+        verify=work.verify,
+        outcomes=work.outcomes,
+        questions=work.questions,
+        report=work.report,
+        ui_audit=work.ui_audit,
+        ui_design=work.ui_design,
+        ui_review=work.ui_review,
+        ui_polish=work.ui_polish,
+        contract=work.contract,
+        stitch=work.stitch,
+        stack=work.stack,
+    )
+
+
+def _sync_back(work: WorkState, delivery: DeliveryState) -> None:
+    """Mirror handler mutations from ``delivery`` back into ``work``.
+
+    Container fields are shared by reference (see :func:`_to_delivery`)
+    so the assignment is a no-op for those — we still mirror them
+    defensively to cover the case where a handler reassigned the
+    attribute (``state.memory = [new_list]``) instead of mutating in
+    place.
+    """
+    work.input.data = delivery.ticket
+    work.persona = delivery.persona
+    work.memory = delivery.memory
+    work.plan = delivery.plan
+    work.changes = delivery.changes
+    work.tests = delivery.tests
+    work.verify = delivery.verify
+    work.outcomes = delivery.outcomes
+    work.questions = delivery.questions
+    work.report = delivery.report
+    work.ui_audit = delivery.ui_audit
+    work.ui_design = delivery.ui_design
+    work.ui_review = delivery.ui_review
+    work.ui_polish = delivery.ui_polish
+    work.contract = delivery.contract
+    work.stitch = delivery.stitch
+    work.stack = delivery.stack
+
+
+def _save(state_file: Path, work: WorkState, fmt: str) -> None:
+    """Persist ``work`` in the wire format it was loaded with.
+
+    v1 emits the canonical envelope via :func:`work_engine.state.to_dict`;
+    v0 emits the legacy flat shape that ``DeliveryState.asdict`` used
+    to produce, byte-identical to the pre-Phase-4 output so the
+    Golden Transcript replay stays green.
+    """
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    payload = _state_module.to_dict(work) if fmt == _FMT_V1 else _to_v0_dict(work)
+    state_file.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _to_v0_dict(work: WorkState) -> dict[str, Any]:
+    """Serialise ``work`` in the legacy v0 wire format.
+
+    Field order matches ``DeliveryState`` declaration order so
+    pre-Phase-4 state files round-trip byte-equal.
+    """
+    return {
+        "ticket": work.input.data,
+        "persona": work.persona,
+        "memory": work.memory,
+        "plan": work.plan,
+        "changes": work.changes,
+        "tests": work.tests,
+        "verify": work.verify,
+        "outcomes": work.outcomes,
+        "questions": work.questions,
+        "report": work.report,
+    }
+
+
+def _read_json(path: Path):
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise _CLIError(f"Cannot read {path}: {exc}") from exc
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise _CLIError(f"Invalid JSON in {path}: {exc}") from exc
+
+
+__all__ = [
+    "_load",
+    "_maybe_raise_legacy_hint",
+    "_read_json",
+    "_save",
+    "_sync_back",
+    "_to_delivery",
+    "_to_v0_dict",
+]

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.13.0"
+    "version": "1.15.0"
   },
   "plugins": [
     {
@@ -17,41 +17,97 @@
       "skills": [
         "./.claude/skills/adversarial-review",
         "./.claude/skills/agent-docs-writing",
+        "./.claude/skills/agent-handoff",
+        "./.claude/skills/agent-status",
+        "./.claude/skills/agents-audit",
+        "./.claude/skills/agents-cleanup",
+        "./.claude/skills/agents-prepare",
         "./.claude/skills/analysis-autonomous-mode",
         "./.claude/skills/analysis-skill-router",
+        "./.claude/skills/analyze-reference-repo",
         "./.claude/skills/api-design",
         "./.claude/skills/api-endpoint",
         "./.claude/skills/api-testing",
         "./.claude/skills/artisan-commands",
+        "./.claude/skills/authz-review",
         "./.claude/skills/aws-infrastructure",
         "./.claude/skills/blade-ui",
+        "./.claude/skills/blast-radius-analyzer",
         "./.claude/skills/bug-analyzer",
+        "./.claude/skills/bug-fix",
+        "./.claude/skills/bug-investigate",
+        "./.claude/skills/chat-history",
+        "./.claude/skills/chat-history-checkpoint",
+        "./.claude/skills/chat-history-clear",
+        "./.claude/skills/chat-history-resume",
+        "./.claude/skills/check-current-md",
+        "./.claude/skills/check-refs",
         "./.claude/skills/code-refactoring",
         "./.claude/skills/code-review",
         "./.claude/skills/command-routing",
+        "./.claude/skills/command-writing",
+        "./.claude/skills/commit",
+        "./.claude/skills/commit-in-chunks",
         "./.claude/skills/composer-packages",
+        "./.claude/skills/compress",
+        "./.claude/skills/context-authoring",
+        "./.claude/skills/context-create",
         "./.claude/skills/context-document",
+        "./.claude/skills/context-refactor",
         "./.claude/skills/conventional-commits-writing",
+        "./.claude/skills/copilot-agents-init",
         "./.claude/skills/copilot-agents-optimization",
+        "./.claude/skills/copilot-agents-optimize",
         "./.claude/skills/copilot-config",
+        "./.claude/skills/create-pr",
+        "./.claude/skills/create-pr-description",
         "./.claude/skills/dashboard-design",
+        "./.claude/skills/data-flow-mapper",
         "./.claude/skills/database",
         "./.claude/skills/dependency-upgrade",
+        "./.claude/skills/description-assist",
         "./.claude/skills/design-review",
         "./.claude/skills/devcontainer",
         "./.claude/skills/developer-like-execution",
+        "./.claude/skills/do-and-judge",
+        "./.claude/skills/do-in-steps",
         "./.claude/skills/docker",
         "./.claude/skills/dto-creator",
+        "./.claude/skills/e2e-heal",
+        "./.claude/skills/e2e-plan",
         "./.claude/skills/eloquent",
+        "./.claude/skills/estimate-ticket",
+        "./.claude/skills/existing-ui-audit",
         "./.claude/skills/fe-design",
+        "./.claude/skills/feature-dev",
+        "./.claude/skills/feature-explore",
+        "./.claude/skills/feature-plan",
         "./.claude/skills/feature-planning",
+        "./.claude/skills/feature-refactor",
+        "./.claude/skills/feature-roadmap",
         "./.claude/skills/file-editor",
+        "./.claude/skills/finishing-a-development-branch",
+        "./.claude/skills/fix-ci",
+        "./.claude/skills/fix-portability",
+        "./.claude/skills/fix-pr-bot-comments",
+        "./.claude/skills/fix-pr-comments",
+        "./.claude/skills/fix-pr-developer-comments",
+        "./.claude/skills/fix-references",
+        "./.claude/skills/fix-seeder",
         "./.claude/skills/flux",
         "./.claude/skills/git-workflow",
         "./.claude/skills/github-ci",
         "./.claude/skills/grafana",
+        "./.claude/skills/guideline-writing",
+        "./.claude/skills/implement-ticket",
         "./.claude/skills/jira-integration",
+        "./.claude/skills/jira-ticket",
         "./.claude/skills/jobs-events",
+        "./.claude/skills/judge",
+        "./.claude/skills/judge-bug-hunter",
+        "./.claude/skills/judge-code-quality",
+        "./.claude/skills/judge-security-auditor",
+        "./.claude/skills/judge-test-coverage",
         "./.claude/skills/laravel",
         "./.claude/skills/laravel-horizon",
         "./.claude/skills/laravel-mail",
@@ -63,15 +119,32 @@
         "./.claude/skills/laravel-scheduling",
         "./.claude/skills/laravel-validation",
         "./.claude/skills/learning-to-rule-or-skill",
+        "./.claude/skills/lint-skills",
         "./.claude/skills/livewire",
         "./.claude/skills/logging-monitoring",
         "./.claude/skills/mcp",
+        "./.claude/skills/md-language-check",
+        "./.claude/skills/memory-add",
+        "./.claude/skills/memory-full",
+        "./.claude/skills/memory-promote",
         "./.claude/skills/merge-conflicts",
         "./.claude/skills/migration-creator",
+        "./.claude/skills/mode",
+        "./.claude/skills/module-create",
+        "./.claude/skills/module-explore",
         "./.claude/skills/module-management",
         "./.claude/skills/multi-tenancy",
+        "./.claude/skills/onboard",
         "./.claude/skills/openapi",
+        "./.claude/skills/optimize-agents",
+        "./.claude/skills/optimize-augmentignore",
+        "./.claude/skills/optimize-rtk-filters",
+        "./.claude/skills/optimize-skills",
+        "./.claude/skills/override-create",
+        "./.claude/skills/override-manage",
         "./.claude/skills/override-management",
+        "./.claude/skills/package-reset",
+        "./.claude/skills/package-test",
         "./.claude/skills/performance",
         "./.claude/skills/performance-analysis",
         "./.claude/skills/pest-testing",
@@ -79,6 +152,7 @@
         "./.claude/skills/php-debugging",
         "./.claude/skills/php-service",
         "./.claude/skills/playwright-testing",
+        "./.claude/skills/prepare-for-review",
         "./.claude/skills/project-analysis-core",
         "./.claude/skills/project-analysis-hypothesis-driven",
         "./.claude/skills/project-analysis-laravel",
@@ -87,32 +161,61 @@
         "./.claude/skills/project-analysis-react",
         "./.claude/skills/project-analysis-symfony",
         "./.claude/skills/project-analysis-zend-laminas",
+        "./.claude/skills/project-analyze",
         "./.claude/skills/project-analyzer",
         "./.claude/skills/project-docs",
+        "./.claude/skills/project-health",
+        "./.claude/skills/propose-memory",
+        "./.claude/skills/quality-fix",
         "./.claude/skills/quality-tools",
+        "./.claude/skills/react-shadcn-ui",
         "./.claude/skills/readme-reviewer",
         "./.claude/skills/readme-writing",
         "./.claude/skills/readme-writing-package",
+        "./.claude/skills/receiving-code-review",
+        "./.claude/skills/refine-prompt",
+        "./.claude/skills/refine-ticket",
+        "./.claude/skills/requesting-code-review",
+        "./.claude/skills/review-changes",
+        "./.claude/skills/review-routing",
+        "./.claude/skills/roadmap-create",
+        "./.claude/skills/roadmap-execute",
         "./.claude/skills/roadmap-management",
         "./.claude/skills/rtk-output-filtering",
+        "./.claude/skills/rule-compliance-audit",
+        "./.claude/skills/rule-writing",
         "./.claude/skills/security",
         "./.claude/skills/security-audit",
         "./.claude/skills/sentry-integration",
         "./.claude/skills/sequential-thinking",
+        "./.claude/skills/set-cost-profile",
         "./.claude/skills/skill-improvement-pipeline",
         "./.claude/skills/skill-management",
         "./.claude/skills/skill-reviewer",
         "./.claude/skills/skill-writing",
         "./.claude/skills/sql-writing",
+        "./.claude/skills/subagent-orchestration",
+        "./.claude/skills/sync-agent-settings",
+        "./.claude/skills/sync-gitignore",
+        "./.claude/skills/systematic-debugging",
         "./.claude/skills/technical-specification",
         "./.claude/skills/terraform",
         "./.claude/skills/terragrunt",
+        "./.claude/skills/test-driven-development",
         "./.claude/skills/test-performance",
+        "./.claude/skills/tests-create",
+        "./.claude/skills/tests-execute",
+        "./.claude/skills/threat-model",
+        "./.claude/skills/threat-modeling",
         "./.claude/skills/traefik",
         "./.claude/skills/universal-project-analysis",
+        "./.claude/skills/update-form-request-messages",
         "./.claude/skills/upstream-contribute",
+        "./.claude/skills/using-git-worktrees",
         "./.claude/skills/validate-feature-fit",
-        "./.claude/skills/websocket"
+        "./.claude/skills/verify-before-complete",
+        "./.claude/skills/websocket",
+        "./.claude/skills/work"
       ]
     }
   ]

package/AGENTS.md

@@ -1,5 +1,7 @@
 # event4u/agent-config
 
+> **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
+
 **Shared agent configuration** — skills, rules, commands, guidelines, and templates
 for AI coding tools (Augment Code, Claude Code, Cursor, Cline, Windsurf, Gemini CLI,
 GitHub Copilot).
@@ -47,16 +49,41 @@ No PHP, no Laravel, no JavaScript runtime dependencies. The `composer.json` /
 ## Working on this repo
 
 ```bash
-task sync          # .agent-src.uncompressed/ → .agent-src/, then project → .augment/
-task generate-tools # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
-task test          # pytest tests/ + tests/test_install.sh
-task lint-skills   # python3 scripts/skill_linter.py --all
-task ci            # Full pipeline — must be green before PR
+task sync                  # .agent-src.uncompressed/ → .agent-src/, then project → .augment/
+task generate-tools        # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
+task test                  # pytest tests/ + tests/test_install.sh
+task lint-skills           # python3 scripts/skill_linter.py --all
+task build-cloud-bundles-all  # ZIP every eligible skill → dist/cloud/ (Claude.ai Web / Skills API)
+task ci                    # Full pipeline — must be green before PR
 ```
 
 All checks must pass before a PR: sync-check, consistency, check-compression,
 check-refs, check-portability, lint-skills, test, lint-readme.
 
+## Maintainer telemetry (opt-in)
+
+The artefact-engagement telemetry pipeline (`./agent-config telemetry:record`
+and `./agent-config telemetry:report`) is **default-off**. Maintainers who
+want to measure which skills/rules/commands the agent actually applies set
+`telemetry.artifact_engagement.enabled: true` in `.agent-settings.yml`. The
+log is local-only JSONL (no upload, no cross-project share) and is bound
+by the redaction floor described in
+[`docs/contracts/artifact-engagement-flow.md`](docs/contracts/artifact-engagement-flow.md) (beta).
+The recording rule lives at
+[`.agent-src/rules/artifact-engagement-recording.md`](.agent-src/rules/artifact-engagement-recording.md).
+
+## Context-aware command suggestion
+
+When a user's free-form prompt matches a command's purpose, the agent
+surfaces matches as a numbered-options block with an always-present
+"run the prompt as-is" escape. **Nothing auto-executes** — the user
+picks every time. Engine: `scripts/command_suggester/`. Rule:
+[`.agent-src/rules/command-suggestion.md`](.agent-src/rules/command-suggestion.md).
+Locked eligibility table, scoring contract, and hardening list:
+[`docs/contracts/adr-command-suggestion.md`](docs/contracts/adr-command-suggestion.md)
+and
+[`docs/contracts/command-suggestion-flow.md`](docs/contracts/command-suggestion-flow.md) (beta).
+
 ## Key rules for agents editing this repo
 
 | Rule | File |
@@ -73,9 +100,9 @@ check-refs, check-portability, lint-skills, test, lint-readme.
 
 ```
 .agent-src.uncompressed/      ← edit here
-  skills/       (124 skills)
-  rules/        (46 rules)
-  commands/     (73 commands)
+  skills/       (128 skills)
+  rules/        (55 rules)
+  commands/     (77 commands)
   guidelines/   (46 guidelines)
   personas/     (7 personas)
   templates/    (AGENTS.md, copilot-instructions.md, skill.md, …)
@@ -101,9 +128,12 @@ agents/                     ← this package's own roadmaps / sessions / context
 | Cline | `.clinerules/` | Symlinks |
 | Windsurf | `.windsurfrules` | Concatenated file |
 | Gemini CLI | `GEMINI.md` | Symlink → AGENTS.md |
+| Claude.ai Web / Skills API | `dist/cloud/<skill>.zip` | `task build-cloud-bundles-all` (T3-H gated) |
 
 Skills follow the [Agent Skills open standard](https://agentskills.io). Commands
 are converted to Claude Code Skills with `disable-model-invocation: true`.
+Cloud bundles enforce description budgets and prepend a sandbox note for
+T2/T3-S skills — see [`docs/architecture.md`](docs/architecture.md#cloud-bundle-pipeline).
 
 ## Contributing