@event4u/agent-config 3.3.0 → 4.2.0

package/.agent-src/skills/condense-memory/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: condense-memory
+description: "Use when shrinking always-loaded memory files (AGENTS.md, CLAUDE.md, .cursorrules) via telegraph grammar — refuses sensitive paths, round-trips via .original.md backup."
+source: package
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: [Bash]
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
+---
+
+# condense-memory
+
+> **Experimental.** Output-side telegraph dialect did not meet kill-criterion in [`internal/bench/reports/telegraph-v1.md`](../../../bench/reports/telegraph-v1.md) (`vs_terse` median −9.27 %). Input-side memory condensation is orthogonal use case: savings target always-loaded memory budget, not reply stream. Treat ship-criterion as **per-target measurement**, not v1 verdict.
+
+## When to use
+
+Use when:
+
+- Always-loaded memory file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`) close to or above host tool's char budget and maintainer wants to recover input-token headroom.
+- Consumer-shipped `templates/AGENTS.md` failing `agents-md-thin-root` cap and pointer-extraction options exhausted.
+- Maintainer asks to "condense this memory file" or "shrink AGENTS.md" or names input-side telegraph.
+
+## Do NOT
+
+- Condense reply, commit message, PR body, ticket summary, or any deliverable written *for* human reader — those are carve-outs in [`telegraph-speak § Carve-outs`](../../rules/telegraph-speak.md) and stay verbatim.
+- Condense path matching sensitive-file denylist (`.env*`, `.netrc`, `credentials*`, `secrets*`, `id_rsa*`, `*.pem|key|p12|pfx|crt|cer|jks`, `.ssh/*`) — script refuses with `SensitivePathError` and so should you.
+- Condense generated file (`.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`) — edit source in `.agent-src.uncondensed/` and regenerate via package's sync + generate-tools scripts (`scripts/condense.sh --sync` + `scripts/condense.py --generate-tools`).
+- Hand-edit condensed memory file in place — run `--decondense` first; next condense pass refuses on body-hash drift (`CondensationRefused`).
+- Commit condensed file without committing matching `.original.md` backup — round-trip breaks otherwise.
+
+## Procedure
+
+1. **Analyse target first.** Before any write, **inspect** target with `view` or `wc -l` to confirm it is always-loaded memory file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`), not generated, and has prose paragraphs to condense (pointer-only Thin-Root file may net near-zero). Skip rest of procedure if any check fails.
+2. **Check denylist gate.** Run `python3 scripts/condense_memory.py <path> --check` — exit 0 = safe; exit 2 = denylist hit, stop and surface refusal.
+3. **Record baseline.** `wc -c <path>` — capture pre-condensation char count for commit message.
+4. **Condense.** `python3 scripts/condense_memory.py <path>`. Script writes `<path>.original.md` (verbatim backup) and rewrites `<path>` with `original_sha256:` + `condensed_at:` frontmatter.
+5. **Inspect diff.** Eyeball every Iron-Law fence, numbered-options block, code fence, backtick span, `❌`/`⚠️`/`✅` line, and frontmatter pair — all must be byte-identical. Body prose may have lost articles (`the`/`a`/`an`) and auxiliaries (`is`/`are`/`was`/`be`/`that`/`which`).
+6. **Validate idempotency.** Re-run `python3 scripts/condense_memory.py <path>` — clean re-run is no-op (body hash matches). Non-zero exit = stop, escalate.
+7. **Commit both files together.** `<path>` and `<path>.original.md` ship as pair. Backup is rollback path; never commit one without other.
+8. **Rollback path.** If readability fails review at step 5: `python3 scripts/condense_memory.py <path> --decondense` restores backup and deletes `.original.md`.
+
+## Output format
+
+Maintainer-facing report after invoking script MUST contain, in this order:
+
+1. **Diff line** — pre/post `wc -c` as single line (`AGENTS.md: 2,891 → 2,453 chars (−15.1 %)`).
+2. **Backup path** — full path of `.original.md` backup so maintainer can verify it landed on disk.
+3. **Carve-out check** — one line confirming seven carve-out classes round-tripped (`carve-outs: 7 classes preserved · idempotent re-run: clean`).
+4. **Exit-code surface** — on failure, surface verbatim exit code and exception name (`SensitivePathError → exit 2`, `CondensationRefused → exit 3`, `FileNotFoundError → exit 4`); do not paraphrase.
+
+Do **not** narrate algorithm, grammar rules, or carve-out theory — rule and this skill document contract; output reports result.
+
+## Carve-outs — byte-for-byte preserved
+
+Mirrors seven carve-out classes in [`telegraph-speak`](../../rules/telegraph-speak.md). Condensation engine in [`scripts/condense_memory.py`](../../../scripts/condense_memory.py) preserves:
+
+1. **Triple-backtick fences** — any language, any depth.
+2. **Numbered-options lines** — `^>?\s*\d+\.\s` plus `**Recommendation:**` / `**Empfehlung:**` label.
+3. **Backtick spans** — file paths, command names, identifiers inside body prose.
+4. **Status / error markers** — lines starting with `❌`, `⚠️`, `✅`.
+5. **Iron-Law ALL-CAPS lines** — `^[A-Z][A-Z0-9 ,.\-_/']{3,}$`.
+6. **Frontmatter blocks** — `---` fence pairs at head of file.
+7. **Mode markers** per [`role-mode-adherence`](../../rules/role-mode-adherence.md).
+
+Mangling any of these breaks Iron-Law surface host tool reads. Unit tests in `tests/test_condense_memory.py` lock each carve-out class as regression case.
+
+## Idempotency contract — Step 9 guard
+
+Script is **idempotent on clean re-runs**: running it twice on same target is no-op because body hash matches recondensed hash. Script **refuses** on **body drift**:
+
+| State | Outcome |
+|---|---|
+| No frontmatter SHA marker | Condense + write backup + inject SHA. |
+| SHA marker present, body re-condenses to same hash | No-op (return target unchanged). |
+| SHA marker present, body hash diverged | **Refuse** with `CondensationRefused` exit 3. |
+
+If you need to edit condensed memory file, run `--decondense` first, edit restored `.original.md` content, then re-run condenseor. Never hand-edit condensed body — next CI run will either silently corrupt your edit (if it happens to re-condense to same shape) or hard-fail next condense pass.
+
+## Sensitive-path gate
+
+Every read path passes through [`scripts/validate_safe_paths.py`](../../../scripts/validate_safe_paths.py) `assert_safe()` before bytes leave disk. Gate is security floor for Phase 2 (input-side condensation) per `step-16-telegraph-substance.md` Phase 0; rollback of gate is rollback of this skill.
+
+CLI exit codes:
+
+- `0` — condense / decondense / check succeeded.
+- `2` — `SensitivePathError` (path matched denylist).
+- `3` — `CondensationRefused` (body hash diverged from frontmatter SHA).
+- `4` — `FileNotFoundError` (no `.original.md` backup to restore).
+
+## Gotchas
+
+- **Body-hash drift after manual edit** — hand-editing condensed body breaks `original_sha256:` invariant. Next condense pass refuses with `CondensationRefused` (exit 3). Recovery: `--decondense`, edit restored body, re-condense.
+- **`.original.md` backup missing on `--decondense`** — exit 4 (`FileNotFoundError`). Either someone deleted backup or `--decondense` already ran. Restore from git history; never regenerate backup by hand (regenerated content would not be byte-identical).
+- **Denylist false positive** — sensitive-looking filename outside denylist surface (project-specific naming) will still pass `assert_safe()`. Denylist necessary but not sufficient; maintainer responsible for never feeding secrets to condenseor.
+- **Frontmatter ordering with existing keys** — if target already has frontmatter, condenseor preserves existing keys, drops any prior `original_sha256:` / `condensed_at:` entries, and appends new pair. Other agents reading file should treat SHA + timestamp pair as canonical condensation marker, not file size.
+- **Negative savings on pointer-heavy files** — `templates/AGENTS.md` already following Thin-Root (≥ 40 % pointers, ≥ 60-char *why*-clauses) has little prose left to drop; condensation may net near-zero or even add bytes via frontmatter. Run [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) first to maximise pointer share, then measure whether this skill still pays.
+- **Generated-tree drift** — condensing `.agent-src.uncondensed/templates/AGENTS.md` does NOT propagate to `.augment/`, `.claude/`, etc. until package's sync + generate-tools scripts run (`scripts/condense.sh --sync` + `scripts/condense.py --generate-tools`). Always regenerate after condensing templated file.
+
+## Measurement — when to condense
+
+No published `telegraph-v2` baseline for input-side savings yet (Step 11 of `step-16-telegraph-substance.md` ships that). Until then, maintainer judges per-target whether condensation pays its readability cost. Suggested workflow:
+
+1. `wc -c <path>` before — record baseline char count.
+2. `python3 scripts/condense_memory.py <path>` — condense + back up.
+3. `wc -c <path>` after — record post-condensation char count.
+4. Eyeball diff: does prose stay legible? Are all Iron-Law fences intact?
+5. If yes → commit both `<path>` and `<path>.original.md`. If no → `--decondense`.
+
+Future `telegraph-v2.md` will tabulate realised input-token saving against `agents-md-thin-root` 40 % pointer-ratio constraint so maintainer has numerical floor.
+
+## Cross-references
+
+- [`telegraph-speak`](../../rules/telegraph-speak.md) — runtime rule script mirrors for input-side targets; `telegraph.speak_scope` does **not** gate this script (input-side runs regardless).
+- [`scripts/validate_safe_paths.py`](../../../scripts/validate_safe_paths.py) — Phase 0 gate; ported from upstream Telegraph `63a91ec`.
+- [`scripts/condense_memory.py`](../../../scripts/condense_memory.py) — implementation.
+- [`tests/test_condense_memory.py`](../../../tests/test_condense_memory.py) — regression locks for each carve-out + idempotency + denylist.
+- [`docs/contracts/condensation-default-kill-criterion.md`](../../../docs/contracts/condensation-default-kill-criterion.md) — v1 verdict (output-side; informs but does not gate this skill).
+- [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) — caps consumer-shipped `templates/AGENTS.md`; this skill is one tool to land under cap.

package/.agent-src/skills/context-authoring/SKILL.md

@@ -51,7 +51,7 @@ Do NOT use when:
 | `deployment-order.md` | Migration strategy, feature flags, rollback plan | `migration-safety`, `judge-bug-hunter`, release reviewers |
 | `observability.md` | Error tracking, log channels, metrics, known alerts | deploy reviewers, `bug-analyzer`, incident mode |
 
-The templates ship in `.agent-src.uncompressed/templates/contexts/` and are
+The templates ship in `.agent-src.uncondensed/templates/contexts/` and are
 copied into `agents/settings/contexts/` by the installer.
 
 ## Procedure: context-authoring
@@ -163,7 +163,7 @@ has to confirm or correct, not invent from scratch.
 If the context file declares its own `load_context:` (chain reasoning),
 use logical names rooted at the source — `contexts/<area>/<file>.md`
 for package material or `agents/settings/contexts/<file>.md` for project-local
-material. The `.agent-src.uncompressed/` prefix is rejected by the
+material. The `.agent-src.uncondensed/` prefix is rejected by the
 schema regex and by `scripts/lint_load_context.py`. Body links to
 `docs/guidelines/...` use the verbatim `../../docs/...` relative form.
 Canonical reference: `rule-writing` § 3b and

package/.agent-src/skills/context-document/SKILL.md

@@ -59,8 +59,10 @@ Unlike feature plans (future-focused) or roadmaps (task-focused), contexts are
 agents/settings/contexts/                         # Project-wide contexts
 ├── {context-name}.md
 
-app/Modules/{Module}/agents/settings/contexts/    # Module-scoped contexts
-├── {context-name}.md
+{module_root}/{Module}/{agent_folder}/settings/contexts/ # Module-scoped contexts
+├── {context-name}.md                                    # Laravel: app/Modules/…
+                                                         # Symfony: src/Bundle/…
+                                                         # Monorepo: packages/…
 
 .augment/templates/
 └── contexts.md                          # Context template
@@ -82,7 +84,7 @@ app/Modules/{Module}/agents/settings/contexts/    # Module-scoped contexts
 |---|---|
 | About the `.augment/` system itself | `.augment/contexts/` (shared package) |
 | Project-wide or cross-module | `agents/settings/contexts/` |
-| Module-specific | `app/Modules/{Module}/agents/settings/contexts/` |
+| Module-specific | `{module_root}/{Module}/{agent_folder}/settings/contexts/` (resolved via `modules.root_paths` + `modules.agent_folder`; Laravel example: `app/Modules/{Module}/agents/settings/contexts/`) |
 | If unsure | Ask the user |
 
 ### Shared vs. project-specific contexts

package/.agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -143,7 +143,7 @@ both. Instead, reference with a table:
 1. **Extract to `agents/`** — Move project-specific details to dedicated files in `agents/`
    and link from AGENTS.md (e.g., `agents/reference/docs/database-setup.md`, `agents/reference/docs/testing.md`)
 2. **Remove duplicates** — If content exists in `.augment/`, remove from AGENTS.md
-3. **Compress** — Turn verbose explanations into concise tables or bullet points
+3. **Condense** — Turn verbose explanations into concise tables or bullet points
 4. **Remove ECS/Rector-enforced rules** — From copilot-instructions.md (auto-fixed anyway)
 5. **Move examples to guidelines** — Detailed code examples belong in `.augment/guidelines/`
 
@@ -175,7 +175,7 @@ Before deduplicating, run three scans:
 
 Every hit from scan 1 is a 🔴 blocker: leaking another project's name
 into a consumer's own docs is the failure mode this skill exists to
-prevent. Fix or remove those BEFORE any dedup/compress work — there's
+prevent. Fix or remove those BEFORE any dedup/condense work — there's
 no point deduplicating content that is about to be rewritten.
 
 When the drift is severe (whole sections are wrong), recommend
@@ -193,7 +193,7 @@ it as "redundant" and never trim its bullets. The patterns it covers:
   (`../docs/guidelines/foo.md`, `../contexts/bar.md`) — paths resolve
   from the file's delivered location, not from the symlink in
   `.claude/rules/` etc. (per `road-to-path-fixes.md` Strategy A).
-- `path_prefix:` triggers containing `.agent-src.uncompressed/` —
+- `path_prefix:` triggers containing `.agent-src.uncondensed/` —
   literal match patterns, not file refs (per Modified Option 1,
   P2.2).
 - Symlinked rule files under `.claude/rules/`, `.cursor/rules/`,

package/.agent-src/skills/description-assist/SKILL.md

@@ -71,7 +71,7 @@ Report which checks pass / fail in one compact line — **not** a long essay.
 
 If the target is a skill, check for a trigger-eval report:
 
-* `.agent-src.uncompressed/skills/{name}/evals/triggers.json` — the expected-trigger corpus
+* `.agent-src.uncondensed/skills/{name}/evals/triggers.json` — the expected-trigger corpus
 * `evals/last-run.json` — the most recent runner output (see
   [`scripts/skill_trigger_eval.py`](../../../scripts/skill_trigger_eval.py))
 
@@ -132,7 +132,7 @@ counter-proposal.
 
 Only after the user picks:
 
-* Edit the frontmatter in `.agent-src.uncompressed/{kind}/{name}.{md,SKILL.md}`.
+* Edit the frontmatter in `.agent-src.uncondensed/{kind}/{name}.{md,SKILL.md}`.
 * Re-copy / re-sync as the target artifact's writing skill prescribes.
 * Run `python3 scripts/skill_linter.py {path}` — must report 0 FAIL.
 * Report the diff and exit.

package/.agent-src/skills/git-workflow/SKILL.md

@@ -132,7 +132,7 @@ git commit -m "<conventional commit message>"
 ```
 
 Interactive rebase only when the user wants per-commit control — it
-replays derived files (`.compression-hashes.json`, router projections)
+replays derived files (`.condensation-hashes.json`, router projections)
 per commit and conflicts on every replay.
 
 ### 4. Re-push in the SAME turn

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

@@ -56,7 +56,7 @@ Creating or materially rewriting a guideline **must** go through Understand
 * **Understand** — which skills or rules will cite this guideline? If the
   answer is "none", the guideline has no home — stop.
 * **Research** — **inspect** `docs/guidelines/` for overlap and grep
-  `.agent-src.uncompressed/` for pages that already cover the topic.
+  `.agent-src.uncondensed/` for pages that already cover the topic.
   **Analyze** 1–2 peer guidelines in the same topic folder for tone.
 * **Draft** — propose location (topic folder + filename) and outline. Only
   fill bodies once the outline is confirmed.
@@ -122,7 +122,7 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 
 * Run `python3 scripts/skill_linter.py docs/guidelines/{topic}/{name}.md`
   → 0 FAIL (guidelines have relaxed linting but must still parse).
-* Run `bash scripts/compress.sh --sync` → projects updates.
+* Run `bash scripts/condense.sh --sync` → projects updates.
 * Run `python3 scripts/check_references.py` → no broken links.
 * Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
   the script list) — must exit 0 except for tolerated warnings.
@@ -132,7 +132,7 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 1. Complete guideline at `docs/guidelines/{topic}/{name}.md`
 2. At least one skill or rule linking to it
 3. Linter + `check_references.py` clean
-4. `bash scripts/compress.sh --sync` confirmation
+4. `bash scripts/condense.sh --sync` confirmation
 
 ## Gotchas
 
@@ -170,7 +170,7 @@ to every guideline you author.
 * Do NOT add `type:` or `alwaysApply:` to the frontmatter
 * Do NOT embed numbered procedures — those belong in skills
 * Do NOT create an orphan guideline with no inbound links
-* Do NOT reintroduce `.agent-src.uncompressed/guidelines/` — relocated to `docs/guidelines/`
+* Do NOT reintroduce `.agent-src.uncondensed/guidelines/` — relocated to `docs/guidelines/`
 
 ## Cloud Behavior
 
@@ -189,7 +189,7 @@ validation:
   `docs/guidelines/{topic}/{name}.md` and run
   `task sync && task lint-skills && task check-refs` locally before
   committing.
-* Do not call the linter, ref-checker, or compressor — they only
+* Do not call the linter, ref-checker, or condenseor — they only
   run on the user's machine.
 
 ## Examples

package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -143,10 +143,10 @@ Run all four steps before declaring "no overlap":
 **Step 1 — list all four surfaces.** Directory taxonomy is free evidence:
 
 ```bash
-ls .agent-src.uncompressed/skills/ \
-   .agent-src.uncompressed/rules/ \
+ls .agent-src.uncondensed/skills/ \
+   .agent-src.uncondensed/rules/ \
    docs/guidelines/ \
-   .agent-src.uncompressed/commands/
+   .agent-src.uncondensed/commands/
 ```
 
 Sub-directories matter — `docs/guidelines/php/patterns/`, `docs/guidelines/agent-infra/`,
@@ -162,7 +162,7 @@ artifact may name the *symptom*, not the cure.
 | Problem-words | `discriminator`, `enum.*match`, `switch.*on`, `if.*else.*chain` |
 
 ```bash
-grep -rl -E "<solution-words>|<problem-words>" .agent-src.uncompressed/
+grep -rl -E "<solution-words>|<problem-words>" .agent-src.uncondensed/
 ```
 
 **Step 3 — taxonomy scan.** For any topic with a likely sub-folder

package/.agent-src/skills/lint-skills/SKILL.md

@@ -32,7 +32,7 @@ install:
 
 Use this skill when:
 
-- Validating the shape of every skill and rule in `.agent-src.uncompressed/`
+- Validating the shape of every skill and rule in `.agent-src.uncondensed/`
 - Verifying execution metadata (`execution.type`, `handler`, `command`) is well-formed
 - Checking locally before opening a PR that CI's skill-lint job will pass
 - Investigating a reported linter failure on a specific skill or rule
@@ -41,14 +41,14 @@ Do NOT use when:
 
 - Linting only one file — call `python3 scripts/skill_linter.py <path>` directly
 - Checking cross-references between files — use `check-refs` instead
-- Checking compression freshness — use `bash scripts/compress.sh --check` instead
+- Checking condensation freshness — use `bash scripts/condense.sh --check` instead
 
 ## Procedure
 
 ### 1. Inspect the environment
 
 Confirm `python3` is available and the working directory is the agent-config
-repository root — the linter expects to find `.agent-src.uncompressed/skills/`
+repository root — the linter expects to find `.agent-src.uncondensed/skills/`
 and related directories relative to `cwd`.
 
 ### 2. Dispatch via the runtime layer

package/.agent-src/skills/md-language-check/SKILL.md

@@ -31,8 +31,8 @@ install:
 
 Fire this skill **before** writing or saving any `.md` file under:
 
-- `.agent-src.uncompressed/` (source of truth — skills, rules, commands, guidelines, templates, contexts)
-- `.agent-src/` (compressed projection)
+- `.agent-src.uncondensed/` (source of truth — skills, rules, commands, guidelines, templates, contexts)
+- `.agent-src/` (condensed projection)
 - `.augment/` (local agent projection)
 - `agents/` (project-specific roadmaps, contexts, sessions)
 

package/.agent-src/skills/module-detect-on-the-fly/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: module-detect-on-the-fly
+description: "Use when editing a file under a module-shaped path (`Modules/*`, `packages/*`, `apps/*`, `internal/*`) while `modules.enabled` is `false` — asks the user once whether to enable the config."
+source: package
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
+---
+
+# module-detect-on-the-fly
+
+## When to use
+
+Fires the first time the agent edits, reads, or references a file
+inside a module-shaped path while the project has not yet opted into
+the module config. Goal: catch projects with real module structure
+that never ran `/agents init` or the GUI wizard, and offer to enable
+the config — once, without nagging.
+
+**Trigger heuristic** (any one):
+
+- The agent is about to edit a path matching `*/Modules/*`,
+  `*/app/Modules/*`, `*/packages/*/<non-noise>`, `*/apps/*/<non-noise>`,
+  `*/src/Module*/*`, or `*/internal/*/<non-noise>`.
+- The user names such a path in their request.
+- A `/module *` command runs while `modules.enabled` is `false`.
+
+**Hard gate** — skip the skill entirely when **any** of these hold:
+
+1. `modules.enabled` is `true` (already configured — use `module-management`).
+2. `modules.detection_acknowledged` is `true` (user already answered).
+3. The path matches a `_NOISE_SEGMENTS` entry (`vendor`, `node_modules`,
+   `dist`, `build`, etc.) — see `scripts/_lib/module_detection.py`.
+
+Confirm both flags via `get_modules_config()` before running detection.
+
+## Procedure
+
+1. **Detect** — call `detect_module_roots(project_root)` from
+   `scripts/_lib/module_detection.py`. Returns a list of
+   `ModuleCandidate` ordered `high → medium` confidence.
+2. **Bail early** — if the list is empty OR every candidate has
+   `confidence: "medium"` AND no candidate matches the path the agent
+   is currently working on, skip silently. (False positives nag worse
+   than missed detections.)
+3. **Surface once** — present a single numbered-options block:
+
+   ```text
+   Detected module-shaped structure not yet in config:
+   - app/Modules/  (laravel-hmvc, high confidence, 4 modules)
+   - packages/     (node-monorepo, medium confidence, 2 candidates)
+
+   1. Enable modules config — add detected paths to
+      `.agent-project-settings.yml` so module-aware skills activate.
+   2. Not now — silence this prompt for the project (you can revisit
+      via `/agents init` later).
+   3. Show details first — list the candidates with their stack guess
+      and per-module subdirs before deciding.
+
+   Recommendation: 1 when the high-confidence list matches your
+   intent. 2 when the layout is intentionally flat.
+   ```
+
+4. **Persist the choice**:
+
+   - **Option 1** — build the payload (matches `propose_modules_config.py
+     --json` shape, includes `detection_acknowledged: true`), pipe into
+     `python3 scripts/apply_modules_config.py --project <root>`.
+   - **Option 2** — run `python3 scripts/apply_modules_config.py
+     --project <root> --acknowledge-only`. Flips only the ack flag;
+     every other `modules.*` key stays untouched.
+   - **Option 3** — list candidates, then loop back to step 3.
+
+5. **Resume the original task** — never block work on the prompt. If
+   the user picks 2, treat the project as flat for the rest of the
+   session.
+
+## Output format
+
+1. One-paragraph note naming the detected paths + stack guess +
+   confidence per row.
+2. Single numbered-options block (1 = enable, 2 = silence,
+   3 = show details).
+3. After the user picks: the apply-script invocation that was run,
+   then resume the original task on the next turn.
+
+## Gotcha
+
+- **False positives nag worse than misses.** Only fire when
+  `is_module_like_path()` matches AND `detect_module_roots()` returns
+  a `high`-confidence candidate that overlaps the path the agent is
+  touching. Pure `medium`-only hits on unrelated paths → skip silently.
+- **Vendored trees mimic module shape.** `vendor/foo/Modules/Bar`,
+  `node_modules/*/packages/*`, `dist/Modules/*` — the noise filter in
+  `is_module_like_path()` already drops these, but never call
+  `detect_module_roots()` against a vendored sub-root.
+- **Maintainer dogfooding.** This repo (`event4u/agent-config`) ships
+  `packages/*/agents/` that look module-shaped. The repo's own
+  `.agent-project-settings.yml` sets `detection_acknowledged: true` to
+  silence the skill here.
+- **Intentional flat monorepos.** When `packages/*` is just a
+  vendoring directory for unrelated tools, option 2 is the right
+  answer and the skill must respect it permanently.
+
+## Do NOT
+
+- Do NOT background-scan. Detection only runs when the trigger
+  heuristic fires on a path the agent is actively touching.
+- Do NOT re-prompt once `modules.detection_acknowledged` is `true`.
+  Re-entry goes through `/agents init`, never automatic.
+- Do NOT auto-enable on a `high`-confidence match. The user has to
+  pick option 1 — the whole point is one explicit decision.
+- Do NOT commit or push the patched `.agent-project-settings.yml`.
+  Persistence writes the file only; staging is the user's call per
+  `commit-policy`.
+- Do NOT block the original task on the prompt. If the user ignores
+  the options block, continue the work and treat the project as flat
+  for the rest of the session.
+
+## See also
+
+- `module-management` — the active skill once modules are configured.
+- `scripts/_lib/module_detection.py` — `detect_module_roots()` +
+  `is_module_like_path()` helpers.
+- `scripts/apply_modules_config.py` — persistence with
+  `--acknowledge-only` for option 2.
+- `commands/agents/init.md` — the explicit re-entry point if the user
+  wants to revisit detection later.