@event4u/agent-config 1.14.0 → 1.16.0

package/.agent-src/skills/skill-writing/SKILL.md

@@ -70,7 +70,7 @@ Do NOT create a skill or rule for:
 
 ### Size and structure hints
 
-→ See `guidelines/agent-infra/size-and-scope.md` for full limits.
+→ See `docs/guidelines/agent-infra/size-and-scope.md` for full limits.
 
 * Target: 300–900 words. Review for split above 1200 words. Strongly consider split above 1500 words.
 * If multiple workflows exist → split into multiple skills
@@ -173,9 +173,9 @@ Present the stub as a numbered-options prompt (per `user-interaction`):
 ```
 
 Nothing is committed without the user's pick. If the user picks *skip*,
-record it in the commit message (`Eval stub: deferred`). Peer examples:
-`php-coder/evals/triggers.json`, `eloquent/evals/triggers.json`,
-`skill-writing/evals/triggers.json`.
+record it in the commit message (`Eval stub: deferred`). Peer examples
+for the expected format: `php-coder/evals/triggers.json`,
+`eloquent/evals/triggers.json`, `skill-writing/evals/triggers.json`.
 
 Rules / commands / guidelines do **not** get eval stubs — only skills
 route through the top-level catalogue.
@@ -262,7 +262,7 @@ Example:
 
 Skills may declare an `execution` frontmatter block (`type`, `handler`,
 `timeout_seconds`, `safety_mode`, `allowed_tools`). Default is `manual`
-(instructional only). See `guidelines/agent-infra/runtime-layer.md` for
+(instructional only). See `docs/guidelines/agent-infra/runtime-layer.md` for
 the full specification and `assisted` / `automated` semantics.
 
 ### When to create a `project-analysis-*` skill
@@ -285,5 +285,5 @@ utility libs, or simple state managers.
 
 * Write documentation-style, pointer-only, or too-broad skills ("Laravel skill")
 * Skip Procedure or use vague validation
-* Exceed size limits (see `guidelines/agent-infra/size-and-scope.md`)
+* Exceed size limits (see `docs/guidelines/agent-infra/size-and-scope.md`)
 * Duplicate rules

package/.agent-src/skills/subagent-orchestration/SKILL.md

@@ -187,4 +187,5 @@ the judge verdict.
 | Do-and-judge loop                    | [`/do-and-judge`](../../commands/do-and-judge.md) |
 | Stepwise plan with judge gates       | [`/do-in-steps`](../../commands/do-in-steps.md) |
 | Standalone judge on an existing diff | [`/judge`](../../commands/judge.md)  |
+| External / networked second opinion  | [`ai-council`](../ai-council/SKILL.md) |
 | Verifying completeness               | [`verify-before-complete`](../verify-before-complete/SKILL.md) |

package/.agent-src/skills/systematic-debugging/SKILL.md

@@ -72,7 +72,7 @@ Goal: locate the failure in a single component, layer, or call site.
 3. Check recent changes: `git log`, `git blame` on the failing line,
    recent dependency updates, config edits, infra changes.
 4. **Consult memory for prior matches.** Via
-   [`memory-access`](../../guidelines/agent-infra/memory-access.md):
+   [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md):
    ```python
    from scripts.memory_lookup import retrieve
    priors = retrieve(

package/.agent-src/skills/upstream-contribute/SKILL.md

@@ -178,14 +178,14 @@ If not in the package repo, note that these checks will run in CI after the PR i
 
 If the contribution originates from a proposal under `agents/proposals/`
 (produced by `learning-to-rule-or-skill` via the pipeline in
-[`self-improvement-pipeline`](../../guidelines/agent-infra/self-improvement-pipeline.md)),
+[`self-improvement-pipeline`](../../../docs/guidelines/agent-infra/self-improvement-pipeline.md)),
 run the Stage-4 gate before opening the PR:
 
 ```bash
 ./agent-config proposal:check agents/proposals/{slug}.md
 ```
 
-**Hard refusal rule:** if `check_proposal.py` exits non-zero, STOP —
+**Hard refusal rule:** if `./agent-config proposal:check` exits non-zero, STOP —
 do not create the branch, do not push, do not open the PR. Surface the
 findings to the user, ask them to fix the proposal (add evidence,
 remove TODO markers, complete required sections), then rerun.
@@ -247,7 +247,7 @@ The shared version now replaces the local override.
 ## Do NOT
 
 - **Do NOT create any upstream artifact without explicit user consent** — this is the #1 rule
-- **Do NOT open a PR if `check_proposal.py` blocks** — fix the proposal first (step 6b)
+- **Do NOT open a PR if `./agent-config proposal:check` blocks** — fix the proposal first (step 6b)
 - Do NOT edit `.augment/` in the consumer project — it's managed by the package
 - Do NOT submit project-specific content without generalizing it first
 - Do NOT skip the compressed version — both files are mandatory

package/.agent-src/skills/validate-feature-fit/SKILL.md

@@ -45,7 +45,7 @@ Verify the request doesn't conflict with:
 - Data flow (does it bypass existing services or repositories?)
 - **Product rules and domain invariants** — pull active rules via the
   shared abstraction (see
-  [`memory-access`](../../guidelines/agent-infra/memory-access.md)):
+  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md)):
 
   ```python
   from scripts.memory_lookup import retrieve
@@ -60,7 +60,7 @@ Verify the request doesn't conflict with:
   (e.g., "free plan caps at 3 users"); the feature must either respect
   it or explicitly propose to retire it. Cite the matching `id:` in
   the findings. Schema:
-  [`engineering-memory-data-format`](../../guidelines/agent-infra/engineering-memory-data-format.md).
+  [`engineering-memory-data-format`](../../../docs/guidelines/agent-infra/engineering-memory-data-format.md).
 
 **If contradiction found** → show the existing pattern, explain why it matters.
 

package/.agent-src/skills/{verify-before-complete → verify-completion-evidence}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: verify-before-complete
+name: verify-completion-evidence
 description: "Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs."
 source: package
 ---
 
-# verify-before-complete
+# verify-completion-evidence
 
 ## When to use
 

package/.agent-src/templates/agent-settings.md

@@ -14,7 +14,7 @@ Keep the format regular — 2-space indent, no tabs, no lists, one nesting
 level only. The installer's YAML handler is a restricted stdlib parser, not
 a full YAML engine. Ask the agent to normalize after manual edits — it
 follows the merge rules in
-[`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ### Migration from the legacy `.agent-settings` (key=value)
 
@@ -36,7 +36,7 @@ This block defines the personal and project-level settings that
 `scripts/install.py` (via `config/agent-settings.template.yml`)
 writes to `.agent-settings.yml` on first install. Subsequent edits are
 made by the user directly or by the agent on request, following the
-[section-aware merge rules](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ```yaml
 # Agent Settings
@@ -276,7 +276,7 @@ onboarding:
 # When the user's free-form prompt matches an eligible slash command,
 # the agent surfaces a numbered-options block with the recommendation
 # plus an always-present "run as-is" option. The suggestion layer
-# never auto-executes — the user picks. See `rules/command-suggestion.md`.
+# never auto-executes — the user picks. See `rules/command-suggestion-policy.md`.
 commands:
   suggestion:
     # Master switch (true, false). `false` = the layer is silent;
@@ -299,7 +299,7 @@ commands:
 # rules, commands, guidelines, personas) the agent consulted and
 # applied. Local only, append-only JSONL, never reaches a consumer
 # repo (gitignored). Maintainer-targeted feature; consumers leave it
-# off. See `agents/contexts/artifact-engagement-flow.md` (once Phase 3
+# off. See `docs/contracts/artifact-engagement-flow.md` (once Phase 3
 # of road-to-artifact-engagement-telemetry lands).
 telemetry:
   artifact_engagement:
@@ -328,7 +328,7 @@ telemetry:
 
 Personal and project-level settings (initial file written by
 `scripts/install.py`, edits follow the merge rules in
-[`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
+[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
 **Key paths use dot-notation** to denote nesting: `personal.user_name`
 lives under `personal:` in YAML.
 
@@ -365,12 +365,12 @@ lives under `personal:` in YAML.
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
-| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../guidelines/agent-infra/role-contracts.md). |
+| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md). |
 | `roles.active_role` | same as `default_role` | _(empty)_ | Role currently active; set by `/mode <name>`, cleared by `/mode none`. Enables the `role-mode-adherence` rule. |
-| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../guidelines/agent-infra/layered-settings.md). |
+| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md). |
 | `personas.ignore` | list of persona ids | `[]` | Persona ids dropped from the default cast locally. Ignored personas stay invokable via `--personas=<id>`. |
 | `onboarding.onboarded` | `true`, `false` | `false` | Whether `/onboard` has run on this project. The `onboarding-gate` rule prompts for `/onboard` when this is `false`. Missing entirely = legacy project, treated as onboarded. |
-| `commands.suggestion.enabled` | `true`, `false` | `true` | Master switch for the command-suggestion layer. `false` = the layer is silent; explicit `/commands` still work. See `rules/command-suggestion.md`. |
+| `commands.suggestion.enabled` | `true`, `false` | `true` | Master switch for the command-suggestion layer. `false` = the layer is silent; explicit `/commands` still work. See `rules/command-suggestion-policy.md`. |
 | `commands.suggestion.confidence_floor` | `0.0`–`1.0` | `0.6` | Minimum match score before a suggestion surfaces. Per-command frontmatter (`suggestion.confidence_floor`) overrides this global floor. |
 | `commands.suggestion.cooldown_seconds` | integer | `600` | Cooldown between re-suggestions of the same `(command, evidence)` pair. `600` = 10m. |
 | `commands.suggestion.max_options` | integer | `4` | Max number of command suggestions before the always-present "run as-is" option (total rendered = `max_options + 1`). |
@@ -432,7 +432,7 @@ they ship with a live consumer in code and get documented here, not before.
 ## Sync rules
 
 When new settings are added to this template, the
-[section-aware merge rules](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 govern the update:
 
 1. Missing keys are added with their **default value** from this template,

package/.agent-src/templates/contexts/auth-model.md

@@ -55,5 +55,5 @@
 
 - `agents/contexts/tenant-boundaries.md` — tenancy scope, multi-tenant
   rules that sit on top of the role model
-- `.augment/guidelines/agent-infra/*` — reviewer skills that read this
+- `../../../docs/guidelines/agent-infra/*` — reviewer skills that read this
   file

package/.agent-src/templates/roadmaps.md

@@ -7,7 +7,8 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
 ## Rules for Roadmaps
 
 1. **Be precise and concise.** Aim for 500–1000 lines max. If larger, split into multiple files.
-2. **Use checkboxes** (`- [ ]`) for every actionable step. Mark `[x]` when completed.
+2. **Checkboxes are mandatory, not decorative.** Every active roadmap MUST contain at least one `- [ ]` per non-intro phase. Decision tables, ICE matrices, and block-sequencing tables capture the *why*; checkboxes capture the *what to do next*. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` — the dashboard cannot count it, the next reader thinks no work is planned. Enforced by [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md) Iron Law #2.
+   - **Status is binary: `ready` (default) or `draft`.** New roadmaps are created **ready** unless the user explicitly says draft — `ready` is implicit and need not be written. Drafts declare it via frontmatter at the top of the file (`---\nstatus: draft\n---`) and are hidden from the dashboard until the flag is removed or flipped to `ready`. Use `draft` while the roadmap is still being authored, while waiting for upstream decisions, or as a capture-only synthesis that has not been promoted to executable phases. There are no other status values; legacy banners like `**Status: directional**` are removed.
 3. **State the goal first.** One sentence at the top — what is the outcome?
 4. **List prerequisites** — what must exist or be running before starting.
 5. **Reference existing code** — point to files, classes, or modules.
@@ -24,17 +25,17 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
     - `agents/roadmaps/skipped/` — decision against pursuit; typically 0 items `[x]` (superseded, scope rejected)
 
     See the `roadmap-management` skill for the exact trigger matrix and user-confirmation flow.
-
 13. **No tags, releases, or version numbers.** Roadmaps describe work, not shipping.
     Never assign version suffixes to phases (`Phase 1 — v1.8.0`), never write
     "Target release: X.Y.Z", never plan git tags or deprecation dates. Release
-    and tag decisions belong to the user, taken outside the roadmap. Enforced by
-    [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
+    and tag decisions belong to the user and are taken outside the roadmap.
+    This is enforced by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
 14. **No automatic branch switches mid-roadmap.** Roadmap work runs on the
-    current branch. If a separate branch (spike, hotfix, experiment) would
-    be useful, agent may propose it **once** during creation — not during
-    execution. Default: stay on current branch. If user declines, topic is
-    closed for this roadmap. See [`scope-control`](../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+    branch the user is on. If a separate branch (spike, hotfix, experiment)
+    would be genuinely useful, the agent may propose it **once** while
+    creating the roadmap — not during execution. Default: stay on the
+    current branch. If the user declines, the topic is closed for this
+    roadmap. See [`scope-control`](../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
 
 ---
 

package/.agent-src/templates/scripts/README.md

@@ -111,7 +111,7 @@ _Data source: ownership-map.yml + historical-bug-patterns.yml. …_
 ```
 
 Curate `ownership-map.yml` and `historical-bug-patterns.yml` over time —
-see `.augment/guidelines/agent-infra/review-routing-data-format.md` for
+see `../../../docs/guidelines/agent-infra/review-routing-data-format.md` for
 the full schema.
 
 ## Uninstall
@@ -191,5 +191,5 @@ python3 scripts/check_memory.py --path agents/memory
 Exit `0` = clean, `1` = violations (missing required fields, duplicate
 ids, or obvious secrets — staleness alone is informational).
 
-Schema reference: `.augment/guidelines/agent-infra/engineering-memory-data-format.md`.
+Schema reference: `../../../docs/guidelines/agent-infra/engineering-memory-data-format.md`.
 Schema examples: `.augment/templates/agents/memory/*.example.yml`.

package/.agent-src/templates/scripts/memory_lookup.py

@@ -246,7 +246,7 @@ def _apply_conflict_rule(
 # says retrieval should route through `@event4u/agent-memory`. The package
 # CLI is purely **semantic** (`memory retrieve <query> --type T …`); the
 # shared `retrieve(types, keys, …)` API is **key-based**. The hybrid
-# resolution agreed in `agents/contexts/agent-memory-contract.md` synthesises
+# resolution agreed in `docs/contracts/agent-memory-contract.md` synthesises
 # `keys` into a single natural-language query for the package call, while
 # the file fallback continues to do glob/substring matching on the same
 # keys. Both legs land in the same `Hit` shape so the conflict rule can

package/.agent-src/templates/scripts/telemetry/aggregator.py

@@ -26,7 +26,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Iterable, Iterator
 
-from .engagement import EngagementEvent, EngagementSchemaError, parse_event
+from .engagement import (
+    ALLOWED_OUTCOMES,
+    EngagementEvent,
+    EngagementSchemaError,
+    parse_event,
+)
 
 
 @dataclass(frozen=True)
@@ -53,6 +58,10 @@ class AggregateResult:
     earliest_ts: str | None = None
     latest_ts: str | None = None
     artefacts: dict[tuple[str, str], dict[str, object]] = field(default_factory=dict)
+    # Event-level outcome counts (boundary outcomes, not per-artefact).
+    # Initialised lazily in :func:`aggregate` so empty logs yield an
+    # empty dict rather than zeros across all five categories.
+    outcomes: dict[str, int] = field(default_factory=dict)
 
     def stats(self) -> list[ArtefactStat]:
         """Materialise the accumulated buckets as immutable stats."""
@@ -121,6 +130,12 @@ def aggregate(
         if result.latest_ts is None or event.ts > result.latest_ts:
             result.latest_ts = event.ts
         _accumulate(result.artefacts, event.consulted, event.applied, event.ts)
+        if event.outcomes:
+            for label in event.outcomes:
+                # Validator already restricted to ALLOWED_OUTCOMES, but
+                # the explicit guard documents intent and is cheap.
+                if label in ALLOWED_OUTCOMES:
+                    result.outcomes[label] = result.outcomes.get(label, 0) + 1
     return result
 
 

package/.agent-src/templates/scripts/telemetry/engagement.py

@@ -10,9 +10,24 @@ adds the redaction validator on top. The contract here is:
       "boundary_kind": "task" | "phase-step" | "tool-call",
       "consulted": {"skills": [...], "rules": [...], ...},
       "applied":   {"skills": [...], "rules": [...], ...},
+      "outcomes":  ["blocked", "verification_failed", ...]  # optional
       "tokens_estimate": {"consulted_load": <int>}   # optional
     }
 
+Outcomes (optional, additive in schema v1) capture *what happened*
+during the boundary, not which artefacts were consulted. The five
+allowed categories are scoped tightly so reports stay actionable:
+
+- ``blocked``                    — Hard-Floor / scope-control gate fired, work paused.
+- ``partial``                    — boundary closed without finishing the planned scope.
+- ``memory_influenced_decision`` — a memory entry shaped a non-trivial decision.
+- ``verification_failed``        — verify-before-complete gate rejected the result.
+- ``stop_rule_triggered``        — context-hygiene 3-failure / tool-loop stop fired.
+
+Outcomes compose: a single boundary may carry multiple. Order is
+preserved as recorded; duplicates are rejected to keep reports
+honest.
+
 Design choices:
 
 - Dataclass + manual ``validate()`` (no pydantic — keep the engine
@@ -48,6 +63,18 @@ ALLOWED_BOUNDARY_KINDS: tuple[str, ...] = (
     "tool-call",
 )
 
+# Outcome categories — see module docstring for semantics. The set is
+# intentionally small; widening requires an explicit follow-up roadmap
+# step. Reports group by these labels, so renaming is breaking.
+ALLOWED_OUTCOMES: tuple[str, ...] = (
+    "blocked",
+    "partial",
+    "memory_influenced_decision",
+    "verification_failed",
+    "stop_rule_triggered",
+)
+MAX_OUTCOMES_PER_EVENT = len(ALLOWED_OUTCOMES)
+
 # Phase 5 redaction validator — keep id fields from leaking paths,
 # free-text, or filenames. Repository-internal artefact ids and
 # task ids never contain these characters.
@@ -115,6 +142,7 @@ class EngagementEvent:
     boundary_kind: str
     consulted: dict[str, list[str]] = field(default_factory=dict)
     applied: dict[str, list[str]] = field(default_factory=dict)
+    outcomes: list[str] | None = None
     tokens_estimate: dict[str, int] | None = None
     schema_version: int = SCHEMA_VERSION
 
@@ -134,6 +162,8 @@ class EngagementEvent:
             )
         _validate_artefact_dict("consulted", self.consulted)
         _validate_artefact_dict("applied", self.applied)
+        if self.outcomes is not None:
+            _validate_outcomes(self.outcomes)
         if self.tokens_estimate is not None:
             if not isinstance(self.tokens_estimate, dict):
                 raise EngagementSchemaError(
@@ -160,6 +190,8 @@ class EngagementEvent:
             "consulted": _normalise_artefact_dict(self.consulted),
             "applied": _normalise_artefact_dict(self.applied),
         }
+        if self.outcomes:
+            out["outcomes"] = list(self.outcomes)
         if self.tokens_estimate:
             out["tokens_estimate"] = dict(self.tokens_estimate)
         return out
@@ -198,6 +230,32 @@ def _normalise_artefact_dict(payload: dict[str, list[str]]) -> dict[str, list[st
     return {kind: list(payload[kind]) for kind in ALLOWED_KINDS if payload.get(kind)}
 
 
+def _validate_outcomes(payload: Any) -> None:
+    if not isinstance(payload, list):
+        raise EngagementSchemaError(
+            "outcomes must be a list of str or None"
+        )
+    if len(payload) > MAX_OUTCOMES_PER_EVENT:
+        raise EngagementSchemaError(
+            f"outcomes exceeds {MAX_OUTCOMES_PER_EVENT} entries"
+        )
+    seen: set[str] = set()
+    for label in payload:
+        if not isinstance(label, str) or not label:
+            raise EngagementSchemaError(
+                "outcomes must contain non-empty str labels"
+            )
+        if label not in ALLOWED_OUTCOMES:
+            raise EngagementSchemaError(
+                f"outcomes contains {label!r}; allowed: {ALLOWED_OUTCOMES!r}"
+            )
+        if label in seen:
+            raise EngagementSchemaError(
+                f"outcomes contains duplicate {label!r}"
+            )
+        seen.add(label)
+
+
 def parse_event(line: str) -> EngagementEvent:
     if not isinstance(line, str) or not line.strip():
         raise EngagementSchemaError("line must be a non-empty JSONL record")
@@ -213,6 +271,7 @@ def parse_event(line: str) -> EngagementEvent:
         boundary_kind=raw.get("boundary_kind", ""),
         consulted=raw.get("consulted", {}) or {},
         applied=raw.get("applied", {}) or {},
+        outcomes=raw.get("outcomes"),
         tokens_estimate=raw.get("tokens_estimate"),
         schema_version=raw.get("schema_version", SCHEMA_VERSION),
     )

package/.agent-src/templates/scripts/telemetry/report_renderer.py

@@ -20,7 +20,7 @@ from dataclasses import dataclass
 from typing import Any, Sequence
 
 from .aggregator import AggregateResult, ArtefactStat, rank_artefacts
-from .engagement import check_id_redaction
+from .engagement import ALLOWED_OUTCOMES, check_id_redaction
 
 QUARTILE_TOP_RATIO = 0.20
 QUARTILE_BOTTOM_RATIO = 0.20
@@ -93,6 +93,23 @@ def render_markdown(
         lines.append(f"- ts range: `{aggregate.earliest_ts}` → `{aggregate.latest_ts}`")
     lines.append("")
 
+    # Outcomes summary — one row per category, in declared order, only
+    # when the log carries any outcome data. Stable column order so two
+    # reports over the same log render byte-identical.
+    outcomes_total = sum(aggregate.outcomes.values())
+    if outcomes_total:
+        lines.append("## Outcomes")
+        lines.append("")
+        lines.append("| outcome | count | share |")
+        lines.append("|---|---:|---:|")
+        for label in ALLOWED_OUTCOMES:
+            count = aggregate.outcomes.get(label, 0)
+            if not count:
+                continue
+            share = count / outcomes_total
+            lines.append(f"| {label} | {count} | {share:.2f} |")
+        lines.append("")
+
     titles = {
         BUCKET_TOP: "Essential (top 20 %)",
         BUCKET_MID: "Useful (mid 60 %)",
@@ -136,6 +153,15 @@ def render_json(
     if top is not None:
         for bucket in grouped:
             grouped[bucket] = grouped[bucket][:top]
+    # Outcomes — declared order, zeros omitted, total at top so callers
+    # can short-circuit without iterating the dict. Empty when no event
+    # in the window carried outcomes.
+    outcomes_total = sum(aggregate.outcomes.values())
+    outcomes_payload: dict[str, Any] = {"total": outcomes_total, "by_category": {}}
+    for label in ALLOWED_OUTCOMES:
+        count = aggregate.outcomes.get(label, 0)
+        if count:
+            outcomes_payload["by_category"][label] = count
     payload = {
         "schema_version": 1,
         "summary": {
@@ -146,6 +172,7 @@ def render_json(
             "latest_ts": aggregate.latest_ts,
             "since_label": since_label,
         },
+        "outcomes": outcomes_payload,
         "buckets": grouped,
     }
     return json.dumps(payload, sort_keys=True, indent=2) + "\n"

package/.agent-src/templates/scripts/telemetry_record.py

@@ -19,7 +19,8 @@ Usage:
     ./agent-config telemetry:record \\
         --task-id ticket-PROJ-42 --boundary task \\
         --consulted skills:php-coder --consulted rules:scope-control \\
-        --applied skills:php-coder
+        --applied skills:php-coder \\
+        --outcome verification_failed --outcome stop_rule_triggered
 
 Exit codes:
     0   success or disabled (silent)
@@ -38,6 +39,7 @@ from pathlib import Path
 # the script is dispatched from the package or from a consumer copy.
 from telemetry.boundary import record_event
 from telemetry.engagement import (
+    ALLOWED_OUTCOMES,
     EngagementEvent,
     EngagementSchemaError,
     now_utc_iso,
@@ -71,6 +73,7 @@ def _build_event_from_args(args: argparse.Namespace) -> EngagementEvent:
         boundary_kind=args.boundary,
         consulted=_parse_kv_list(args.consulted or []),
         applied=_parse_kv_list(args.applied or []),
+        outcomes=list(args.outcome) if args.outcome else None,
     )
 
 
@@ -87,6 +90,7 @@ def _build_event_from_payload(raw: str) -> EngagementEvent:
         boundary_kind=data.get("boundary_kind", ""),
         consulted=data.get("consulted", {}) or {},
         applied=data.get("applied", {}) or {},
+        outcomes=data.get("outcomes"),
         tokens_estimate=data.get("tokens_estimate"),
     )
 
@@ -107,6 +111,15 @@ def main(argv: list[str] | None = None) -> int:
     )
     parser.add_argument("--consulted", action="append")
     parser.add_argument("--applied", action="append")
+    parser.add_argument(
+        "--outcome",
+        action="append",
+        choices=ALLOWED_OUTCOMES,
+        help=(
+            "Boundary outcome label; repeat for multiple. "
+            "Allowed: " + ", ".join(ALLOWED_OUTCOMES) + "."
+        ),
+    )
     parser.add_argument("--ts", default="")
     parser.add_argument("--payload-file", type=Path)
     parser.add_argument("--stdin", action="store_true")

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

@@ -8,8 +8,8 @@ the dispatcher, CLI and step modules over from the legacy
 that re-exports from here with a ``DeprecationWarning``.
 
 Architectural constraints (from
-``agents/contexts/adr-implement-ticket-runtime.md`` and
-``agents/contexts/implement-ticket-flow.md``):
+``docs/contracts/adr-implement-ticket-runtime.md`` and
+``docs/contracts/implement-ticket-flow.md``):
 
 - Runtime is Python 3.10+.
 - The dispatcher is linear, not a DAG. Eight fixed steps, fixed order.