ace-task 0.31.9 → 0.36.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c67dcf6153b34a7d6a72bf8e58bba04945835c1af53ba458391c857f49260ad
-  data.tar.gz: 68546adc536f8f70b260e6e7315bfa965112322e4e25dc737bde18b25169461d
+  metadata.gz: 81fe627b41cbd7329b370ce01458343eb34bb6dd3033772750976ab7fdbf604e
+  data.tar.gz: 55d0dd5f43f21cd4b9f83984d703905d1e66c22869fe6791a430ad1d782fdeb8
 SHA512:
-  metadata.gz: dab5c187c7f4f6c031c3510b37b6f0322e8aa73d2aeb57290d7be2d46120ec7c2ea79f4dc18c37a4bfc2d004f760ba502e7f4c377e61cfaa0c83e901cb5668ae
-  data.tar.gz: 7dd3dfd6cf4b25ea4180310ed6240ef0d421c9a724c6662bc95b926e846060b6b08cf8adf625648d878c35858268cb96ae702479c621c0398ceaf31287a22a1b
+  metadata.gz: 5683574d4b854a0aeabd3e1b22e32ab7ad2f74f4bca594316c860954d7bce927da95e9142f804c0bf9078f263f69a6960cdda009fe500e545dbee6d7d78316fc
+  data.tar.gz: b28b4bec231fe6d4461a2673d3d4cfcb753aaff3e026ca83cb26b2ed053f906ba1382f174c7e09ad8d92911219626d5445b4507f2de9b356515c14d4341ea804

data/CHANGELOG.md

@@ -7,6 +7,210 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.36.7] - 2026-04-25
+
+### Changed
+
+- Removed spike as a first-class task pattern from active ACE task drafting. Drafts must now create real child tasks for each original intention, while `as-task-review` owns the deep analysis, draft reshaping, dependency repair, and skip/split decisions for uncertain families.
+
+## [0.36.6] - 2026-04-24
+
+### Changed
+
+- Redesigned spike-task guidance around evaluation against real parent goals instead of closure mechanics alone. Spike-first parents must now declare `Learning Targets Before Decomposition`, spike subtasks must map those targets explicitly, and spikes rewrite the active in-folder task tree before later review decides lifecycle.
+- Restricted spike mutation scope to the task folder. Spikes must no longer edit package docs, handbook files, or other out-of-folder assets directly; they capture those impacts as new subtasks under the same parent instead.
+
+## [0.36.5] - 2026-04-24
+
+### Changed
+- Tightened spike-task drafting and review guidance again so spikes must declare explicit outcome tasks whose type matches the completion mode, and so `reopen later if needed` is no longer an acceptable post-spike closure.
+
+### Fixed
+- Tightened spike work guidance so a spike cannot be marked done until its declared concrete outcome task exists in addition to the synchronized parent/doc artifacts and rerun parent review.
+
+### Changed
+- Tightened spike-task workflow guidance so spike drafts must declare a decision-complete Spike Completion Contract naming completion mode, parent sync target, related artifact sync targets, and the final `as-task-review <parent-ref>` rerun.
+
+### Fixed
+- Ensured parent task auto-close for child task closure uses the same `TaskManager#update` flow as explicit task closes, so linked GitHub issues close through one consistent code path.
+- Tightened spike work/review guidance so a spike cannot be considered complete until its parent and declared related task/doc artifacts are synchronized and the parent review has been rerun.
+
+## [0.36.4] - 2026-04-24
+
+## [0.36.2] - 2026-04-23
+
+
+### Changed
+- Added layer-ownership triage into task bug-work and planning workflows to reduce cross-package misrouting of root-cause fixes.
+- Tightened task planning workflows to improve issue linkage and work-on sequencing with clearer workflow ownership validation.
+
+
+### Changed
+- Added layer-ownership triage to bug analysis/fix and task planning/work workflows so agents identify owner, adapter, and symptom packages before implementing cross-package shared-primitive fixes.
+- Tightened the task draft workflow so GitHub issue URL inputs must create the parent or single task with `--github-issue <number>` and sync the linked issue.
+
+### Technical
+- Added workflow contract coverage for the layer-ownership triage guidance.
+## [0.36.1] - 2026-04-19
+
+### Technical
+- Decoupled retained create/list/show and archive E2E goals so task root-state evidence is captured before later archive movement.
+- Clarified `TS-TASK-002` plan-path verification so bounded planner timeout diagnostics are accepted as actionable sandbox evidence.
+
+## [0.36.0] - 2026-04-16
+
+### Changed
+- Added `ace-task plan --timeout` so path-based plan generation can be bounded explicitly from the public CLI.
+- Documented bounded plan generation and timeout troubleshooting in the getting-started and usage guides.
+
+### Fixed
+- Converted planner-provider timeout failures into actionable CLI errors instead of surfacing raw timeout backtraces.
+- Updated `TS-TASK-002` path-mode verification to accept explicit timeout diagnostics when plan generation cannot complete within the requested bound.
+
+## [0.35.7] - 2026-04-16
+
+### Fixed
+- Refined `TS-TASK-001` smoke verification around sandbox-root task trees, archive layout, and invalid-status doctor evidence so retained E2E goals track the current public CLI behavior.
+
+## [0.35.6] - 2026-04-15
+
+### Fixed
+- Tightened `TS-TASK-002` plan-path verification to require at least one successful path-mode plan artifact while keeping explicit diagnostics for failed dependency paths.
+
+## [0.35.5] - 2026-04-15
+
+### Changed
+- Reworked retained `TS-TASK-001` goal contracts to use deterministic task-ref handoff artifacts across create/show/update/archive smoke journeys.
+- Added `TS-TASK-002` auxiliary public CLI journeys for `status` and `plan` command coverage, with explicit sandbox diagnostics for unavailable planning dependencies.
+- Updated usage docs with E2E-safe `ace-task plan <ref>` path-mode guidance and `github-sync` precondition examples.
+- Tightened spike-task drafting, review, and work-on-task guidance so spikes must declare whether they are design-contract or proof-of-concept work, define explicit follow-up tasks, and stop implementation flow when runtime work materially drifts from the promised spike contract.
+
+## [0.35.4] - 2026-04-13
+
+### Fixed
+- Reworked `TS-TASK-001` smoke coverage to validate created and archived tasks from stable task-tree state plus runner observations instead of brittle helper files under `results/`.
+
+## [0.35.3] - 2026-04-13
+
+### Fixed
+- Hardened `TS-TASK-001` task-ref capture so create/show/archive smoke coverage derives the persisted short ref from stable list/filesystem evidence instead of brittle prose parsing.
+
+## [0.35.2] - 2026-04-13
+
+### Technical
+- Refreshed `TS-TASK-001` archive and doctor smoke scenario contracts to match the current `_archive` layout and isolate the invalid-status validation path.
+
+## [0.35.1] - 2026-04-13
+
+### Fixed
+- Accepted subtask IDs in task frontmatter ID validation so doctor frontmatter checks no longer report false invalid-ID errors for valid subtasks.
+- Added atomic task-ID reservation during create so concurrent creates treat lock contention as retryable collisions instead of racing through non-atomic prechecks.
+
+### Technical
+- Narrowed task ID-existence scans to ID-prefixed glob matches and added regression coverage for subtask ID validation plus reservation-lock collision behavior.
+
+## [0.35.0] - 2026-04-13
+
+### Fixed
+- Added duplicate persisted task-ID detection to doctor health checks, including subtask collisions and frontmatter-only doctor validation failures.
+- Added bounded retry handling for standalone `ace-task create` ID collisions with clear retry-exhaustion failures and no partial-artifact leakage.
+
+### Technical
+- Added regression coverage for duplicate-ID doctor failures, create-time retry semantics, and cleanup guarantees.
+
+## [0.34.3] - 2026-04-13
+
+### Fixed
+- Added bounded retry handling for standalone `ace-task create` ID collisions so success is emitted only after a unique persisted task ID exists.
+- Added clear retry-exhaustion failure messaging for create-time ID collisions.
+
+### Technical
+- Added command and molecule regression coverage for task ID collision retries and partial-artifact cleanup guarantees.
+
+## [0.34.2] - 2026-04-13
+
+### Fixed
+- Report duplicate persisted task IDs as explicit doctor health-check errors with file-path context, including top-level and subtask collisions.
+- Include duplicate ID detection in `ace-task doctor --check frontmatter` and fail health status when duplicates are present.
+
+### Technical
+- Added organism and CLI regression coverage for duplicate top-level/subtask ID failures and frontmatter-only doctor checks.
+
+## [0.34.1] - 2026-04-13
+
+### Changed
+- Completed the batch i05 migration follow-through for this package and aligned it with the restarted `fast` / `feat` / `e2e` verification model.
+
+### Technical
+- Included in the coordinated assignment-driven patch release for batch i05 package updates.
+
+
+### Changed
+- Expanded canonical `as-task-plan` and `as-task-work` skill metadata so public `plan-task` and `work-on-task` assign-step discovery is skill-owned rather than catalog-owned.
+
+## [0.34.0] - 2026-04-12
+
+### Changed
+- Migrated package tests to the restarted `fast` / `feat` / `e2e` model by moving deterministic coverage to `test/fast`, retaining `TS-TASK-001` as workflow-value E2E coverage, and updating package testing guidance.
+
+### Fixed
+- Hardened `TS-TASK-001` sandbox bootstrap and doctor error-path runner setup so repeated E2E runs start from a clean healthy baseline before malformed-task injection.
+
+## [0.33.3] - 2026-04-07
+
+### Changed
+- Added linked GitHub issue metadata handling as a single ownership model and kept task/task manager sync behavior aligned with linked-task life cycle updates.
+
+### Fixed
+- Fixed GitHub sync dispatch and manual sync verification paths by routing through the reusable sync flow and tightening demo-task linkage checks.
+
+### Technical
+- Expanded test coverage around GitHub sync assertions, frontmatter ownership validation, and workflow-level linked issue behavior.
+
+## [0.33.2] - 2026-04-07
+
+### Changed
+- Updated the live GitHub sync demo tape to declare semantic verification expectations for exported issue/task refs, forbidden error output, and final closed-issue state.
+
+## [0.33.1] - 2026-04-07
+
+### Fixed
+- Corrected create-time GitHub sync dispatch so `ace-task` resolves the reusable `sync_task` integration instead of the ownership-validator entrypoint.
+- Fixed the live GitHub sync demo tape to recover the created task ref from slugified task filenames during recording.
+
+## [0.33.0] - 2026-04-07
+
+### Fixed
+- Hardened linked-issue synchronization by loading `ace/git` on the main runtime path, reconciling previous/current issue ID sets during updates, and treating GitHub sync failures as non-blocking task warnings.
+- Surfaced manual `github-sync` failures with per-task error details and an explicit non-zero CLI failure when requested sync work does not complete.
+- Updated linked issue sync payloads to use task spec file paths for sticky comment links so GitHub issue references land on `.s.md` source-of-truth files.
+- Updated `ace-task create` to print non-blocking GitHub sync warnings (`last_update_note`) so create-time linked-issue sync failures are visible to operators.
+- Replaced array-style linked issue metadata with singular `github_issue` ownership and reject duplicate `--github-issue` flags.
+
+### Changed
+- Updated ACE-linked GitHub issue lifecycle guidance to treat task metadata and ACE-managed sync as the canonical path, while keeping PR footer closure keywords as optional manual guidance.
+- Updated linked GitHub issue storage and task-manager sync hooks to enforce one canonical owning task per GitHub issue.
+- Reworked the GitHub sync demo to show live issue creation, task linkage, and automatic issue closure.
+
+### Technical
+- Added linked-issue metadata contract checks to task draft/review workflow instructions and aligned related task spec examples for consistency.
+- Expanded create/update/frontmatter/manager test coverage for singular `github_issue` ownership and conflict handling.
+
+## [0.32.0] - 2026-04-05
+
+### Added
+- Added `ace-task github-sync` command for manual linked-issue synchronization by task reference or `--all`.
+- Added `--github-issue` create-time linkage support for storing machine-readable `github_issue` task metadata.
+- Added lifecycle sync orchestration through `TaskManager` and `GithubIssueSyncAdapter` for linked task create/update/reparent flows.
+
+### Changed
+- Extended task frontmatter defaults to emit structured `github_issue` metadata when linked issues are provided.
+- Updated `ace-task` usage documentation with linked issue create flags and manual sync command usage.
+
+### Technical
+- Added validation rules for `github` and `github_issue` frontmatter structure and numeric issue IDs.
+- Expanded command/organism/validator/defaults test coverage for linked issue metadata and sync behavior.
+
 ## [0.31.9] - 2026-03-31
 
 ### Changed

data/README.md

@@ -26,6 +26,13 @@ Tasks are markdown specs living in git - attached to branches and worktrees, not
 2. Review and planning workflows refine scope before implementation.
 3. Oversee execution through worktrees and assignments until ship-ready.
 
+## Testing Model
+
+- `ace-test ace-task` runs deterministic package tests (`test/fast`) for the default feedback loop.
+- `ace-test ace-task feat` runs deterministic feature coverage when `test/feat` exists.
+- `ace-test ace-task all` runs all deterministic lanes.
+- `ace-test-e2e ace-task` runs retained real workflow scenarios from `test/e2e`.
+
 ## Use Cases
 
 **Draft and structure work** - create a task, split it into subtasks, add new subtasks as work reveals scope. Use `/as-task-draft` to draft from an earlier captured [idea](../ace-idea) or short note, or [`ace-task create`](docs/usage.md#ace-task-create-title) from the CLI.

data/handbook/guides/task-definition.g.md

@@ -2,13 +2,13 @@
 doc-type: guide
 purpose: Guide for writing clear, actionable task definitions in ace-task
 ace-docs:
-  last-updated: '2026-03-21'
+  last-updated: '2026-04-25'
 ---
 
 <!-- markdownlint-disable -->
-# 📑 Writing Clear, Actionable Dev Tasks
+# 📑 Writing Clear, Actionable Dev Tasks
 
-## A playbook for documentation‑oriented tickets, with a complete worked example
+## A playbook for documentation-oriented tickets, with a complete worked example
 
 ## Introduction & Goal
 
@@ -19,7 +19,7 @@ minimize ambiguity and streamline the process of defining and executing document
 
 ---
 
-## 0. Directory Audit Step ✅
+## 0. Directory Audit Step ✅
 
 **Always start by discovering what actually exists in the repo.**
 
@@ -28,7 +28,7 @@ minimize ambiguity and streamline the process of defining and executing document
 3. From that listing, build the deliverable manifest.
 
 > **Tip:**
-> • If you don’t have repo access, create a tiny *pre‑ticket* titled “Generate Guide‑Audit Manifest”.
+> • If you don’t have repo access, create a tiny *pre-ticket* titled “Generate Guide-Audit Manifest”.
 > • Commit the tree output as a comment or markdown file, then reference it in the main ticket.
 
 Example audit snippet to embed:
@@ -45,18 +45,18 @@ guides
 
 ---
 
-## 1. Anatomy of a Great Task
+## 1. Anatomy of a Great Task
 
-| Section | Purpose | Key Questions |
+| Section | Purpose | Key Questions |
 |---------|---------|---------------|
-| **Front‑matter** | Helps tooling & humans filter | id (use `task-manager generate-id VERSION` to generate), status, priority, estimate, dependencies |
+| **Front-matter** | Helps tooling & humans filter | id (use `task-manager generate-id VERSION` to generate), status, priority, estimate, dependencies |
 | **Objective / Problem** | *Why* are we doing this? | What pain are we fixing? |
-| **Directory Audit (0)** | Source‑of‑truth for scope | Did we include the current tree? |
+| **Directory Audit (0)** | Source-of-truth for scope | Did we include the current tree? |
 | **Scope of Work** | *What* to touch | Which guides/folders? |
 | **Deliverables / Manifest** | Exact files to create / modify / delete | Could a newcomer do it with just this? |
-| **Phases** | Bite‑sized plan | Audit → Extract → Refactor → Index |
+| **Phases** | Bite-sized plan | Audit → Extract → Refactor → Index |
 | **Implementation Plan** | Divided into Planning Steps (`* [ ]`) for analysis/design and Execution Steps (`- [ ]`) for implementation actions. Consider embedding automated test/verification steps directly. | |
-| **Acceptance Criteria** | Definition of Done | Check‑list style `[ ]`. **Can include references to automated checks defined in the Implementation Plan's Planning and Execution sections or be high-level checks themselves.** |
+| **Acceptance Criteria** | Definition of Done | Check-list style `[ ]`. **Can include references to automated checks defined in the Implementation Plan's Planning and Execution sections or be high-level checks themselves.** |
 | **Out of Scope** | Prevent scope creep | What must *not* be touched? |
 | **References & Risks** | Links to style guides, ADRs, **testing standards (like [Embedded Testing Guide](ace-docs/handbook/guides/embedded-testing-guide.g.md))**; mitigations | Any scripts to run? **Use links relative to the project root (e.g., `ace-handbook/handbook/guides/some-guide.g.md`), not relative to the current file (`../guides/some-guide.md`)** |
 
@@ -88,7 +88,7 @@ This distinction supports workflow separation where review/planning phases focus
 
 ---
 
-## 3. **Full Worked Example**
+## 3. Full Worked Example
 
 A full worked example of a task, "Tailor Guides to Tech Stack," has been moved to a separate file:
 [`ace-task/handbook/templates/release-tasks/example.md`](../templates/release-tasks/example.md)
@@ -153,4 +153,38 @@ For complex tasks requiring analysis or design decisions, include both sections:
 6. Are Planning Steps used for complex tasks requiring analysis/design?
 7. Do visual markers distinguish planning (`* [ ]`) from execution (`- [ ]`) steps?
 
-Tick them all → merge the ticket.
+Tick them all → merge the ticket.
+
+---
+
+## Review-first task shaping
+
+ACE no longer uses spike as a special task type.
+
+### Rules
+
+1. The parent owns the umbrella outcome and the child-task map.
+2. Every original intention that matters must exist as a real child task from the start.
+3. If ordering matters, the first child should be the smallest real vertical slice, not a synthetic research-only task.
+4. `as-task-review` is the deep-analysis stage: it may rewrite, split, reorder, skip, or dependency-shape draft subtasks after codebase research.
+5. Do not preserve major uncertainty only in parent prose. If a goal matters enough to protect, give it a child task.
+6. If review later proves a drafted child obsolete or already satisfied, review updates the task family directly instead of relying on a dedicated spike artifact.
+
+### Parent responsibility
+
+The parent should keep:
+- umbrella objective
+- why the family exists
+- decomposition map of child refs and concerns
+- shared boundaries or references
+
+The parent should not hide work that has no child owner.
+
+### Child responsibility
+
+Each child task should own:
+- one concrete slice of the original intention
+- its own interface contract and success criteria
+- its own verification plan
+
+If a single child is trying to answer multiple independent questions, split it before implementation.

data/handbook/skills/as-task-draft/SKILL.md

@@ -3,7 +3,7 @@ name: as-task-draft
 description: Draft Task with Idea File Movement (SPECS ONLY - no code)
 # bundle: wfi://task/draft
 # context: no-fork
-# agent: general-purpose
+# agent: Plan
 user-invocable: true
 allowed-tools:
   - Bash(ace-task:*)
@@ -22,3 +22,9 @@ skill:
 ---
 
 Load and run `ace-bundle wfi://task/draft` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.
+
+This skill is for specification work only.
+
+- Create or update draft task artifacts only.
+- Do not implement package code, tests, or runtime behavior changes.
+- If the user later says "implement", treat that as continuing the drafting/spec workflow unless they explicitly switch to `as-task-work` / `wfi://task/work`.

data/handbook/skills/as-task-plan/SKILL.md

@@ -18,10 +18,15 @@ skill:
   execution:
     workflow: wfi://task/plan
 assign:
-  source: wfi://task/plan
   steps:
     - name: plan-task
       description: Analyze task requirements and create an implementation plan
+      produces: [implementation-plan]
+      consumes: [project-base-context, task-spec]
+      when_to_skip:
+        - "Task is trivial and doesn't need a plan"
+        - "Implementation plan already exists"
+      effort: light
       tags: [planning, analysis]
       context:
         default: fork

data/handbook/skills/as-task-work/SKILL.md

@@ -17,7 +17,6 @@ argument-hint: [task-id like 123]
 last_modified: 2026-02-17
 source: ace-task
 assign:
-  source: wfi://task/work
   steps:
     - name: work-on-task
       description: Implement task changes following project conventions
@@ -27,6 +26,12 @@ assign:
           - "implement task"
           - "task work"
           - "build feature"
+      produces: [code-changes, commits]
+      consumes: [project-base-context, task-spec]
+      when_to_skip:
+        - "Task is documentation-only"
+        - "Changes are already implemented"
+      effort: medium
       tags: [implementation, core-workflow]
       context:
         default: fork

data/handbook/templates/task/draft.template.md

@@ -15,7 +15,7 @@ bundle:
 doc-type: template
 purpose: Template for drafting task definitions
 ace-docs:
-  last-updated: '2026-03-21'
+  last-updated: '2026-04-25'
 ---
 
 # {title}
@@ -98,7 +98,7 @@ GET/POST/PUT/DELETE /endpoint
 <!-- Ask about unclear requirements, edge cases, and user expectations -->
 
 - [ ] **Requirement Clarity**: [Question about unclear or ambiguous requirements]
-- [ ] **Edge Case Handling**: [Question about boundary conditions or unusual scenarios]  
+- [ ] **Edge Case Handling**: [Question about boundary conditions or unusual scenarios]
 - [ ] **User Experience**: [Question about user expectations, workflows, or interactions]
 - [ ] **Success Definition**: [Question about how success will be measured or validated]
 
@@ -135,7 +135,7 @@ Why are we doing this? Focus on user value and behavioral outcomes.
 <!-- Define the behavioral scope - what user experiences and system behaviors are included -->
 
 - **User Experience Scope**: [Which user interactions, workflows, and experiences are included]
-- **System Behavior Scope**: [Which system capabilities, responses, and behaviors are included]  
+- **System Behavior Scope**: [Which system capabilities, responses, and behaviors are included]
 - **Interface Scope**: [Which APIs, commands, or interfaces are included]
 
 ### Deliverables
@@ -143,7 +143,7 @@ Why are we doing this? Focus on user value and behavioral outcomes.
 
 #### Behavioral Specifications
 - User experience flow definitions
-- System behavior specifications  
+- System behavior specifications
 - Interface contract definitions
 
 #### Validation Artifacts
@@ -169,7 +169,7 @@ Why are we doing this? Focus on user value and behavioral outcomes.
 <!-- Explicitly exclude implementation concerns to maintain behavioral focus -->
 
 - ❌ **Implementation Details**: File structures, code organization, technical architecture
-- ❌ **Technology Decisions**: Tool selections, library choices, framework decisions  
+- ❌ **Technology Decisions**: Tool selections, library choices, framework decisions
 - ❌ **Performance Optimization**: Specific performance improvement strategies
 - ❌ **Future Enhancements**: Related features or capabilities not in current scope
 
@@ -177,4 +177,4 @@ Why are we doing this? Focus on user value and behavioral outcomes.
 
 - Related capture-it output (if applicable)
 - User experience requirements
-- Interface specification examples
+- Interface specification examples

data/handbook/workflow-instructions/bug/analyze.wf.md

@@ -156,7 +156,29 @@ Systematically analyze bug reports to identify root cause, verify reproduction,
    - Contributing factors (conditions that enable the bug)
    - Impact scope (what else might be affected)
 
-### 5. Propose Regression Tests
+### 5. Layer Ownership Triage
+
+Before finalizing the fix plan, identify the layer that owns the failing primitive. This is required when the bug crosses package boundaries or involves shared external resources, protocols, command routing, configuration namespaces, or reusable helper APIs.
+
+Classify each relevant package/component:
+
+- **Owner/creator**: creates, names, persists, routes, or navigates the primitive
+- **Adapter/orchestrator**: coordinates owner APIs for a workflow
+- **Consumer/symptom**: exposes the failure but does not own the primitive
+
+Answer these questions in the analysis:
+
+- What is the failing primitive or contract?
+- Which package creates or names it?
+- Which package navigates, reuses, or cleans it up?
+- Which package only exposed the symptom?
+- Is there a shared package/API that all callers should use?
+
+Default fix rule: fix the owner layer first, then update adapters/consumers only to call the shared behavior. Do not propose a consumer-only fix when an owner layer exists and has not been inspected.
+
+Example: if `ace-assign` fails because `ace-t.k5a-fs` is parsed incorrectly as a tmux target, the failing primitive is tmux window naming/targeting. `ace-tmux` owns window creation, naming, and navigation, so the primary fix belongs in `ace-tmux`; `ace-assign` and `ace-overseer` should reuse the shared policy.
+
+### 6. Propose Regression Tests
 
 **Design tests to catch this bug:**
 
@@ -185,24 +207,26 @@ Systematically analyze bug reports to identify root cause, verify reproduction,
 - Purpose: Verify [specific behavior] handles [edge case]
 - Scenario: When [condition], expect [result]
 
-**Integration Test: [test name]**
-- Location: test/integration/[flow]_test.rb
+**Feature Test: [test name]**
+- Location: test/feat/[flow]_test.rb
 - Purpose: Verify [workflow] completes correctly
 - Scenario: Given [setup], when [action], then [verification]
 ```
 
-### 6. Create Fix Plan
+### 7. Create Fix Plan
 
 **Document the fix strategy:**
 
 1. **Files to modify:**
    - List each file that needs changes
    - Describe the type of change for each
+   - Mark each file as owner, adapter/orchestrator, or consumer/symptom when layer ownership triage applies
 
 2. **Fix approach:**
    - Describe the technical solution
    - Explain why this approach was chosen
    - Note any alternative approaches considered
+   - Explain why the fix is placed in the owner layer, or why no owner-layer change is needed
 
 3. **Risks and side effects:**
    - What else might be affected by the fix
@@ -213,7 +237,7 @@ Systematically analyze bug reports to identify root cause, verify reproduction,
    - How to revert if issues arise
    - What to check after reverting
 
-### 7. Save Analysis Results
+### 8. Save Analysis Results
 
 **Cache the analysis for fix-bug workflow:**
 
@@ -228,6 +252,14 @@ mkdir -p .ace-local/task/bug-analysis/{session}
 # .ace-local/task/bug-analysis/{session}/analysis.yml
 root_cause: "Description of root cause"
 repro_status: confirmed | not_reproducible | intermittent
+layer_ownership:
+  primitive: "Shared resource/protocol/API involved, if any"
+  owner: "Package/component that owns creation/naming/routing"
+  adapters:
+    - "Adapter/orchestrator package, if any"
+  consumers:
+    - "Symptom package, if any"
+  fix_layer: "owner | adapter | consumer | not_applicable"
 affected_files:
   - path: path/to/file.rb
     change_summary: "Description of what change is needed"
@@ -357,7 +389,7 @@ Present the analysis to the user in this format:
    - Purpose: [What it validates]
 
 2. **[Test Name]** (integration)
-   - File: `test/integration/flow_test.rb`
+   - File: `test/feat/flow_test.rb`
    - Purpose: [What it validates]
 
 ### Fix Plan
@@ -420,7 +452,7 @@ This workflow provides systematic bug analysis that ensures proper investigation
    - Purpose: [What it validates]
 
 2. **[Test Name]** (integration)
-   - File: `test/integration/flow_test.rb`
+   - File: `test/feat/flow_test.rb`
    - Purpose: [What it validates]
 
 ### Fix Plan
@@ -455,4 +487,4 @@ risks:
   - "Potential side effect description"
 rollback_plan: "How to revert if issues arise"
 </template>
-</documents>
+</documents>

data/handbook/workflow-instructions/bug/fix.wf.md

@@ -67,6 +67,7 @@ ls .ace-local/task/bug-analysis/
 - Load the analysis.yml from the most recent session
 - Review root cause, affected files, and proposed tests
 - Confirm the fix plan with user if needed
+- Review `layer_ownership` when present and verify the planned fix targets the owner layer before adapters or consumers
 
 **If no analysis exists:**
 
@@ -74,6 +75,16 @@ ls .ace-local/task/bug-analysis/
 - Gather: affected files, root cause, proposed solution
 - Document the fix approach before proceeding
 
+**Layer ownership guard:**
+
+When the bug crosses package boundaries or involves a shared primitive, classify packages before editing:
+
+- **Owner/creator**: creates, names, persists, routes, or navigates the primitive
+- **Adapter/orchestrator**: coordinates owner APIs for a workflow
+- **Consumer/symptom**: exposes the failure but does not own the primitive
+
+If the loaded/user-provided plan changes only a consumer/symptom package while an owner layer exists and was not inspected, stop and return to analysis. Do not implement a local workaround before checking the owner package.
+
 ### 2. Prepare for Fix
 
 **Set up the fix branch:**
@@ -100,12 +111,14 @@ git checkout -b fix/[bug-description]
    - Review surrounding code
    - Understand dependencies
    - Check for similar patterns in codebase
+   - If the file is a consumer of a shared primitive, inspect the owner package/API before changing local policy
 
 2. **Apply the fix:**
    - Make minimal changes to fix the bug
    - Follow existing code style and patterns
    - Add appropriate error handling
    - Include inline comments only if logic is non-obvious
+   - Put shared policy in the owner layer and have adapters/consumers call that policy
 
 3. **Review the change:**
    - Verify the fix addresses root cause
@@ -140,7 +153,7 @@ git checkout -b fix/[bug-description]
 
 2. **Create integration test if needed:**
    ```ruby
-   # Example: test/integration/workflow_test.rb
+   # Example: test/feat/workflow_test.rb
    def test_complete_flow_with_missing_data
      # Test the full workflow that exhibited the bug
    end
@@ -509,4 +522,4 @@ The fix is ready for code review and merge.
 ### Notes
 [Any additional context about the fix]
 </template>
-</documents>
+</documents>