@event4u/agent-config 2.26.0 → 3.0.0

package/.agent-src/contexts/augment-infrastructure.md

@@ -152,7 +152,7 @@ Each guideline has a consistent header with **Related Skills**, **Related Rules*
 |---|---|
 | `features.md` | `agents/features/` or module `agents/features/` |
 | `roadmaps.md` | `agents/roadmaps/` or module `agents/roadmaps/` |
-| `contexts.md` | `agents/contexts/` or module `agents/contexts/` |
+| `contexts.md` | `agents/settings/contexts/` or module `agents/settings/contexts/` |
 | `overrides/rule.md` | `agents/overrides/rules/` |
 | `overrides/skill.md` | `agents/overrides/skills/` |
 | `overrides/command.md` | `agents/overrides/commands/` |
@@ -164,7 +164,7 @@ Each guideline has a consistent header with **Related Skills**, **Related Rules*
 **Shared context documents** about the `.augment/` system itself.
 These help agents understand the infrastructure they operate in.
 
-Unlike project contexts (`agents/contexts/`), these are part of the shared package
+Unlike project contexts (`agents/settings/contexts/`), these are part of the shared package
 and describe the agent system, not the project's business domain.
 
 ## Key Principles

package/.agent-src/contexts/authority/scope-mechanics.md

@@ -91,6 +91,17 @@ User decides. Default: **3** when the current branch's name and scope match the
 
 **Failure mode — diverging stacked PRs.** Skipping the inventory and committing to the wrong base creates two PRs that should have been one stack: merge conflicts when the parent lands, rebase / force-push churn, duplicate review effort. The 30-second inventory cost up front beats hours of rebase reconciliation later.
 
+**Failure mode — opening a PR on a stale long-lived branch.** A pre-existing feature branch (e.g. `feat/X` last touched days ago) is still "the current branch" but its base — `main` — has moved on. Auto-generated artifacts (`agents/roadmaps-progress.md`, ownership matrices, compressed mirrors, hash files) are the canonical collision surface: any merged PR on `main` touched them, and the stale branch's copy is now a content conflict by construction. Opening a PR without fetching `main` first surfaces conflicts only after `gh pr create` has already published the broken PR.
+
+**Pre-PR freshness check — MANDATORY** (mirrored in [`/create-pr` Step 1b](../../commands/create-pr.md)). Before `gh pr create`:
+
+1. `git fetch origin {target-base} --quiet`.
+2. `git rev-list --count HEAD..origin/{target-base}` — commits behind base.
+3. Count > 0 AND another open PR targets the same base → STOP and ask: stack on top / wait for parent to land / merge-main-into-branch / proceed-anyway-and-accept-conflicts / cancel.
+4. Count > 0 AND no overlap → ask: merge-main / rebase / proceed-anyway / cancel.
+
+User decides. Never silently `gh pr create` on a branch that is behind its base.
+
 ## Decline = silence — context
 
 The right moment to ask is **before** the work starts (writing the

package/.agent-src/contexts/contracts/agents-md-anatomy.md

@@ -101,7 +101,7 @@ package edit touches the same hot file.
    inside backticks with no *why*-clause; collapse runs of three or
    more into a single capability pointer.
 4. **Outboard.** Move each `outboard-candidate` into
-   `agents/contexts/`, `docs/contracts/`, an existing rule body, or
+   `agents/settings/contexts/`, `docs/contracts/`, an existing rule body, or
    an existing skill body. Replace in-file with a substantive
    pointer. Never invent a new top-level dir.
 5. **Verify.** Run `python3 scripts/lint_agents_md.py` until green;

package/.agent-src/contexts/documentation-hierarchy.md

@@ -124,8 +124,8 @@ agents/overrides/skills/eloquent.md        ← Override (Layer 4)
 | Context location | Scope | Example |
 |---|---|---|
 | `.augment/contexts/` | Shared (about the agent system) | `augment-infrastructure.md` |
-| `agents/contexts/` | Project-wide | `import-pipeline.md` |
-| `app/Modules/*/agents/contexts/` | Module-specific | `client-api.md` |
+| `agents/settings/contexts/` | Project-wide | `import-pipeline.md` |
+| `app/Modules/*/agents/settings/contexts/` | Module-specific | `client-api.md` |
 
 ### Template Usage (Layer 1 → Layer 5/6)
 

package/.agent-src/contexts/execution/roadmap-process-loop.md

@@ -138,6 +138,25 @@ For each open step in the working set (scope-bound — see wrapper):
    [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md).
    A loop iteration that lands work without flipping its box is a
    rule violation. Do not save flips for the archive commit.
+
+### 5b. Flip-guard — deterministic
+
+   Before advancing to step 6, run:
+
+   ```bash
+   git diff --name-only -- agents/roadmaps/<file>.md
+   ```
+
+   Empty output → Iron Law 2 was violated this iteration: the step
+   landed work but no checkbox flipped. **Halt loudly**, surface
+   "step <N> landed without checkbox flip — flip then resume", and
+   stop the run. Do not auto-fix; the user resumes on the next turn.
+
+   Deterministic counterpart to the rule's pre-send self-check —
+   catches a forgotten flip per step, not only at run end. Runs in
+   every scope (`process-step`, `process-phase`, `process-full`);
+   cost is one `git diff` per step.
+
 6. **Dashboard regen — cadence-gated.** Run
    `./agent-config roadmap:progress` when due per
    `roadmap.dashboard_regen_cadence` (resolved in § 4):

package/.agent-src/ghostwriter/README.md

@@ -10,7 +10,7 @@
 - `fictional-fixture-v1.md` — single allowlisted fictional fixture
   demonstrating the schema. **No real-person profiles ever ship here.**
 
-That's it. Real-person profiles live in **`agents/ghostwriter/`** in the
+That's it. Real-person profiles live in **`agents/reference/ghostwriter/`** in the
 consumer project and are gitignored by default
 (see [`config/gitignore-block.txt`](../../config/gitignore-block.txt)).
 
@@ -42,7 +42,7 @@ Two-step process — **both required**:
 
 - Any file in this directory whose stem is not on the allowlist.
 - Any allowlisted file missing `fictional: true`.
-- Any consumer-side file under `agents/ghostwriter/` with `fictional: true`
+- Any consumer-side file under `agents/reference/ghostwriter/` with `fictional: true`
   (fictional profiles belong here, not in consumer trees).
 
 New fixtures require reviewer sign-off on the allowlist change.

package/.agent-src/ghostwriter/fictional-fixture-v1.md

@@ -85,7 +85,7 @@ to load.
 
 Do not use this fixture as a template for adding a real person to
 `.agent-src.uncompressed/ghostwriter/`. Real-person profiles never
-ship with the package — they belong in `agents/ghostwriter/` on the
+ship with the package — they belong in `agents/reference/ghostwriter/` on the
 consumer side, where they are gitignored by default.
 
 If you need a second fictional fixture (for a different

package/.agent-src/personas/README.md

@@ -111,4 +111,4 @@ Personas are one of three voice primitives. Same shape (Markdown +
 frontmatter), distinct purpose — **no folding, no shared schema**:
 
 - [`../../docs/contracts/agent-user-schema.md`](../../docs/contracts/agent-user-schema.md) — `.agent-user.md`, the maintainer's own voice (`/post-as:me`, no disclosure footer).
-- [`../../docs/contracts/ghostwriter-schema.md`](../../docs/contracts/ghostwriter-schema.md) — `agents/ghostwriter/<slug>.md`, captured public-figure voice (`/ghostwriter:write` / `/post-as:ghostwriter`, mandatory disclosure footer).
+- [`../../docs/contracts/ghostwriter-schema.md`](../../docs/contracts/ghostwriter-schema.md) — `agents/reference/ghostwriter/<slug>.md`, captured public-figure voice (`/ghostwriter:write` / `/post-as:ghostwriter`, mandatory disclosure footer).

package/.agent-src/personas/advisors/contrarian.md

@@ -90,6 +90,6 @@ straw man.
 ---
 
 *This persona is consumed by the AI Council advisor system
-(replace-mode). When activated via `agents/.ai-council.yml`'s
+(replace-mode). When activated via `agents/settings/.ai-council.yml`'s
 `advisors:` block, the entire file body below the frontmatter becomes
 the system prompt for the targeted member.*

package/.agent-src/personas/advisors/executor.md

@@ -94,6 +94,6 @@ can start on.
 ---
 
 *This persona is consumed by the AI Council advisor system
-(replace-mode). When activated via `agents/.ai-council.yml`'s
+(replace-mode). When activated via `agents/settings/.ai-council.yml`'s
 `advisors:` block, the entire file body below the frontmatter becomes
 the system prompt for the targeted member.*

package/.agent-src/personas/advisors/expansionist.md

@@ -93,6 +93,6 @@ the proposal as written can survive its own success.
 ---
 
 *This persona is consumed by the AI Council advisor system
-(replace-mode). When activated via `agents/.ai-council.yml`'s
+(replace-mode). When activated via `agents/settings/.ai-council.yml`'s
 `advisors:` block, the entire file body below the frontmatter becomes
 the system prompt for the targeted member.*

package/.agent-src/personas/advisors/first-principles.md

@@ -93,6 +93,6 @@ inherit an accidental complexity from convention.
 ---
 
 *This persona is consumed by the AI Council advisor system
-(replace-mode). When activated via `agents/.ai-council.yml`'s
+(replace-mode). When activated via `agents/settings/.ai-council.yml`'s
 `advisors:` block, the entire file body below the frontmatter becomes
 the system prompt for the targeted member.*

package/.agent-src/personas/advisors/outsider.md

@@ -97,6 +97,6 @@ synthesis stage can use to see the proposal from outside.
 ---
 
 *This persona is consumed by the AI Council advisor system
-(replace-mode). When activated via `agents/.ai-council.yml`'s
+(replace-mode). When activated via `agents/settings/.ai-council.yml`'s
 `advisors:` block, the entire file body below the frontmatter becomes
 the system prompt for the targeted member.*

package/.agent-src/rules/agent-authority.md

@@ -4,6 +4,18 @@ tier: "3"
 description: "Priority Index for the four authority rules — Hard Floor → Permission Gate → Commit Default → Trivial-vs-Blocking; read first, route to canonical rule"
 alwaysApply: true
 source: package
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Agent Authority — Priority Index

package/.agent-src/rules/analysis-skill-routing.md

@@ -9,6 +9,18 @@ triggers:
   - phrase: "dig into the codebase"
 routes_to:
   - "skill:analysis-skill-router"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Analysis Skill Routing

package/.agent-src/rules/architecture.md

@@ -2,13 +2,25 @@
 type: "auto"
 tier: "3"
 alwaysApply: false
-description: "Architecture rules for creating new files, classes, controllers, modules, or making structural decisions about project organization"
+description: "Architecture rules for new files, classes, controllers, modules, or structural decisions about project organization"
 source: package
 triggers:
   - keyword: "controller"
   - keyword: "service"
   - keyword: "module"
   - intent: "structural decision"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Architecture Rules

package/.agent-src/rules/artifact-drafting-protocol.md

@@ -2,13 +2,25 @@
 type: "auto"
 tier: "2a"
 alwaysApply: false
-description: "Creating a new skill, rule, command, or guideline, or significantly rewriting one — runs mandatory Understand → Research → Draft before drafting"
+description: "Creating a new skill/rule/command/guideline or significantly rewriting one — runs mandatory Understand → Research → Draft first"
 source: package
 triggers:
   - intent: "create new skill"
   - intent: "create new rule"
   - intent: "create new command"
   - intent: "create new guideline"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Artifact Drafting Protocol

package/.agent-src/rules/artifact-engagement-recording.md

@@ -2,7 +2,7 @@
 type: "auto"
 tier: "mechanical-already"
 alwaysApply: false
-description: "After a /implement-ticket or /work phase-step (refine/memory/analyze/plan/implement/test/verify/report) or full task — emit one telemetry:record call"
+description: "After a /implement-ticket or /work phase-step or full task — emit one telemetry:record call"
 source: package
 triggers:
   - phrase: "/implement-ticket"
@@ -12,6 +12,18 @@ routes_to:
   - "contract:artifact-engagement-flow"
 load_context:
   - "../contexts/contracts/artifact-engagement-flow.md"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 <!-- cloud_safe: noop -->

package/.agent-src/rules/ask-when-uncertain.md

@@ -4,6 +4,18 @@ tier: "3"
 description: "Ask when uncertain — don't guess, assume, or improvise"
 alwaysApply: true
 source: package
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Ask When Uncertain

package/.agent-src/rules/augment-edit-discipline.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "2a"
-description: "Editing inside .augment/ or .agent-src.uncompressed/ — files MUST stay project-agnostic AND any add/rename/delete syncs counts and cross-references in the same edit"
+description: "Editing .augment/ or .agent-src.uncompressed/ — keep files project-agnostic; sync counts and cross-refs on add/rename/delete"
 source: package
 triggers:
   - path_prefix: ".augment/"
@@ -16,6 +16,18 @@ validator_ignore:
   - type: "substring"
     pattern: ".agent-src.uncompressed/"
     reason: "Rule scopes the portability gate to the uncompressed authoring tree."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Augment Edit Discipline

package/.agent-src/rules/augment-source-of-truth.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "1"
-description: "Creating, editing, or modifying files in .agent-src/ or .augment/ — source of truth is .agent-src.uncompressed/, never edit generated dirs directly"
+description: "Editing files in .agent-src/ or .augment/ — source of truth is .agent-src.uncompressed/; never edit generated dirs directly"
 source: package
 load_context:
   - ../contexts/communication/rules-auto/augment-source-of-truth-mechanics.md
@@ -14,6 +14,18 @@ validator_ignore:
   - type: "substring"
     pattern: ".agent-src.uncompressed/"
     reason: "Rule documents the source-of-truth boundary; mentioning the path is its purpose."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Source of Truth

package/.agent-src/rules/autonomous-execution.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "3"
-description: "Whether to ask or act on a workflow step — trivial-vs-blocking, autonomy opt-in, commit default; Hard Floor in non-destructive-by-default"
+description: "Whether to ask or act on a workflow step — trivial-vs-blocking, autonomy opt-in, commit default; Hard Floor non-destructive-by-default"
 alwaysApply: false
 source: package
 load_context:
@@ -12,6 +12,18 @@ triggers:
   - intent: "trivial workflow question"
   - intent: "autonomy mode"
   - keyword: "personal.autonomy"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Autonomous Execution

package/.agent-src/rules/caveman-speak.md

@@ -1,10 +1,22 @@
 ---
 type: "auto"
 tier: "1"
-description: "When caveman.speak_scope != off — compress reply prose to caveman grammar with carve-outs for numbered options, Iron-Law, code, paths, error markers"
+description: "When caveman.speak_scope != off — compress prose to caveman grammar with carve-outs for numbered options, Iron-Law, code, paths, error markers"
 source: package
 triggers:
   - intent: "any reply"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Caveman Speak

package/.agent-src/rules/cli-output-handling.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "2a"
-description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk; tail/grep fallback"
+description: "Running verbose CLI output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk; tail/grep fallback"
 source: package
 triggers:
   - keyword: "git"
@@ -11,6 +11,18 @@ triggers:
   - keyword: "composer"
 routes_to:
   - "skill:rtk-output-filtering"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Cli Output Handling

package/.agent-src/rules/command-suggestion-policy.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "mechanical-already"
-description: "User prompt without /command matching an eligible slash command — surface matches as numbered options with as-is escape; never auto-executes"
+description: "Prompt without /command matching an eligible slash command — surface matches as numbered options with as-is escape; never auto-executes"
 source: package
 triggers:
   - phrase: "free-form prompt"
@@ -10,6 +10,18 @@ routes_to:
   - "contract:command-suggestion-flow"
 load_context:
   - "../contexts/contracts/command-suggestion-flow.md"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Command Suggestion Policy

package/.agent-src/rules/commit-conventions.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "2a"
-description: "Git commit message format, branch naming, conventional commits, committing, pushing, or creating pull requests"
+description: "Git commit format, branch naming, conventional commits, committing, pushing, creating PRs"
 source: package
 triggers:
   - keyword: "commit"
@@ -9,6 +9,18 @@ triggers:
   - phrase: "conventional commits"
 routes_to:
   - "skill:conventional-commits-writing"
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Commit Conventions

package/.agent-src/rules/commit-policy.md

@@ -6,6 +6,18 @@ alwaysApply: true
 source: package
 load_context:
   - ../contexts/authority/commit-mechanics.md
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Commit Policy

package/.agent-src/rules/context-hygiene.md

@@ -2,20 +2,32 @@
 type: "auto"
 tier: "1"
 alwaysApply: false
-description: "When debugging, fixing errors, or running long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers"
+description: "Debugging, fixing errors, or long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers"
 source: package
 triggers:
   - intent: "long conversation"
   - intent: "tool loop"
   - intent: "fresh chat"
   - keyword: "3-failure"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Context Hygiene
 
 > **Enforced by:** [`scripts/context_hygiene_hook.py`](../../scripts/context_hygiene_hook.py)
 > on Augment + Claude Code (`PostToolUse`). The hook maintains
-> `agents/state/context-hygiene.json` (turn count, loop signal,
+> `agents/runtime/state/context-hygiene.json` (turn count, loop signal,
 > freshness milestones at 20/40/60); the prose below is the spec the
 > hook implements and the agent-side fallback.
 
@@ -105,7 +117,7 @@ If you need an ignored skill: read its SKILL.md directly, apply guidance, then a
 
 GitHub Copilot has no `PostToolUse` hook surface, so
 `scripts/context_hygiene_hook.py` cannot run structurally and
-`agents/state/context-hygiene.json` is not maintained automatically
+`agents/runtime/state/context-hygiene.json` is not maintained automatically
 (turn count, loop signal, freshness milestones at 20/40/60).
 
 The cooperative path: track turns and tool-loop signals from memory

package/.agent-src/rules/copilot-routing.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "3"
-description: "Configuring GitHub Copilot — copilot-instructions.md, PR-review comment patterns, suggestion behavior — route to the copilot-config skill"
+description: "Configuring GitHub Copilot — copilot-instructions.md, PR-review patterns, suggestion behavior — route to copilot-config"
 source: package
 triggers:
   - keyword: "copilot"
@@ -9,6 +9,18 @@ triggers:
   - phrase: "copilot pr review"
 routes_to:
   - "skill:copilot-config"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Copilot Routing

package/.agent-src/rules/devcontainer-routing.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "3"
-description: "Wiring DevContainers or GitHub Codespaces — devcontainer.json, images, VS Code features, port forwarding — route to the devcontainer skill"
+description: "Wiring DevContainers/Codespaces — devcontainer.json, images, VS Code features, port forwarding — route to the devcontainer skill"
 source: package
 triggers:
   - keyword: "devcontainer"
@@ -10,6 +10,18 @@ triggers:
   - phrase: "devcontainer.json"
 routes_to:
   - "skill:devcontainer"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Devcontainer Routing

package/.agent-src/rules/direct-answers.md

@@ -4,6 +4,18 @@ tier: "3"
 description: "Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default."
 alwaysApply: true
 source: package
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # Direct Answers