@event4u/agent-config 3.3.0 → 4.2.0

package/.agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -99,15 +99,15 @@ Decide what to create:
 
 ### Step 4: Create or Update
 
-- **New rule** → create in `.agent-src.uncompressed/rules/`, follow rule conventions
-- **New skill** → use `skill-writing` skill, create in `.agent-src.uncompressed/skills/`
+- **New rule** → create in `.agent-src.uncondensed/rules/`, follow rule conventions
+- **New skill** → use `skill-writing` skill, create in `.agent-src.uncondensed/skills/`
 - **Update existing** → use `skill-management` skill
 
 After creation:
 1. Run `python3 scripts/skill_linter.py {path}` — must pass (0 fail)
 2. Copy to `.augment/`
-3. Mark hash: `python3 scripts/compress.py --mark-done "{relative_path}"`
-4. Regenerate tools: `python3 scripts/compress.py --generate-tools`
+3. Mark hash: `python3 scripts/condense.py --mark-done "{relative_path}"`
+4. Regenerate tools: `python3 scripts/condense.py --generate-tools`
 
 ### Step 5: Decide scope
 
@@ -131,7 +131,7 @@ Ask the user:
 1. Read `project.upstream_repo` and `project.improvement_pr_branch_prefix` from `.agent-settings.yml`
 2. If `project.upstream_repo` is empty → ask user for the target repo
 3. Create branch: `{prefix}{learning-slug}` from `main`
-4. Commit changes to `.agent-src.uncompressed/` AND `.augment/`
+4. Commit changes to `.agent-src.uncondensed/` AND `.augment/`
 5. Push branch
 6. Create PR with title: `improve(agent): {short description}`
 7. Use the agent-improvement PR template if it exists
@@ -155,7 +155,7 @@ Ask the user:
 - Do NOT skip the promotion gate — it prevents skill/rule bloat
 - Do NOT create both a rule AND a skill for the same learning
 - Do NOT auto-push without user permission
-- Do NOT create project-specific content in `.agent-src.uncompressed/`
+- Do NOT create project-specific content in `.agent-src.uncondensed/`
 - Do NOT run this pipeline for trivial learnings
 
 ## References

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

@@ -1,6 +1,6 @@
 ---
 name: skill-management
-description: "Use when compressing, decompressing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained."
+description: "Use when condensing, decondenseing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained."
 source: project
 domain: process
 execution:
@@ -26,8 +26,8 @@ install:
 ## When to use
 
 Use this skill when:
-* Compressing a verbose skill into a sharper version
-* Expanding a compressed skill into a maintainable source-of-truth
+* Condenseing a verbose skill into a sharper version
+* Expanding a condensed skill into a maintainable source-of-truth
 * Refactoring a skill to fix structure, scope, or quality issues
 * Migrating skills to new standards
 
@@ -37,22 +37,22 @@ Do not use when:
 
 ## Procedure: Manage a skill
 
-### Mode: Compress
-**Trigger:** "compress skill", "shorten skill", "make skill sharper"
+### Mode: Condense
+**Trigger:** "condense skill", "shorten skill", "make skill sharper"
 
 1. Inspect — what is the core job? Which lines are redundant?
 2. Preserve critical skeleton: When to use, Procedure, Output format, Gotchas, Do NOT
-3. Compress trigger — rewrite description for fast matching
-4. Compress decision logic — explanations → direct choices
-5. Compress procedure — each step short and executable
+3. Condense trigger — rewrite description for fast matching
+4. Condense decision logic — explanations → direct choices
+5. Condense procedure — each step short and executable
 6. Remove obvious content — keep only what model forgets or misuses
-7. Validate — compressed version must be: easier to scan, easier to trigger, at least as safe
+7. Validate — condensed version must be: easier to scan, easier to trigger, at least as safe
 
-**Iron rule:** Compression must NOT weaken validation or remove decision hints that prevent mistakes.
-**Linter gate:** After compression, run `python3 scripts/skill_linter.py` on the file — must be 0 FAIL.
+**Iron rule:** Condensation must NOT weaken validation or remove decision hints that prevent mistakes.
+**Linter gate:** After condensation, run `python3 scripts/skill_linter.py` on the file — must be 0 FAIL.
 
-### Mode: Decompress
-**Trigger:** "expand skill", "decompress skill", "make skill clearer"
+### Mode: Decondense
+**Trigger:** "expand skill", "decondense skill", "make skill clearer"
 
 1. Inspect — which parts are unclear or too condensed?
 2. Restore full structure (all required sections)
@@ -81,7 +81,7 @@ Do not use when:
 If the refactor introduced guideline delegations ("see guideline X"), ensure the Procedure still works standalone.
 
 **Decision hints:**
-* Too long → compress or split
+* Too long → condense or split
 * Too generic → narrow scope
 * Missing validation → add it
 * Too dependent on guidelines → inline essential steps
@@ -92,7 +92,7 @@ If the refactor introduced guideline delegations ("see guideline X"), ensure the
 * Same idea repeated in Goal, Core rules, and Gotchas
 * Long paragraphs where one bullet would do
 * Vague procedure steps ("think about X")
-* Compression that deletes safety-critical checks
+* Condensation that deletes safety-critical checks
 * Over-expansion that turns skills into documentation
 * Refactoring scope instead of structure
 * Removing gotchas because they "look verbose"
@@ -104,18 +104,18 @@ If the refactor introduced guideline delegations ("see guideline X"), ensure the
 
 ## Gotchas
 
-* Over-compression removes important nuance
+* Over-condensation removes important nuance
 * Some examples look verbose but are load-bearing
 * Shorter is not better if trigger quality drops
 * Changing intent instead of improving structure
-* Compressed versions must be derived from uncompressed source, not the other way around
+* Condensed versions must be derived from uncondensed source, not the other way around
 * **Validation steps are non-negotiable** — every Procedure must end with a concrete verify/confirm step. Skills without validation pass the linter today but cause failures when the linter is tightened.
 * **Renaming headings to "Procedure:" without adding steps** creates false structure — the linter now requires ordered steps or sub-headings inside Procedure blocks.
 
 ## Do NOT
 
 * Do NOT remove validation steps
-* Do NOT compress away decision hints that prevent mistakes
+* Do NOT condense away decision hints that prevent mistakes
 * Do NOT change the skill's core intent
 * Do NOT merge unrelated workflows to save space
 * Do NOT expand everything blindly — only where it helps execution
@@ -124,11 +124,11 @@ If the refactor introduced guideline delegations ("see guideline X"), ensure the
 
 ## Auto-trigger keywords
 
-* compress skill
-* decompress skill
+* condense skill
+* decondense skill
 * refactor skill
 * improve skill
 * shorten skill
 * expand skill
-* caveman compress
+* telegraph condense
 * make skill sharper

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

@@ -169,7 +169,7 @@ Before scoring the 5 Killers, verify structure:
 - Always-applicable (no situational triggers)
 - Not procedural (no numbered steps — that's a skill)
 
-**Compression safety** (if compressed version exists):
+**Condensation safety** (if condensed version exists):
 - Trigger clarity preserved
 - Decision hints or equivalent present
 - Concrete validation still present
@@ -191,7 +191,7 @@ Before scoring the 5 Killers, verify structure:
 ### Single skill
 1. Validate structure (required sections present)
 2. Score each killer: ✅ Pass / ⚠️ Weak / ❌ Fail
-3. Check compression safety (if applicable)
+3. Check condensation safety (if applicable)
 4. Produce a verdict table + specific fix suggestions
 
 ### Batch audit

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

@@ -75,9 +75,9 @@ Ask: **"Does the model need this to do its job correctly?"**
 
 ### Skills and commands share the `.claude/skills/` namespace
 
-Skills in `.agent-src.uncompressed/skills/{name}/SKILL.md` AND commands in
-`.agent-src.uncompressed/commands/{name}.md` both project into
-`.claude/skills/` (see `scripts/compress.py` →
+Skills in `.agent-src.uncondensed/skills/{name}/SKILL.md` AND commands in
+`.agent-src.uncondensed/commands/{name}.md` both project into
+`.claude/skills/` (see `scripts/condense.py` →
 `generate_claude_skills` + `generate_claude_commands`). Claude treats
 the whole directory as native skills.
 
@@ -118,7 +118,7 @@ Do NOT create a skill or rule for:
 ### 0. Inspect, then run the Drafting Protocol
 
 Before writing, **inspect** the landscape: grep
-`.agent-src.uncompressed/skills/` and `rules/` for duplicates or
+`.agent-src.uncondensed/skills/` and `rules/` for duplicates or
 near-matches, and **analyze** 1–2 gold-standard peers (e.g. `pest-testing`,
 `php-coder`) to anchor shape and tone. If requirements are unclear or
 incomplete, stop and ask — do not assume.
@@ -178,7 +178,7 @@ approval-gated propose / pick loop with at most two rounds.
 ### 1c. Propose a trigger-eval stub (new skills only)
 
 When creating a new skill, propose a stub
-`.agent-src.uncompressed/skills/{name}/evals/triggers.json` before writing
+`.agent-src.uncondensed/skills/{name}/evals/triggers.json` before writing
 the body. Draw the queries from Phase A of the drafting protocol (the
 user's "should trigger" and "must not trigger" answers).
 
@@ -292,7 +292,7 @@ asks for it.
 **Workspace layout** (all under `.gitignore`):
 
 ```
-.agent-src.uncompressed/skills/{name}/evals/
+.agent-src.uncondensed/skills/{name}/evals/
   triggers.json              # tracked — routing eval (§ 1c)
   evals.json                 # tracked — behavior eval definitions
   runs/                      # gitignored — per-iteration outputs
@@ -379,13 +379,13 @@ Neighbors:
 
 * Body links to guidelines / contracts use the verbatim relative form
   (`../../docs/guidelines/<group>/<name>.md`,
-  `../../docs/contracts/<name>.md`). The compress-time rewriter
+  `../../docs/contracts/<name>.md`). The condense-time rewriter
   resolves them to depth-aware single-up form — do not pre-rewrite in
   source.
 * Skills do **not** declare `load_context:` / `load_context_eager:`;
   those frontmatter keys are rule-only. If a skill needs to point at a
   context, link to it inline (`[context-name](../../contexts/<area>/<file>.md)`).
-* Never write `.agent-src.uncompressed/` in any skill body link or
+* Never write `.agent-src.uncondensed/` in any skill body link or
   example — it ships into `.augment/skills/` and breaks consumer
   resolution. See `rule-writing` § 3b for the canonical reference.
 

package/.agent-src/skills/skill-writing/evals/triggers.json

@@ -9,7 +9,7 @@
     {"q": "add a proper procedure section to the graphql skill", "trigger": true},
     {"q": "refactor my PHP controller", "trigger": false},
     {"q": "run the skill linter on my branch", "trigger": false},
-    {"q": "compress this SKILL.md to half its length", "trigger": false},
+    {"q": "condense this SKILL.md to half its length", "trigger": false},
     {"q": "which skill handles git workflow?", "trigger": false},
     {"q": "write a CONTRIBUTING.md for this repo", "trigger": false}
   ]

package/.agent-src/skills/token-optimizer/SKILL.md

@@ -82,11 +82,11 @@ INTENT
 
 | Asset | Path | Trigger keywords | What it does |
 |---|---|---|---|
-| `cli-output-handling` | `.agent-src.uncompressed/rules/cli-output-handling.md` | `verbose`, `tail`, `grep`, `CLI` | Wrap-tail-grep contract for any verbose command |
-| `rtk-output-filtering` | `.agent-src.uncompressed/skills/rtk-output-filtering/SKILL.md` | `rtk`, `verbose`, `filter`, `wrap` | Project-local rtk filters; wrapper command |
-| `token-efficiency` | `.agent-src.uncompressed/rules/token-efficiency.md` | `redirect`, `verbose`, `concise`, `tool` | Batch + parallelize tool calls; brevity floor |
+| `cli-output-handling` | `.agent-src.uncondensed/rules/cli-output-handling.md` | `verbose`, `tail`, `grep`, `CLI` | Wrap-tail-grep contract for any verbose command |
+| `rtk-output-filtering` | `.agent-src.uncondensed/skills/rtk-output-filtering/SKILL.md` | `rtk`, `verbose`, `filter`, `wrap` | Project-local rtk filters; wrapper command |
+| `token-efficiency` | `.agent-src.uncondensed/rules/token-efficiency.md` | `redirect`, `verbose`, `concise`, `tool` | Batch + parallelize tool calls; brevity floor |
 | `agent-handoff` | `.claude/skills/agent-handoff/SKILL.md` | `handoff`, `fresh`, `chat`, `context` | Context envelope for fresh-chat continuation |
-| `direct-answers` | `.agent-src.uncompressed/rules/direct-answers.md` | `brevity`, `flattery`, `severity`, `tiered` | Iron-Law brevity floor (kernel) |
+| `direct-answers` | `.agent-src.uncondensed/rules/direct-answers.md` | `brevity`, `flattery`, `severity`, `tiered` | Iron-Law brevity floor (kernel) |
 | `markitdown` | upstream: github.com/microsoft/markitdown | `PDF`, `DOCX`, `HTML`, `convert` | Document → markdown converter (authoritative-link only) |
 | `/cost:report` | TBD — `road-to-ruflo-adoption.md § P1.2` | `cost`, `model spend`, `budget` | Per-session cost telemetry (planned) |
 

package/.agent-src/skills/unit-economics-modeling/SKILL.md

@@ -91,7 +91,7 @@ Do NOT use for full-business intrinsic-value modeling, OKR setting, funnel-stage
 1. **Burn multiple** = `net burn / net new ARR` over the fiscal-period
    slot's reporting window (monthly close / quarterly / annual).
    It answers *"how many dollars of cash do we burn to add one
-   dollar of recurring revenue?"* — a single ratio that compresses
+   dollar of recurring revenue?"* — a single ratio that condenses
    CAC, gross margin, and churn into capital efficiency.
 2. Compute on **net** new ARR (gross new − churn − contraction).
    Burn-multiple on gross new ARR flatters the picture by exactly

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

@@ -50,7 +50,7 @@ shared `agent-config` package — with correct file placement, quality gates, an
 - **Universality first** — the contribution must work for ALL consumers, not just one project
 - **Generalize when possible** — project-specific content CAN become universal with adaptation
 - **Evidence-based** — learnings must have occurred 2+ times or be clearly generalizable
-- **Complete pairs** — both uncompressed and compressed versions required
+- **Complete pairs** — both uncondensed and condensed versions required
 - **Quality verified** — must pass linter before PR creation
 - **Local benefit immediately** — use override for instant project benefit while PR is pending
 
@@ -87,12 +87,12 @@ Before ANY upstream work (branch, files, PR), ask the user:
 
 ### 1. Determine contribution type
 
-| Type | Uncompressed path | Compressed path |
+| Type | Uncondensed path | Condensed path |
 |---|---|---|
-| **New skill** | `.agent-src.uncompressed/skills/{name}/SKILL.md` | `.augment/skills/{name}/SKILL.md` |
-| **New rule** | `.agent-src.uncompressed/rules/{name}.md` | `.augment/rules/{name}.md` |
-| **New command** | `.agent-src.uncompressed/commands/{name}.md` | `.augment/commands/{name}.md` |
-| **New guideline** | `.agent-src.uncompressed/guidelines/{category}/{name}.md` | `.augment/guidelines/{category}/{name}.md` |
+| **New skill** | `.agent-src.uncondensed/skills/{name}/SKILL.md` | `.augment/skills/{name}/SKILL.md` |
+| **New rule** | `.agent-src.uncondensed/rules/{name}.md` | `.augment/rules/{name}.md` |
+| **New command** | `.agent-src.uncondensed/commands/{name}.md` | `.augment/commands/{name}.md` |
+| **New guideline** | `.agent-src.uncondensed/guidelines/{category}/{name}.md` | `.augment/guidelines/{category}/{name}.md` |
 | **Update to existing** | Same path as original | Same path as original |
 
 ### 2. Apply locally as override (immediate benefit)
@@ -159,12 +159,12 @@ git checkout -b feat/skills/{name}  # or fix/rules/{name}, etc.
 
 Create both files:
 
-- **Uncompressed version** → `.agent-src.uncompressed/{type}/{name}` (full, verbose, human-readable)
-- **Compressed version** → `.augment/{type}/{name}` (token-efficient, preserving all code blocks,
+- **Uncondensed version** → `.agent-src.uncondensed/{type}/{name}` (full, verbose, human-readable)
+- **Condensed version** → `.augment/{type}/{name}` (token-efficient, preserving all code blocks,
   headings, frontmatter, validation, gotchas)
 
-For skills, the compressed version should be 40-60% shorter than uncompressed.
-For rules and commands, they are usually copied 1:1 (no compression).
+For skills, the condensed version should be 40-60% shorter than uncondensed.
+For rules and commands, they are usually copied 1:1 (no condensation).
 
 ### 5. Ensure file quality
 
@@ -179,10 +179,10 @@ The files must:
 
 ```bash
 python3 scripts/skill_linter.py --all          # 0 FAIL required
-python3 scripts/check_compression.py            # No errors for this file
-python3 scripts/compress.py --generate-tools    # Regenerate symlinks
-bash scripts/compress.sh --check                # .agent-src/ in sync with source
-bash scripts/compress.sh --check-hashes         # All hashes match
+python3 scripts/check_condensation.py            # No errors for this file
+python3 scripts/condense.py --generate-tools    # Regenerate symlinks
+bash scripts/condense.sh --check                # .agent-src/ in sync with source
+bash scripts/condense.sh --check-hashes         # All hashes match
 ```
 
 If not in the package repo, note that these checks will run in CI after the PR is created.
@@ -243,7 +243,7 @@ The shared version now replaces the local override.
 ## Output format
 
 1. Summary of what is being contributed (type, name, why)
-2. File contents for both uncompressed and compressed versions
+2. File contents for both uncondensed and condensed versions
 3. If working in the package repo: branch name, commit message, PR title
 4. If Option 3: copyable file blocks for the user to paste
 5. Reminder to clean up local override after upstream merge
@@ -252,7 +252,7 @@ The shared version now replaces the local override.
 
 - Agent in consumer project doesn't know the package repo URL — this skill provides it
 - Agent may try to edit `.augment/` in the consumer project — that's read-only (symlinked)
-- Agent may forget the compressed version — both are mandatory
+- Agent may forget the condensed version — both are mandatory
 - Agent may include project-specific references in the skill — must be universal
 - The `source` field in frontmatter must be `package`, not `project`
 - Agent may not have git access to the package repo — Option 3 handles this gracefully
@@ -263,7 +263,7 @@ The shared version now replaces the local override.
 - **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
+- Do NOT skip the condensed version — both files are mandatory
 - Do NOT forget to clean up the local override after upstream merge
 - Do NOT bypass quality gates — they exist for a reason
 - Do NOT assume consent from a previous contribution — ask every time

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

@@ -31,3 +31,4 @@
 3. **Where do I edit agent-config?** — Do not edit `.augment/` or `.agent-src/` here; they are installed artifacts. Project edits live in `agents/` and project source.
 4. **Lint / test / sync entry point?** — Project-specific (see project README); agent-config reinstalls via `composer update event4u/agent-config` or `npm update @event4u/agent-config`.
 5. **Where do the always-active rules live?** — `.agent-src/rules/` (kernel = 9 Iron-Law rules; tier-1 / tier-2 routed via `.agent-src/router.json`).
+6. **Per-module agent docs?** — If `modules.enabled: true`, each module under `modules.root_paths` may carry its own `{agent_folder}/` (default `agents/`). See `module-management` skill.

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

@@ -143,7 +143,7 @@ chat_history:
   # Max file size in KB before overflow handling kicks in
   max_size_kb: 256
 
-  # Overflow behavior: rotate (drop oldest) | compress (summarize)
+  # Overflow behavior: rotate (drop oldest) | condense (summarize)
   on_overflow: rotate
 
 # --- Work-engine hooks ---
@@ -209,6 +209,16 @@ pipelines:
 # response — that cadence is governed by `roadmap-progress-sync` and
 # is non-negotiable. This setting only governs *quality tool runs*.
 roadmap:
+  # Skip the /roadmap:process-* pre-run confirmation gate (true, false).
+  #   true  = default. Command name names the scope; a discoverable single
+  #           active roadmap (or a named one) starts the loop immediately,
+  #           resolved config surfaced inline so a wrong pick can still be
+  #           aborted mid-stream.
+  #   false = legacy. Shows the pre-run summary with numbered options and
+  #           waits. Gate is still shown regardless when the roadmap is
+  #           ambiguous or a scope / cadence conflict has no default.
+  skip_pre_run_gate: true
+
   # When to run quality tools during /roadmap:process-step|phase|full.
   #   end_of_roadmap = once, before archiving (default — fastest, fewest tokens)
   #   per_phase      = once after every completed phase
@@ -385,18 +395,18 @@ verbosity:
   # safe task per Phase 10.3.
   taskfile_command_echo: false
 
-# --- Caveman speak (authoring-only) ---
+# --- Telegraph speak (authoring-only) ---
 #
-# Caveman-style compression scope for newly authored prose. The
-# compile-time toggle (`caveman.speak`) is added in Phase 8.
+# Telegraph-style condensation scope for newly authored prose. The
+# compile-time toggle (`telegraph.speak`) is added in Phase 8.
 # `speak_scope` lands now so the charter and consumers can pin it.
-caveman:
-  # speak_scope = how widely caveman-speak grammar applies in chat
-  #   off          = no caveman grammar in output (compile-time still
-  #                  governed by caveman.speak)
-  #   prose_only   = caveman in body prose; numbered options +
+telegraph:
+  # speak_scope = how widely telegraph-speak grammar applies in chat
+  #   off          = no telegraph grammar in output (compile-time still
+  #                  governed by telegraph.speak)
+  #   prose_only   = telegraph in body prose; numbered options +
   #                  Iron-Law-literal blocks stay full prose
-  #   aggressive   = caveman everywhere except Iron-Law literals
+  #   aggressive   = telegraph everywhere except Iron-Law literals
   speak_scope: prose_only
 
 telemetry:
@@ -430,7 +440,7 @@ Personal and project-level settings (initial file written by
 **Key paths use dot-notation** to denote nesting: `personal.user_name`
 lives under `personal:` in YAML.
 
-The `verbosity.*` and `caveman.speak_scope` rows are summarized below;
+The `verbosity.*` and `telegraph.speak_scope` rows are summarized below;
 the canonical narrative lives in
 [`docs/customization.md` § Verbosity](../../docs/customization.md#verbosity).
 
@@ -453,7 +463,7 @@ the canonical narrative lives in
 | `chat_history.enabled` | `true`, `false` | `true` | Persist chat events to `agents/runtime/.agent-chat-history` (JSONL) for crash recovery. |
 | `chat_history.frequency` | `per_turn`, `per_phase`, `per_tool` | per profile | Logging granularity. Defaults: `minimal`→`per_turn`, `balanced`→`per_phase`, `full`→`per_tool`. |
 | `chat_history.max_size_kb` | integer | per profile | Max file size before overflow handling. Defaults: `minimal`→`128`, `balanced`→`256`, `full`→`512`. |
-| `chat_history.on_overflow` | `rotate`, `compress` | per profile | On overflow: `rotate` drops oldest entries; `compress` marks the file for summarization on the next turn. Defaults: `minimal`/`balanced`→`rotate`, `full`→`compress`. |
+| `chat_history.on_overflow` | `rotate`, `condense` | per profile | On overflow: `rotate` drops oldest entries; `condense` marks the file for summarization on the next turn. Defaults: `minimal`/`balanced`→`rotate`, `full`→`condense`. |
 | `chat_history.text_limits.{user,agent,tool,phase}` | integer (chars) | `user=0`, `agent=5000`, `tool=200`, `phase=200` | Per-entry-type text-length cap. `0` = verbatim, no slice. `N > 0` = collapse whitespace, slice to N chars, append `" … [+K chars]"` so the log self-reports truncation. Defaults match `DEFAULT_TEXT_LIMITS` in `scripts/chat_history.py`. |
 | `hooks.enabled` | `true`, `false` | `false` | Master switch for the work-engine hook layer. When `false` (default) the registry stays empty and golden replay is byte-stable. See [`agents/settings/contexts/work-engine-hooks.md`](../../../agents/settings/contexts/work-engine-hooks.md). |
 | `hooks.trace` | `true`, `false` | `false` | Emit per-event trace lines on stderr. Useful for debugging; off by default because it is noisy. |
@@ -463,6 +473,7 @@ the canonical narrative lives in
 | `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via a 16-char session fingerprint, no ownership/sidecar layer. |
 | `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
+| `roadmap.skip_pre_run_gate` | `true`, `false` | `true` | When `true` (default): `/roadmap:process-step\|phase\|full` skips the interactive pre-run summary and starts immediately — resolved roadmap / cadence / council surfaced inline so an unwanted pick can still be aborted. When `false`: shows the pre-run summary with numbered options and waits. Gate is always shown — regardless of this flag — when the roadmap is ambiguous (multiple active, none named) or a scope / cadence conflict has no default. |
 | `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap:process-step|phase|full` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
 | `quality.local_auto_run` | `true`, `false` | `true` | When `true`: agent runs the project's quality pipeline (`task ci`, `make test`, `npm run check`, PHPStan, ECS, Rector, test suites) autonomously when work is ready for verification. When `false`: agent asks before running locally. **Carve-out**: NEW CI gates / smoke tests / test files MUST run locally regardless of this flag — without execution the new gate is unverified evidence. Iron Law `verify-before-complete` still applies; suppressed runs require the agent to surface the gap before claiming completion. |
 | `quality.wait_for_remote_ci` | `true`, `false` | `false` | When `true`: after `git push`, the agent polls GitHub check-runs / pipeline status on the PR and reports green / red before handing back. When `false`: agent pushes and hands back immediately; the user inspects CI themselves (default — saves agent runtime and tokens). |
@@ -486,7 +497,7 @@ the canonical narrative lives in
 | `verbosity.offer_council_in_delivery` | `true`, `false` | `false` | Offer "run AI Council on this?" inside delivery commands (`/feature-plan`, `/review-changes`, `/roadmap-create`). Council commands themselves are unaffected. |
 | `verbosity.post_action_reports` | `off`, `minimal`, `full` | `minimal` | Multi-line status / summary blocks after a successful action. `off` = no report; `minimal` = one-line confirmation; `full` = bullet list. |
 | `verbosity.intent_announcements` | `true`, `false` | `false` | Intent announcements ("Let me check…", "Now I will…", "Found it") in skill bodies. `false` = act and emit the result. |
-| `caveman.speak_scope` | `off`, `prose_only`, `aggressive` | `prose_only` | How widely caveman-speak grammar applies in chat. `off` = no caveman grammar; `prose_only` = caveman in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = caveman everywhere except Iron-Law literals. Compile-time toggle (`caveman.speak`) lands in Phase 8. |
+| `telegraph.speak_scope` | `off`, `prose_only`, `aggressive` | `prose_only` | How widely telegraph-speak grammar applies in chat. `off` = no telegraph grammar; `prose_only` = telegraph in body prose, numbered options + Iron-Law-literal blocks stay full prose; `aggressive` = telegraph everywhere except Iron-Law literals. Compile-time toggle (`telegraph.speak`) lands in Phase 8. |
 | `telemetry.artifact_engagement.enabled` | `true`, `false` | `false` | Master switch for the artefact engagement log. Default-off; zero file IO and zero token cost when `false`. Maintainer-targeted; consumers leave it off. |
 | `telemetry.artifact_engagement.granularity` | `task`, `phase-step`, `tool-call` | `task` | Boundary at which events are recorded. `tool-call` is expensive — opt-in only. |
 | `telemetry.artifact_engagement.record.consulted` | `true`, `false` | `true` | When `true`: record artefacts loaded into context. |

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -8,7 +8,7 @@
 #   1. Package defaults (shipped by event4u/agent-config)
 #   2. ~/.event4u/agent-config/agent-settings.yml — user-global DX-comfort
 #      defaults (whitelist: name, ide, cost_profile, personal.bot_icon,
-#      personal.autonomy, caveman.speak_scope). Created on opt-in via
+#      personal.autonomy, telegraph.speak_scope). Created on opt-in via
 #      /onboard; project-local files always win. Legacy
 #      ~/.config/agent-config/agent-settings.yml is read as a fallback.
 #   3. This file (.agent-project-settings.yml) — team defaults
@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.py (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "3.1.1"
+agent_config_version: "4.1.0"
 
 # --- Project identity ---
 project:
@@ -55,6 +55,65 @@ project:
   # "zend-laminas", "multi" (polyglot monorepo).
   stack: ""
 
+# --- Modules (optional) ---
+#
+# Module-aware skills and commands (`module-management`, `/module
+# explore`, `/module create`, roadmap-writing) consult this block to
+# discover where modules live, which namespace template they use, and
+# whether per-module `agents/` folders ship contexts the agent should
+# auto-load. When `modules.enabled` is false (default), every
+# module-aware surface skips its module branch — the project is
+# treated as a flat repo.
+#
+# Populated automatically by `scripts/install.py` on a fresh install
+# when an `app/Modules/`, `src/modules/`, `packages/`, `internal/`, or
+# similar shape is detected. Set manually for custom layouts. Lockable
+# via `locked_keys: [modules.root_paths]` for compliance-critical
+# repos where the module layout must not drift.
+modules:
+  # Opt-in flag. When false, module-aware skills behave as if the
+  # block were absent — no enumeration, no auto-context-load. Flip to
+  # true once `root_paths` is populated and the team has agreed on the
+  # layout.
+  enabled: false
+
+  # Repo-relative paths to module root directories. Multiple entries
+  # supported for polyglot repos (e.g. `[app/Modules, packages]` for a
+  # Laravel + JS monorepo). Each subdirectory under a root path is a
+  # module unless its name is in `skip_dirs`. Examples by stack:
+  #   Laravel HMVC          → [app/Modules]
+  #   Symfony DDD-lite      → [src]
+  #   Node monorepo         → [packages]
+  #   Python src layout     → [src]
+  #   Go internal layout    → [internal]
+  root_paths: []
+
+  # Namespace template used when generating files for a new module.
+  # `{ModuleName}` is replaced with the module's directory name.
+  # Empty when the stack does not use a PHP-style namespace (Node,
+  # Python, Go). Examples:
+  #   Laravel HMVC          → "App\\Modules\\{ModuleName}\\App"
+  #   Symfony DDD-lite      → "App\\{ModuleName}"
+  namespace_template: ""
+
+  # Per-module agent docs directory name. The agent looks for this
+  # folder under every module to auto-load `contexts/*.md` when the
+  # user enters the module via `/module explore <Name>`. Override
+  # only if your project already uses a different convention.
+  agent_folder: "agents"
+
+  # Directory names skipped during module enumeration. Template
+  # scaffolds and example modules should not show up as real modules.
+  skip_dirs: [".module-template", ".example"]
+
+  # On-the-fly detection acknowledgement. The `module-detect-on-the-fly`
+  # skill flips this to `true` once the agent has asked the user whether
+  # detected module candidates should be enabled — regardless of the
+  # answer. Prevents repeated nagging on subsequent sessions when the
+  # user said "not now". Re-detection still runs if a new root appears
+  # outside the previously surfaced set.
+  detection_acknowledged: false
+
 # --- Memory layer (optional) ---
 #
 # Opt-in signal for the @event4u/agent-memory companion package and

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

@@ -1,14 +1,14 @@
 # Command Template
 
-> Template for creating new commands in `.agent-src.uncompressed/commands/{command-name}.md`.
+> Template for creating new commands in `.agent-src.uncondensed/commands/{command-name}.md`.
 
 ## Instructions
 
-1. Create file: `.agent-src.uncompressed/commands/{command-name}.md`
+1. Create file: `.agent-src.uncondensed/commands/{command-name}.md`
 2. Copy the template below
 3. Replace all `{placeholders}` with actual content
 4. Remove all `<!-- comments -->` when done
-5. Run: `python3 scripts/skill_linter.py .agent-src.uncompressed/commands/{command-name}.md`
+5. Run: `python3 scripts/skill_linter.py .agent-src.uncondensed/commands/{command-name}.md`
 6. Sync: `task sync` (regenerates `.agent-src/` and `.augment/`)
 7. Generate Claude symlink: `task generate-tools` (or manually create symlink)
 
@@ -49,7 +49,7 @@ suggestion:
 
 {One-line summary of what this command does.}
 
-**Source of truth:** `.agent-src.uncompressed/` — never read or edit `.agent-src/` or `.augment/` directly.
+**Source of truth:** `.agent-src.uncondensed/` — never read or edit `.agent-src/` or `.augment/` directly.
 
 ## Steps
 
@@ -97,7 +97,7 @@ Before considering a command complete:
 
 - [ ] **Frontmatter**: has `name`, `description`, `disable-model-invocation: true`, `suggestion` block
 - [ ] **Steps**: numbered sub-headings (`### 1.`, `### 2.`, ...)
-- [ ] **Source of truth**: works on `.agent-src.uncompressed/`, not `.agent-src/` or `.augment/`
+- [ ] **Source of truth**: works on `.agent-src.uncondensed/`, not `.agent-src/` or `.augment/`
 - [ ] **No auto-apply**: presents findings, asks before destructive changes
 - [ ] **Linter passes**: `python3 scripts/skill_linter.py` reports 0 FAIL
 - [ ] **English only**: all content in English

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

@@ -1,6 +1,6 @@
 # Context Template
 
-Templates for context documents stored in `agents/settings/contexts/` or `app/Modules/{Module}/agents/settings/contexts/`.
+Templates for context documents stored in `agents/settings/contexts/` or `{module_root}/{Module}/{agent_folder}/settings/contexts/` (resolved via `modules.root_paths` + `modules.agent_folder` in `.agent-project-settings.yml`; Laravel example: `app/Modules/{Module}/agents/settings/contexts/`).
 
 A **context document** captures the architectural understanding of a codebase area — its structure,
 key classes, patterns, dependencies, and conventions. It's a snapshot of knowledge that helps

package/.agent-src/templates/copilot-instructions.md

@@ -102,7 +102,7 @@ This repository contains {{project_description_oneline}}.
 ## ✅ Known False Positives — Do NOT Flag
 
 The repo ships agent-config rules and skills under `.augment/`,
-`.agent-src/`, and (during authoring) `.agent-src.uncompressed/`.
+`.agent-src/`, and (during authoring) `.agent-src.uncondensed/`.
 Cross-references inside those trees resolve via the **delivered**
 `.augment/` layout — not via raw git checkout. Copilot's static
 checker walks the git tree, so it sees broken paths where there are
@@ -116,7 +116,7 @@ resolve at agent runtime. The patterns below are correct by design:
   delivered location (e.g. `.augment/rules/<rule>.md`) — these paths
   are valid via the `.augment/` tree, even when the file is symlinked
   into `.claude/rules/`, `.cursor/rules/`, or `.clinerules/`.
-- **`path_prefix:` triggers containing `.agent-src.uncompressed/`**
+- **`path_prefix:` triggers containing `.agent-src.uncondensed/`**
   in YAML frontmatter. This is a literal match pattern for the
   host's router, **not** a file reference — source-of-truth meta-rules
   (`augment-source-of-truth`, `augment-edit-discipline`, `skill-quality`,
@@ -127,15 +127,15 @@ resolve at agent runtime. The patterns below are correct by design:
   `.augment/skills/`, `.augment/commands/` via installer-managed
   symlinks. Missing-file reports here are renderer artifacts.
 - **Body-link forms `../docs/guidelines/...`** (single-up). This is
-  the post-rewrite shape produced by `scripts/compress.py`. The
-  compressed `.agent-src/rules/` tree is one level deeper than the
-  source `.agent-src.uncompressed/rules/`, so the rewriter collapses
+  the post-rewrite shape produced by `scripts/condense.py`. The
+  condensed `.agent-src/rules/` tree is one level deeper than the
+  source `.agent-src.uncondensed/rules/`, so the rewriter collapses
   `../../docs/...` to `../docs/...`. Both forms are expected — one in
-  source, one in compressed output.
+  source, one in condensed output.
 
 **What TO flag:** code defects, security issues, broken tests, type
-errors, and any new `.agent-src.uncompressed/` substring introduced
-into `.agent-src/rules/` body content (the `check-compressed-paths`
+errors, and any new `.agent-src.uncondensed/` substring introduced
+into `.agent-src/rules/` body content (the `check-condensed-paths`
 task gates this — flag it as a regression if it slips through).
 
 ## ✅ Code Review Comment Behavior

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

@@ -1,6 +1,6 @@
 # Feature Planning Template
 
-Templates for feature plan files stored in `agents/features/` or `app/Modules/{Module}/agents/features/`.
+Templates for feature plan files stored in `agents/features/` or `{module_root}/{Module}/{agent_folder}/features/` (resolved via `modules.root_paths` + `modules.agent_folder` in `.agent-project-settings.yml`; Laravel example: `app/Modules/{Module}/agents/features/`).
 
 ---