@event4u/agent-config 1.14.0 → 1.15.0

package/.agent-src/skills/roadmap-management/SKILL.md

@@ -30,12 +30,13 @@ the dashboard **in the same response**.
 `count_open == 0` (pure `[x]`, or `[x]` + `[~]`/`[-]`), `git mv`
 it into `agents/roadmaps/archive/` **before** regenerating — see
 the auto-archive decision table under "Check completion status"
-below. A 100%-complete roadmap left in `agents/roadmaps/` makes
-the next reader think work is still open.
+below. A 100%-complete roadmap left in `agents/roadmaps/` makes the
+next reader think work is still open.
 
-Enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md).
-Batching edits in one response is fine — one final regeneration before
-replying is enough. But the response must not end without it.
+This is enforced by the [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+rule. Batching multiple edits in one response is fine — one final
+regeneration before replying is enough. But the response must not end
+without it.
 
 ## Procedure: Manage a roadmap
 
@@ -100,11 +101,13 @@ Every roadmap follows this structure:
 
 ## Key rules for roadmaps
 
-### Checkboxes
+### Checkboxes — mandatory, not decorative
 
+- **Every active roadmap MUST contain at least one `- [ ]` per non-intro phase.** Decision tables, ICE matrices, and block-sequencing tables are valid rationale, but they do not satisfy this rule on their own — pair them with a `## Phase N` or `## Implementation Checklist` section whose checkboxes execute the decision. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` and violates [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) Iron Law #2.
 - Every actionable step uses `- [ ]` (unchecked) or `- [x]` (completed).
 - Mark steps as `[x]` immediately after completing them.
 - Never remove completed steps — they serve as history.
+- **Status is binary: `ready` (default, implicit) or `draft`.** New roadmaps are created **ready** unless the user explicitly says otherwise — `ready` is implicit and need not be written. A roadmap that is still being authored, awaiting upstream decisions, or capturing options without a worked plan declares `status: draft` in YAML frontmatter at the top of the file. Drafts are hidden from `agents/roadmaps-progress.md` until the flag is removed or flipped to `ready`. There are no other status values; legacy banners (`**Status: directional**`, `Status: capture-only`, `mode: feedback`) are removed.
 
 ### Phases
 
@@ -138,12 +141,13 @@ Every roadmap implicitly includes these gates (run after each step that changes
 1. Ask the user for goal, context-create, and phases.
 2. Use the template structure from `.augment/templates/roadmaps.md`.
 3. Review with the user iteratively until approved.
-4. **Branch & release questions — ask at most once, only if genuinely useful.**
-   Default: stay on current branch, no version numbers in roadmap.
-   Only propose a separate branch with concrete evidence (e.g. risky
-   migration → spike branch). Never include releases, deprecation dates,
-   or git tags in roadmap text. If user declines, do **not** re-propose
-   during `roadmap-execute`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+4. **Branch & release questions — at most once, only if genuinely useful.**
+   Default: stay on the current branch, no version numbers in the
+   roadmap. Only propose a separate branch when there is concrete,
+   evidence-based reason (e.g. risky migration benefits from a spike).
+   Never include release versions, deprecation dates, or git tags in
+   the roadmap text. If the user declines, do **not** re-propose during
+   `roadmap-execute`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
 5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
 6. Regenerate the dashboard so the new roadmap is included.
 
@@ -272,8 +276,10 @@ Command:
 ./agent-config roadmap:progress-check     # CI: fail if stale
 ```
 
-The `./agent-config` wrapper is written into the project root by the
-installer and always works — no global tooling or task runner required.
+The `./agent-config` wrapper lives in the project root (written by the
+package installer, gitignored) and delegates to the master CLI inside
+`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
+No global tooling required.
 
 The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate it.
 
@@ -309,5 +315,5 @@ The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate
 - Do NOT archive roadmaps with open `[ ]` items without asking the user.
 - Do NOT delete roadmaps — always move to `archive/` or `skipped/`.
 - Do NOT use `skipped/` as a dumping ground for partially-finished work — that is what `archive/` with deferred items is for.
-- Do NOT assign version numbers, git tags, deprecation dates, or release identifiers to phases. Hard rule — see [`scope-control`](../../rules/scope-control.md#git-operations--permission-gated).
-- Do NOT propose a branch switch while executing a roadmap. Branch question is settled at creation; declined or never-asked = silent. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+- Do NOT assign version numbers, git tags, deprecation dates, or release identifiers to phases. Roadmaps plan work; releases and tags are decided by the user separately. Hard rule — see [`scope-control`](../../rules/scope-control.md#git-operations--permission-gated).
+- Do NOT propose a branch switch while executing a roadmap. The branch question is settled at creation time; if the user already declined (or you never asked because it wasn't sensible), stay silent. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).

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

@@ -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.

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

@@ -185,7 +185,7 @@ run the Stage-4 gate before opening the PR:
 ./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/templates/agent-settings.md

@@ -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:

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/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/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.