hatch3r 1.7.5 → 1.9.0

package/{commands → dist/content/commands}/hatch3r-revision.md

@@ -4,14 +4,21 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-implementer, hatch3r-lint-fixer, hatch3r-test-writer, hatch3r-reviewer, hatch3r-fixer, hatch3r-security-auditor, hatch3r-docs-writer, hatch3r-a11y-auditor, hatch3r-perf-profiler]
 description: User-guided revision of agent-implemented code in a fresh context window. Reconstructs what was done, interviews the user for feedback, fixes issues, cleans up leftovers, and drives toward merge readiness. Delegation, quality pipeline, modes, and board integration details are in commands/revision/.
-tags: [implementation, team]
+tags: [implementation, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 9
+  rationale: Per-revision fanout — implementer, lint-fixer, test-writer (Stage 1 fix group), reviewer ↔ fixer review loop, then parallel Stage 2 final-quality specialists (security-auditor, docs-writer, a11y-auditor, perf-profiler) bounded by max_phase4_parallel.
 ---
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
 ## Agent Pipeline
 
 | Stage | Agent(s) | Parallel | Required |
@@ -46,7 +53,7 @@ The user is the reviewer. The agent is the interviewer and fixer.
 
 ## Shared Context
 
-**If board context exists** (current branch has an associated PR linked to issues), **read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
+**If board context exists** (current branch has an associated PR linked to issues), **read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
 
 If no board context exists (plain instruction, no PR, no linked issues), skip shared context loading and work from the git diff alone.
 
@@ -98,7 +105,7 @@ Rebuild full context in the fresh window. No prior implementation context is ass
 #### 1a. Detect Scope of Changes
 
 1. Identify the current branch: `git branch --show-current`.
-2. Determine the default branch from `.agents/hatch.json` (`board.defaultBranch`). Fall back to `main` if unavailable.
+2. Determine the default branch from `.hatch3r/hatch.json` (`board.defaultBranch`). Fall back to `main` if unavailable.
 3. Compute the diff: `git diff {defaultBranch}...HEAD --stat` for a summary, then `git diff {defaultBranch}...HEAD` for the full diff.
 4. Parse the diff summary: files changed, lines added/removed, file types affected.
 5. Identify affected areas from the file paths (e.g., `src/routes/` -> API, `src/components/` -> UI, `tests/` -> testing).
@@ -107,7 +114,7 @@ Rebuild full context in the fresh window. No prior implementation context is ass
 
 > Platform-specific CLI commands: see `commands/board/shared-{platform}.md` for PR/issue lookup
 
-1. Detect the platform from `.agents/hatch.json` (`board.platform`). Fall back to GitHub if unavailable.
+1. Detect the platform from `.hatch3r/hatch.json` (`board.platform`). Fall back to GitHub if unavailable.
 2. Search for an open PR on this branch using the platform CLI:
    - **GitHub:** `gh pr list --head {branch} --state open --json number,title,body,url --limit 1`
    - **Azure DevOps:** `az repos pr list --source-branch {branch} --status active --top 1`
@@ -120,11 +127,11 @@ Rebuild full context in the fresh window. No prior implementation context is ass
 
 #### 1c. Load Project Rules
 
-Read all `scope: always` rules from `.agents/rules/`. These must be included in every sub-agent prompt in Step 6.
+Read all `scope: always` rules from `rules/`. These must be included in every sub-agent prompt in Step 6.
 
 #### 1d. Consult Learnings
 
-If `.agents/learnings/` exists, scan for learnings with matching areas or tags that overlap with the affected areas from Step 1a.5. Cache relevant learnings for Step 6.
+If `.hatch3r/learnings/` exists, scan for learnings with matching areas or tags that overlap with the affected areas from Step 1a.5. Cache relevant learnings for Step 6.
 
 ---
 
@@ -453,7 +460,7 @@ Capture revision-specific learnings. Focus on patterns that inform future implem
    - Were there any integration issues between sub-agent outputs?
 
 2. If significant learnings are identified:
-   - Create learning files in `.agents/learnings/` following the `hatch3r-learn` command format.
+   - Create learning files in `.hatch3r/learnings/` following the `hatch3r-learn` command format.
    - Use category `pitfall` for issues agents commonly miss.
    - Use category `pattern` for revision approaches that worked well.
    - Tag with relevant area labels.

package/{commands → dist/content/commands}/hatch3r-roadmap.md

@@ -4,13 +4,21 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Sequence delivery phases over time into a dependency-ordered milestone plan with business and technical lenses, emitting a todo.md rollout schedule rather than design docs
-tags: [planning, greenfield]
+tags: [planning, ctx:greenfield-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 2
+  rationale: Two parallel hatch3r-researcher modes (business-priority + technical-readiness) in Step 3 to inform sequencing; one hatch3r-docs-writer in Step 6 assembles todo.md on their merged output (serialized on the research → assembly dependency edge).
 ---
+
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
 # Roadmap — Generate Phased Roadmap from Specs & Vision
 
 Generate a dependency-aware, priority-ordered roadmap with **two parallel dimensions**: business milestones and technical milestones. Spawns parallel researcher sub-agents (business priority, technical readiness) to inform prioritization with market timing, competitive pressure, revenue impact, and production readiness gaps. Outputs to `todo.md` in the exact format that `hatch3r-board-fill` expects, with items tagged as `[BIZ]`, `[TECH]`, or `[BOTH]`. Optionally generates a root-level `AGENTS.md`. Works for both greenfield projects (from `hatch3r-project-spec` output) and brownfield projects (from `hatch3r-codebase-map` output).
@@ -27,7 +35,7 @@ Generate a dependency-aware, priority-ordered roadmap with **two parallel dimens
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
+**Read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 

package/{commands → dist/content/commands}/hatch3r-security-audit.md

@@ -3,13 +3,17 @@ id: hatch3r-security-audit
 type: command
 orchestrator: false
 description: Open an OWASP ASI security epic reviewing auth boundaries, input validation, and supply-chain risks with one hardening sub-issue per module plus trust-boundary audit
-tags: [maintenance, security]
+tags: [maintenance, floor:security]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 ---
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
 ## Agent Pipeline
 
 This command creates audit issues and epics. It does not spawn implementation sub-agents.
@@ -30,7 +34,7 @@ Create a security audit epic on **{owner}/{repo}** with one sub-issue per logica
 
 ## Shared Context
 
-**Read the project's shared board context at the start of the run** (e.g., `.agents/commands/hatch3r-board-shared.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
+**Read the project's shared board context at the start of the run** (e.g., `commands/hatch3r-board-shared/SKILL.md` or equivalent). It contains GitHub Context, Project Reference, Projects v2 sync procedure, and Board Overview template. Cache all values for the duration of this run.
 
 ## Token-Saving Directives
 

package/{commands → dist/content/commands}/hatch3r-test-plan.md

@@ -4,14 +4,21 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Plan a comprehensive test strategy -- spawn parallel researchers, produce test plan spec with coverage targets, priority ordering, test case outlines, and structured todo.md entries for board-fill.
-tags: [core, planning]
+tags: [planning, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 5
+  rationale: Five parallel hatch3r-researcher modes per test-planning brief — coverage-analysis, complexity-and-risk, test-pattern, boundary-analysis, risk-prioritization — dispatched concurrently in Step 3; a docs-writer composes the test plan on their merged output.
 ---
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
 ## Agent Pipeline
 
 | Stage | Agent(s) | Parallel | Required |
@@ -28,7 +35,7 @@ Take a test planning scope (feature, module, or codebase area) and produce a com
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
 
 ## Token-Saving Directives
 
@@ -115,11 +122,11 @@ Answer these now, or say 'use defaults' for any where you're comfortable with a
    - `docs/specs/` -- project specifications (read TOC/headers first, expand relevant sections only)
    - `docs/adr/` -- architectural decision records (scan for testing-related decisions)
    - `README.md` -- project overview
-   - `.agents/hatch.json` -- board configuration
+   - `.hatch3r/hatch.json` -- board configuration
    - Existing `todo.md` -- current backlog (check for overlap or related items)
    - Feature spec -- if mode is feature-scoped, look for the referenced feature spec in `docs/specs/`
 2. Scan GitHub issues via `search_issues` for existing testing-related work. Note duplicates or partial overlaps.
-3. If `.agents/learnings/` exists, scan for learnings relevant to testing, coverage, or quality.
+3. If `.hatch3r/learnings/` exists, scan for learnings relevant to testing, coverage, or quality.
 4. Present a context summary:
 
 ```
@@ -527,7 +534,7 @@ If `hatch3r-board-fill`: instruct the user to invoke `hatch3r-board-fill`. Note
 - **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, present partial results from the remaining sub-agents and ask the user how to proceed (continue without that researcher's input / provide the missing information manually / abort).
 - **Conflicting researcher outputs:** Present both options side by side with trade-offs. Ask the user to decide. Do not silently pick one.
 - **File write failure:** Report the error and provide the full file content so the user can create the file manually.
-- **Missing project context:** If no `hatch3r-board-shared` or `.agents/hatch.json` exists, proceed without board context -- this command does not require board configuration.
+- **Missing project context:** If no `hatch3r-board-shared` or `.hatch3r/hatch.json` exists, proceed without board context -- this command does not require board configuration.
 - **No existing tests:** Switch to bootstrapping strategy -- the test plan becomes a greenfield test setup plan. Include infrastructure setup (framework installation, config, CI gates) as P0 items. Warn that coverage baselines will be unavailable.
 - **No coverage tooling:** Recommend coverage setup as a prerequisite. Include coverage tooling installation as a P0 infrastructure item in the test plan. Proceed with estimated coverage from code analysis rather than measured coverage.
 - **Feature spec not found (feature-scoped mode):** Warn that the test plan will be less informed without a feature spec. Recommend running `hatch3r-feature-plan` first for best results. Proceed with what's available from codebase analysis.

package/{commands → dist/content/commands}/hatch3r-workflow.md

@@ -4,13 +4,21 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-reviewer, hatch3r-fixer, hatch3r-test-writer, hatch3r-security-auditor, hatch3r-docs-writer, hatch3r-lint-fixer, hatch3r-a11y-auditor, hatch3r-perf-profiler]
 description: Guided development lifecycle with 4 phases (Analyze, Plan, Implement, Review) and scale-adaptive Quick Mode for small tasks.
-tags: [core, implementation]
+tags: [implementation, orchestration]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
 triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 10
+  rationale: Full 4-phase delivery pipeline — researcher (Phase 1), implementer (one per independent module, Phase 3), reviewer ↔ fixer review loop (Phase 4a), then a parallel Phase-4b final-quality batch (test-writer, security-auditor, docs-writer, lint-fixer, a11y-auditor, perf-profiler) bounded by max_phase4_parallel.
 ---
+
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
 # Development Workflow -- Guided Lifecycle for Structured Implementation
 
 Optional guided development lifecycle command that walks through structured phases — Analyze, Plan, Implement, Review — using hatch3r's existing agents and skills. Includes a Quick Mode that collapses phases for small tasks. Scale-adaptive: detects task complexity and recommends the appropriate mode. Works standalone or when invoked from `hatch3r-board-pickup`.
@@ -43,7 +51,7 @@ If **no**: all browser verification steps are skipped silently throughout the en
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
+**Read the `hatch3r-board-shared` skill at the start of the run.** It contains Board Configuration, GitHub Context, Project Reference, Projects v2 sync procedure, and tooling directives. Cache all values for the duration of this run.
 
 ## Global Rule Overrides
 
@@ -143,7 +151,7 @@ Cache the researcher outputs for use in Phase 2 and Phase 3.
 
 #### 1d. Consult Learnings
 
-If `.agents/learnings/` exists:
+If `.hatch3r/learnings/` exists:
 
 1. Search for learnings tagged with relevant areas or technologies.
 2. Surface any applicable past experiences that inform this task.
@@ -253,8 +261,8 @@ The implementer sub-agent prompt MUST include:
 - The task description, acceptance criteria, and type.
 - The researcher output from Step 3a (if not skipped).
 - The selected hatch3r skill name and instructions.
-- All `scope: always` rule directives from `.agents/rules/`.
-- Relevant learnings from `.agents/learnings/`.
+- All `scope: always` rule directives from `rules/`.
+- Relevant learnings from `.hatch3r/learnings/`.
 - Explicit instruction: do NOT create branches, commits, or PRs.
 - **Reference conventions** from `similar-implementation` output (Tier 2/3) — triggers the implementer's Convention Lock step.
 - **Resolved requirements** from `requirements-elicitation` answers (Tier 2/3) — explicit decisions on ambiguities.
@@ -302,14 +310,14 @@ After each reviewer iteration, assess the reviewer's findings confidence: if the
 
 Each reviewer/fixer sub-agent prompt MUST include:
 - The agent protocol to follow.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - The diff or file changes to review/fix.
 - The task's acceptance criteria.
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
 #### 4b. Final Quality (Parallel Specialists)
 
-**ONLY after the review loop (4a) reports 0 Critical + 0 Warning findings**, spawn the remaining specialist sub-agents. Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many independent sub-agents in parallel as the platform supports.
+**ONLY after the review loop (4a) reports 0 Critical + 0 Warning findings**, spawn the remaining specialist sub-agents. Use the Task tool with `subagent_type: "generalPurpose"`. Dispatch is bounded by `max_phase4_parallel` (default `3`, env-overridable via `HATCH3R_MAX_PHASE4_PARALLEL`, valid range 1-16) per `rules/hatch3r-agent-orchestration.md` Phase 4 — Final Quality. When the applicable specialists exceed the bound, batch by severity priority `CRITICAL → HIGH → MEDIUM → LOW`; each batch runs to completion before the next.
 
 **Always spawn (mandatory for every code change):**
 
@@ -328,7 +336,7 @@ Each reviewer/fixer sub-agent prompt MUST include:
 
 Each specialist sub-agent prompt MUST include:
 - The agent protocol to follow.
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - The diff or file changes to review.
 - The task's acceptance criteria.
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
@@ -363,10 +371,10 @@ Review Results:
 
 #### 4e. Capture Learnings
 
-If `.agents/learnings/` exists:
+If `.hatch3r/learnings/` exists:
 
 1. Extract learnings from this implementation session (patterns discovered, pitfalls encountered, decisions made).
-2. Store in `.agents/learnings/` with appropriate area tags.
+2. Store in `.hatch3r/learnings/` with appropriate area tags.
 
 ---
 

package/{commands → dist/content/commands}/revision/revision-delegation.md

@@ -63,9 +63,9 @@ Each sub-agent prompt MUST include:
 
 1. The specific findings to address (file paths, line numbers, descriptions, expected behavior).
 2. Instruction to follow the corresponding agent protocol (e.g., "Follow the hatch3r-implementer agent protocol").
-3. All `scope: always` rule directives from `.agents/rules/` — sub-agents do not inherit rules automatically.
+3. All `scope: always` rule directives from `rules/` — sub-agents do not inherit rules automatically.
 4. Acceptance criteria from linked issues (if available from Step 1b).
-5. Relevant learnings from `.agents/learnings/` (if found in Step 1d).
+5. Relevant learnings from `.hatch3r/learnings/` (if found in Step 1d).
 6. Explicit instruction: do NOT create branches, commits, or PRs.
 7. Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 8. Revision-specific constraint: "You are fixing existing code, not implementing new features. Stay within the architecture established by the original implementation."

package/{commands → dist/content/commands}/revision/revision-quality.md

@@ -38,7 +38,7 @@ Run an iterative review loop (max 3 iterations) until 0 Critical + 0 Warning fin
 
 The reviewer prompt MUST include:
 - The diff of all changes made (use `git diff` on the working tree).
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Iteration number and previous findings (if not the first iteration).
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
 
@@ -82,7 +82,7 @@ After the review loop is clean, spawn specialist agents in parallel via the Task
 
 Each specialist sub-agent prompt MUST include:
 - The agent protocol to follow (e.g., "Follow the hatch3r-test-writer agent protocol").
-- All `scope: always` rule directives from `.agents/rules/` (sub-agents do not inherit rules automatically).
+- All `scope: always` rule directives from `rules/` (sub-agents do not inherit rules automatically).
 - The diff or file changes to review.
 - The linked issue's acceptance criteria (if available).
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.

package/{github-agents → dist/content/github-agents}/hatch3r-docs-agent.md

@@ -3,7 +3,7 @@ name: hatch3r-docs-agent
 type: github-agent
 description: Technical writer who maintains specs, ADRs, and documentation
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [devops, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{github-agents → dist/content/github-agents}/hatch3r-lint-agent.md

@@ -3,7 +3,7 @@ name: hatch3r-lint-agent
 type: github-agent
 description: Code quality enforcer who fixes style, formatting, and type issues
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [devops, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{github-agents → dist/content/github-agents}/hatch3r-security-agent.md

@@ -3,7 +3,7 @@ name: hatch3r-security-agent
 type: github-agent
 description: Security analyst who audits code, rules, and data flows
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [devops, floor:security, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{github-agents → dist/content/github-agents}/hatch3r-test-agent.md

@@ -3,7 +3,7 @@ name: hatch3r-test-agent
 type: github-agent
 description: QA engineer who writes and maintains tests
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [review, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true

package/{hooks → dist/content/hooks}/hatch3r-ci-failure.md

@@ -4,7 +4,7 @@ type: hook
 event: ci-failure
 agent: ci-watcher
 description: Diagnose CI pipeline failures
-tags: [core]
+tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -22,7 +22,7 @@ When this hook fires, the assigned agent should:
 4. For test failures: identify the specific failing test(s), expected vs. actual values, and the source file(s) involved.
 5. For build/type errors: extract the compiler error message and the source location.
 6. Produce a root-cause hypothesis with a concrete suggested fix (code change, config change, or retry recommendation for flaky failures).
-7. If the failure matches a known pattern from `.agents/learnings/`, reference the relevant learning.
+7. If the failure matches a known pattern from `.hatch3r/learnings/`, reference the relevant learning.
 
 ## Expected Output
 
@@ -33,7 +33,7 @@ A structured diagnostic report containing:
 - **Root cause**: Concise explanation of why the failure occurred.
 - **Error excerpt**: The relevant log output (truncated to key lines).
 - **Suggested fix**: Specific, actionable remediation steps.
-- **Related learnings**: Links to any matching entries in `.agents/learnings/` (if applicable).
+- **Related learnings**: Links to any matching entries in `.hatch3r/learnings/` (if applicable).
 
 ## Configuration
 

package/{hooks → dist/content/hooks}/hatch3r-file-save.md

@@ -5,7 +5,7 @@ event: file-save
 agent: context-rules
 description: Activate context-specific rules on file save
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
-tags: [core]
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -17,7 +17,7 @@ Activate context-specific rules when a file is saved, applying relevant coding s
 
 When this hook fires, the assigned agent should:
 
-1. Determine the saved file's path and match it against the project's rule definitions in `.agents/rules/`.
+1. Determine the saved file's path and match it against the project's rule definitions in `rules/`.
 2. Load all rules where `scope: always` applies, plus any rules with glob patterns matching the saved file's path.
 3. Evaluate the saved file's contents against the loaded rules — check for convention violations, pattern mismatches, or missing required elements (e.g., missing error handling in API routes, missing accessibility attributes in components).
 4. If violations are found, surface them as inline warnings or suggestions (not blocking — file-save hooks should be non-disruptive).
@@ -31,5 +31,5 @@ When this hook fires, the assigned agent should:
 ## Configuration
 
 - **Globs**: Controlled by the `globs` frontmatter field. Adjust to match your project's source file extensions.
-- **Rule sources**: Reads from `.agents/rules/`. Rules with matching `globs` or `scope: always` are activated.
+- **Rule sources**: Reads from `rules/`. Rules with matching `globs` or `scope: always` are activated.
 - **Debounce**: To avoid excessive processing during rapid saves, the agent debounces with a 2-second window (configurable via `debounceMs`).

package/{hooks → dist/content/hooks}/hatch3r-post-merge.md

@@ -4,7 +4,7 @@ type: hook
 event: post-merge
 agent: ci-watcher
 description: Check CI pipeline status after merge
-tags: [core]
+tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{hooks → dist/content/hooks}/hatch3r-pre-commit.md

@@ -5,7 +5,7 @@ event: pre-commit
 agent: lint-fixer
 description: Auto-fix lint and formatting issues before commit
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
-tags: [core]
+tags: [implementation]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{hooks → dist/content/hooks}/hatch3r-pre-push.md

@@ -4,7 +4,7 @@ type: hook
 event: pre-push
 agent: security-auditor
 description: Scan for secrets and security issues before push
-tags: [core]
+tags: [floor:security]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -29,6 +29,6 @@ When this hook fires, the assigned agent should:
 
 ## Configuration
 
-- **Allowlist**: Add known false positives to `.agents/security/secret-allowlist.json` (patterns or file paths to ignore).
-- **Pattern extensions**: The agent uses built-in patterns for common secret types. Add project-specific patterns via `.agents/security/custom-patterns.json`.
+- **Allowlist**: Add known false positives to `.hatch3r/security/secret-allowlist.json` (patterns or file paths to ignore).
+- **Pattern extensions**: The agent uses built-in patterns for common secret types. Add project-specific patterns via `.hatch3r/security/custom-patterns.json`.
 - **Scope**: By default, scans only the diff of outgoing commits. Set `scanFullHistory: true` to scan all files (slower, useful for initial audits).

package/{hooks → dist/content/hooks}/hatch3r-session-start.md

@@ -4,7 +4,7 @@ type: hook
 event: session-start
 agent: learnings-loader
 description: Load relevant learnings at session start
-tags: [core]
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -16,11 +16,11 @@ Activate the learnings-loader agent when a new coding session starts to surface
 
 When this hook fires, the assigned agent should:
 
-1. Read the `.agents/learnings/` directory and index all available learning files by area, tags, and recency.
+1. Read the `.hatch3r/learnings/` directory and index all available learning files by area, tags, and recency.
 2. Identify the most relevant learnings based on recently modified files in the working tree (using `git diff` and `git log` to infer the active work area).
 3. Surface the top 3-5 most relevant learnings as a brief summary, prioritizing: (a) learnings from the last 7 days, (b) learnings matching the current branch's area labels, (c) learnings tagged as high-impact or cross-cutting.
 4. If there are recent architectural decisions or convention changes, highlight them prominently.
-5. If `.agents/learnings/` does not exist or is empty, skip silently.
+5. If `.hatch3r/learnings/` does not exist or is empty, skip silently.
 
 ## Expected Output
 

package/{rules → dist/content/rules}/hatch3r-accessibility-standards.md

@@ -3,7 +3,8 @@ id: hatch3r-accessibility-standards
 type: rule
 description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
 scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/*a11y*,**/*accessibility*"
-tags: [a11y]
+tags: [floor:ui-ux, a11y]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{rules → dist/content/rules}/hatch3r-accessibility-standards.mdc

@@ -2,6 +2,7 @@
 description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard navigation, screen readers, and ARIA patterns
 globs: ["**/*.vue", "**/*.jsx", "**/*.tsx", "**/*.svelte", "**/components/**", "**/*.html", "**/*a11y*", "**/*accessibility*"]
 alwaysApply: false
+precedence: high
 ---
 # Accessibility Standards
 

package/{rules → dist/content/rules}/hatch3r-agent-orchestration-detail.md

@@ -3,10 +3,13 @@ id: hatch3r-agent-orchestration-detail
 type: rule
 description: Extended orchestration reference — PipelineContext schemas, resilience protocols, observability integration, and auto-mode guardrails
 scope: conditional
-globs: "**/.agents/**,**/pipeline/**,**/*orchestrat*,**/*agent*"
-tags: [core]
+globs: "**/.hatch3r/**,**/pipeline/**,**/*orchestrat*,**/*agent*"
+tags: [orchestration, floor:protocol]
+precedence: normal
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
+detail_rule: true
+consumed_by: hatch3r-agent-orchestration
 ---
 # Agent Orchestration — Extended Reference
 

package/{rules → dist/content/rules}/hatch3r-agent-orchestration-detail.mdc

@@ -1,7 +1,10 @@
 ---
 description: Extended orchestration reference — PipelineContext schemas, resilience protocols, observability integration, and auto-mode guardrails
-globs: ["**/.agents/**", "**/pipeline/**", "**/*orchestrat*", "**/*agent*"]
+globs: ["**/.hatch3r/**", "**/pipeline/**", "**/*orchestrat*", "**/*agent*"]
 alwaysApply: false
+precedence: normal
+detail_rule: true
+consumed_by: hatch3r-agent-orchestration
 ---
 # Agent Orchestration — Extended Reference
 

package/{rules → dist/content/rules}/hatch3r-agent-orchestration.md

@@ -3,7 +3,8 @@ id: hatch3r-agent-orchestration
 type: rule
 description: Mandatory agent delegation, skill loading, and subagent usage directives for ALL tasks in ALL contexts
 scope: always
-tags: [core]
+tags: [orchestration, floor:protocol]
+precedence: high
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -103,6 +104,28 @@ Examples:
 
 A missing header on a tracked Tier >= 2 task is a self-detectable drift signal — the user may halt the turn and request re-grounding. The header also functions as a per-reply cache prime: rendering it forces the orchestrator to re-resolve which phase it is in before choosing tools. Tier 1 tasks, read-only answers, and chat-only iterations do NOT require the header.
 
+### End-of-Turn Delegation Attestation
+
+When the turn is on a tracked task at Tier >= 2 AND caused at least one file mutation, the orchestrator MUST emit a closing block immediately before the Iteration Summary. The block enumerates every file mutated this turn, the spawning sub-agent invocation, and the `delegation_proof_id` returned by that sub-agent.
+
+Format:
+
+```
+[hatch3r-delegation-attestation]
+files_mutated_this_turn:
+  - <relative path>: via <agent-name> (proof: <delegation_proof_id>)
+mutating_subagent_invocations: <integer>
+inline_edits_by_orchestrator: none | <carve-out: hatch3r-quick-change Tier-1 + queued re-delegation>
+```
+
+Rules:
+
+- Each `files_mutated_this_turn` row MUST cite the spawning sub-agent invocation and quote the `delegation_proof_id` returned by that sub-agent verbatim. Unattributable rows are self-declared P8 B2 violations and the orchestrator MUST queue re-delegation in the next turn.
+- `inline_edits_by_orchestrator: none` is the only acceptable value outside the `hatch3r-quick-change` Tier-1 carve-out declared in the "Inline implementation" definition above.
+- Tier 1 read-only and chat-only turns are exempt — same scope as the Per-Turn Pipeline-State Header.
+- Missing block on a Tier >= 2 mutating turn is a self-detectable drift signal — the user may halt the turn and re-ground per the same protocol as the missing-header signal.
+- The block is consumed by reviewers and the next orchestrator turn; it sits beside the Iteration Summary, not inside it, preserving the existing 5-field iteration-summary contract verbatim.
+
 ### Mandatory Delegation Directive (No Inline Implementation)
 
 Restating with maximum clarity for sub-agent prompt inclusion: the orchestrator MUST NOT call `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform-equivalent code-writing tool from its own turn. The only path for code mutation is the Task tool spawning `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3). Carve-out: `hatch3r-quick-change` Tier 1 trivial items per its declared scope. No other carve-out exists. Violations are bypass mode (see issue #73) — surface them by halting the turn and re-delegating.
@@ -132,14 +155,14 @@ For multi-sub-task implementations, the implementer performs a lightweight mini-
 
 1. Spawn `hatch3r-reviewer` with diff and acceptance criteria. Reviewer includes blast radius summary.
 2. Critical/Warning findings: spawn `hatch3r-fixer` with full reviewer output.
-3. Re-review after fixes. Repeat until 0 Critical + 0 Warning, or max 3 iterations.
+3. Re-review after fixes. Repeat until 0 Critical + 0 Warning, or max 4 iterations (matches `DEFAULT_MAX_REVIEW_ITERATIONS` in `src/pipeline/reviewLoop.ts`; raised from 3 to 4 in Cycle 7.5 W2B2 finding H26 so the oscillation detector becomes reachable in default config). The rule default and the code constant are kept in sync by `src/__tests__/pipeline/reviewLoop.test.ts` (CI-enforced).
 4. **Confirmation pass** after clean review: lightweight re-review for fix-driven regressions and acceptance criteria completeness. The confirmation pass checks only: (a) no new test failures compared to Phase 2 baseline, (b) no type errors introduced, (c) acceptance criteria from the issue are still met. It does not re-run the full review checklist.
 5. Max iterations reached: surface to user with a structured summary: iteration count, remaining Critical findings (with file:line), remaining Warning findings, and a recommendation (fix manually vs. accept risk). Never present raw reviewer output without summarization.
 6. **Review gate confidence signal:** When the review loop exits with a clean verdict, record the iteration count in `PipelineContext.reviewResult.iterations`. Clean-on-first-pass (iteration 1) signals higher confidence than clean-after-multiple-iterations (iteration 2-3). Phase 4 specialists and the orchestrator should factor this into their risk assessment.
 
 **Phase 4 — Final Quality** (after review loop is clean):
 
-Launch parallel subagents -- no artificial concurrency limit.
+Launch Phase 4 specialists in parallel, bounded by `max_phase4_parallel` (default `3`, override via `HATCH3R_MAX_PHASE4_PARALLEL` env var; valid range 1-16, values outside the range fall back to default with a logged warning). The bound exists to cap per-orchestrator concurrent context cost — it does not soften the P8 B2 directive that fan-out scales with task decomposition. When the number of applicable specialists exceeds `max_phase4_parallel`, batch them by severity-descending priority: `CRITICAL → HIGH → MEDIUM → LOW` (severity is the worst-case finding class the specialist is expected to surface, per the `hatch3r-test-writer` / `hatch3r-security-auditor` always-on baseline → CRITICAL, conditional UI/security/perf → HIGH, docs/lint → MEDIUM, low-impact specialists → LOW). Within the same severity bucket, dispatch order is the trigger-table order in the table above. Each batch runs to completion (all specialists return SUCCESS/PARTIAL/FAILED) before the next batch starts; the validation pass below runs once after the final batch.
 
 - **Always** (except when Phase Skip Criteria applies — see below)**:** `hatch3r-test-writer`, `hatch3r-security-auditor`
 - **Evaluate:** `hatch3r-docs-writer` (when APIs/architecture/UX affected)
@@ -348,6 +371,6 @@ All `scope: always` rules apply to every task including subagent work. Include r
 - `hatch3r-dependency-management` -- dependency-auditor
 
 **Tier 3 -- On-demand:**
-- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`, `hatch3r-observability-tracing-detail`
+- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`
 
 For limited context windows, Tier 1 is mandatory. Tier 2/3 included selectively by agent role and task scope.