ace-task 0.36.1 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34781c3bdaae6a3d794b1d2ff7654b80cd0c6df85377960ca85e6b9e3868bf20
-  data.tar.gz: a9da028f06155e0dfa3dd24f39c8d625d1768c965e26af2351f6f5e477d3510e
+  metadata.gz: 0c904888ee87cacc7e50943b71c57903e2b4b86e100fd430a39888268ae52c10
+  data.tar.gz: b7a750de5413603f17f69aba61bb18cef0c522167b69fcee88dbdfd8052feea1
 SHA512:
-  metadata.gz: '0189d7b62882f379f721d5c34a3e5e0ca4aad445631cddc9ab88ecb46c235eb500df1a633be1ccb9dff9aba5c4267935c037baded1d4a3bdc7a76568c2940a2e'
-  data.tar.gz: 755d4133499d1e4f005645affb13a8b723e1f1f48d5739072c25af44e29c172b3b7b068fc7def6e32ebf4a72af8cbcbf88f957e3f990c6fd4fd2711227561a0a
+  metadata.gz: e0d87b222c10a7b7253771f5c8c01f56d9326638cb0a56878d3d768d8988cb63758551cc24800f82f68516e25b36d87ff7a8a43d4fcef7e674027178b1b61c70
+  data.tar.gz: e0e3b6b034578fb56b13acf58a6cc4e412bf941077f06bcc492fb87cfee059524ac0cfc3bbb791c68c7af299ff20e685eeb4571787ab2fe4541e668aff84db59

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-06-30
+
+### Added
+
+- Accepted `--title` as an alternate title input for `ace-task create`, with clear conflict handling when both title forms are provided.
+
+## [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

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/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:**
 
@@ -191,18 +213,20 @@ Systematically analyze bug reports to identify root cause, verify reproduction,
 - 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"

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

data/handbook/workflow-instructions/task/draft.wf.md

@@ -1,19 +1,18 @@
 ---
 name: task-draft
 allowed-tools: Bash, Read
-description: Create behavior-first draft tasks and subtasks with vertical slicing
-  and verification plans
+description: Create high-level behavioral specifications that define WHAT the system should do (UX/DX/AX) rather than HOW to implement it. This workflow transforms ideas or requirements into behavior-first draft tasks with clear interface contracts, leaving implementation details for the replan step. This workflow also includes automated idea file management, moving original idea files to organized locations with task number prefixes for clear traceability.
 doc-type: workflow
 purpose: task draft workflow instruction
 ace-docs:
-  last-updated: '2026-03-21'
+  last-updated: '2026-04-25'
 ---
 
 # Draft Task - Behavior-First Specification
 
 ## Goal
 
-Create high-level behavioral specifications that define WHAT the system should do (UX/DX/AX) rather than HOW to implement it. This workflow transforms ideas or requirements into behavior-first draft tasks with clear interface contracts, leaving implementation details for the replan step. The workflow also includes automated idea file management, moving original idea files to organized locations with task number prefixes for clear traceability.
+Create high-level behavioral specifications that define WHAT the system should do (UX/DX/AX) rather than HOW to implement it. This workflow transforms ideas or requirements into behavior-first draft tasks with clear interface contracts, leaving implementation details for the replan step. This workflow also includes automated idea file management, moving original idea files to organized locations with task number prefixes for clear traceability.
 
 ## Prerequisites
 
@@ -36,6 +35,11 @@ Create high-level behavioral specifications that define WHAT the system should d
      * User stories or experience descriptions
      * Interface specifications or contracts
    * If files are referenced, read their contents
+   * If the input is a GitHub issue URL, extract the issue number and treat it
+     as task lifecycle metadata. Use that number with `ace-task create
+     --github-issue <number>` when creating the parent task or single flat task.
+     The issue URL may still appear in the task body as source context, but the
+     lifecycle link belongs in task frontmatter as `github_issue`.
    * **Intent mapping from enhanced ideas**: When the source idea contains the
      3-Question Delegation Brief sections (`What I Hope to Accomplish`,
      `What "Complete" Looks Like`, `Success Criteria`), use them as the
@@ -79,6 +83,7 @@ Create high-level behavioral specifications that define WHAT the system should d
         - What users experience: [UX description]
         - Interface contract: [CLI/API/UI examples]
         - Success criteria: [Measurable outcomes]
+        - Linked GitHub issue: #[issue-number] (when drafting from a GitHub issue)
         - Status: draft (needs implementation planning)
 
      2. [Next Task Title] - [User experience summary]
@@ -111,6 +116,8 @@ Create high-level behavioral specifications that define WHAT the system should d
      * Integration/E2E scenarios when behavior crosses boundaries
      * At least one invalid/failure-path scenario
    * Capture required context files per slice for fresh sessions in `bundle.files`
+   * Draft real child subtasks immediately when a parent has multiple original intentions
+   * Do not preserve major goals only in parent prose; if an intention matters, it must exist as a real child task/subtask
 
 7. **Determine Storage Location and Create Draft Tasks**
 
@@ -127,12 +134,14 @@ Create high-level behavioral specifications that define WHAT the system should d
    **Pattern A -- Single flat task (default):**
    ```bash
    ace-task create "Task Title" --status draft --estimate "TBD"
+   ace-task create "Task Title" --status draft --estimate "TBD" --github-issue 276
    ```
 
    **Pattern B -- Orchestrator with subtasks:**
    ```bash
    # 1. Create the parent task first
    ace-task create "Parent Title" --status draft --estimate "TBD"
+   ace-task create "Parent Title" --status draft --estimate "TBD" --github-issue 276
    # Returns: v.X.Y+task.NNN
 
    # 2. Add each subtask with --child-of (auto-converts parent to orchestrator)
@@ -157,36 +166,22 @@ Create high-level behavioral specifications that define WHAT the system should d
    * For subtasks, list required shared context files explicitly in EACH subtask's bundle (no implicit inheritance)
    * Include behavioral specification template
    * Focus on behavioral content, leave implementation for replan step
+   * When drafting from a GitHub issue:
+     * Put `--github-issue <number>` only on the parent/orchestrator or single
+       flat task create command unless separate subtasks each own distinct
+       GitHub issues.
+     * Run `ace-task github-sync <parent-or-task-ref>` after creation so the
+       GitHub issue receives the ACE task tracking update.
 
-### Spike-First Rule for Engine/Pipeline Redesigns
+### Review-First Rule for Uncertain Drafts
 
-When an orchestrator task redesigns a core execution path (test runner, build pipeline,
-deployment flow), the FIRST subtask should be a time-boxed spike that:
-1. Validates the target architecture end-to-end with a single scenario
-2. Identifies which existing concepts survive and which get removed
-3. Produces a "concept inventory" showing what the final system looks like
+When requirements are uncertain, do not create a special spike task. Draft the real goal subtasks immediately, then let later `as-task-review` do the deep analysis.
 
-Only AFTER the spike validates the end-state should remaining subtasks be drafted.
-This prevents decomposing into subtasks that add concepts the spike later proves unnecessary.
-
-**Anti-pattern**: 8 subtasks drafted upfront, each adding features, then a late subtask undoes half.
-**Correct pattern**: 1 spike subtask validates the end-state, then remaining subtasks build toward it.
-
-Every spike-first draft must also declare the spike type:
-- **Design-contract spike**: validates target behavior and ownership boundaries, but does not yet claim runnable proof
-- **Proof-of-concept spike**: validates target behavior with runnable proof, not only a design contract
-
-For both spike types, the draft must include:
-1. one **Validated End-State Scenario**
-2. one **Concept Inventory** with kept / changed / new / rejected outcomes
-3. one **Adopted Decisions / Rejected Decisions / Deferred Gaps** section
-4. one **Follow-up Tasks After Spike** section naming the next implementation or adoption work that must happen if the spike succeeds
-
-For proof-of-concept spikes, the draft must additionally include:
-1. one concrete **Proof Artifact Plan** describing what runnable evidence will prove the spike
-2. success criteria that require the proof artifact, not only the concept inventory
-
-Do not treat "we now understand the design" as sufficient spike completion when the spike affects a runtime, UX, or execution-path contract. A useful spike must also leave a clear proof path and explicit next task.
+1. The parent owns the umbrella outcome and decomposition map only.
+2. Each original intention or goal must exist as a real child subtask from the start.
+3. If ordering matters, make the first child the smallest real vertical slice that validates the riskiest path.
+4. Review may later rewrite, split, reorder, skip, or add dependencies between draft subtasks.
+5. Do not preserve uncertainty by inventing a dedicated research-only subtask when normal review can answer it.
 
 8. **Complete Behavioral Specifications**
    * For each created draft task, populate with:
@@ -248,19 +243,20 @@ Do not treat "we now understand the design" as sufficient spike completion when
    * **Validation Checklist:**
      * [ ] All behavioral requirements captured as drafts
      * [ ] Task files have status: draft
+     * [ ] GitHub issue inputs are linked through `github_issue` frontmatter on the parent/single task
+     * [ ] Linked GitHub issue inputs have been synced with `ace-task github-sync <ref>`
      * [ ] Behavioral specifications are complete
      * [ ] Interface contracts are defined
      * [ ] Success criteria are measurable
      * [ ] Vertical slices are defined using task/subtask model (no horizontal-only decomposition)
+     * [ ] Every original intention is represented as a real task/subtask, not only parent prose
      * [ ] Verification Plan includes unit/equivalent validation, integration/E2E when needed, and failure path checks
      * [ ] `bundle` frontmatter exists with canonical key order (`presets`, `files`, `commands`)
      * [ ] Required context artifacts are explicitly listed in `bundle.files` for each task/subtask
      * [ ] Draft is decision-complete: no unresolved behavior choices left for implementer
      * [ ] Defaults are explicit where behavior could otherwise be ambiguous
      * [ ] Usage documentation created in `ux/usage.md` (when task changes any API surface)
-     * [ ] Spike tasks declare whether they are `design-contract` or `proof-of-concept`
-     * [ ] Spike tasks include explicit follow-up task(s) after the spike
-     * [ ] Proof-of-concept spikes include a runnable proof artifact plan
+     * [ ] For uncertain families, the first slice is still a real subtask rather than a dedicated spike
 
 12. **Run Quality Pass (Better, Not More)**
    * Perform one concise quality pass before finalizing:
@@ -354,6 +350,10 @@ All code implementation happens during `ace-bundle wfi://task/work` (status: in-
 * All tasks have status: draft
 * No implementation details mixed with behavioral requirements
 * Clear handoff to review-task for readiness validation and promotion to pending
+* **REQUIRED when drafting from a GitHub issue URL:**
+  * The parent/orchestrator or single flat task is created with `--github-issue <number>`
+  * The task frontmatter contains `github_issue: <number>`
+  * `ace-task github-sync <ref>` has updated the linked issue
 * **REQUIRED when drafting from ideas:**
   * All source idea files marked as done via `ace-idea move <id> --to archive`
   * Task references updated to new idea file locations
@@ -377,6 +377,15 @@ All code implementation happens during `ace-bundle wfi://task/work` (status: in-
 **Example 3: Interface-focused requirements**
 > "Draft task for CLI tool: auth-manager with login, logout, and status commands"
 
+**Example 4: GitHub issue integration**
+> "Draft a task from https://github.com/cs3b/ace/issues/276"
+
+Create the parent or single task with the linked issue number:
+
+```bash
+ace-task create "Task Title" --status draft --estimate "TBD" --github-issue 276
+```
+
 ---
 
 This workflow creates behavior-first specifications that serve as clear contracts for implementation, ensuring user value is defined before technical details are considered.

data/handbook/workflow-instructions/task/plan.wf.md

@@ -137,6 +137,16 @@ The plan will be consumed by a separate execution agent that has no access to th
      - List consumer packages that will need coordinated updates
    - Document the full downstream scope before implementation begins
 
+   **Layer Ownership Triage:**
+   - For tasks involving shared resources, external protocols, command routing, configuration namespaces, or cross-package helpers, identify the owner layer before choosing files to edit.
+   - Classify relevant packages/components as:
+     - **Owner/creator**: creates, names, persists, routes, or navigates the primitive
+     - **Adapter/orchestrator**: coordinates owner APIs for a workflow
+     - **Consumer/symptom**: exposes the issue but does not own the primitive
+   - Default to implementing shared policy in the owner layer, then update adapters/consumers to call it.
+   - Do not plan a consumer-only fix when an owner layer exists and has not been inspected.
+   - Example: for tmux window-name failures surfaced by `ace-assign`, inspect `ace-tmux` first because it owns tmux window creation, naming, and navigation.
+
    **Document Research Findings:**
    - Summarize key technical insights
    - Note recommended approaches with pros/cons
@@ -164,6 +174,7 @@ The plan will be consumed by a separate execution agent that has no access to th
    - Identify existing files requiring changes
    - Document specific modifications and their impact
    - Plan integration points and interfaces
+   - Mark cross-package files as owner, adapter/orchestrator, or consumer/symptom when layer ownership triage applies
 
    **Delete Files:**
    - Identify obsolete files to be removed
@@ -486,4 +497,4 @@ If needed, add **`## Behavioral Gaps`** only after `## Freshness Summary`.
   - `ace-test path/to/test_file.rb`
 </template>
 
-</documents>
+</documents>

data/handbook/workflow-instructions/task/review.wf.md

@@ -1,19 +1,18 @@
 ---
 name: task-review
 allowed-tools: Bash, Read
-description: Review draft tasks for readiness, vertical slice quality, verification
-  plans, and promotion to pending
+description: Review draft tasks for readiness, vertical slice quality, verification plans, and promotion to pending
 doc-type: workflow
 purpose: Review draft tasks for readiness and quality before promotion
 ace-docs:
-  last-updated: '2026-03-21'
+  last-updated: '2026-04-25'
 ---
 
 # Review Task Workflow Instruction
 
 ## Goal
 
-Validate draft behavioral specifications and promote to pending when ready. This workflow acts as the readiness gate between drafting and implementation. It reviews draft tasks for completeness, conducts autonomous research to resolve open questions, generates critical questions for unresolved items, and either promotes validated drafts to `status: pending` or blocks with `needs_review: true` when questions remain.
+Validate draft behavioral specifications and promote to pending when ready. This workflow acts as the readiness gate between drafting and implementation. It reviews draft tasks for completeness, conducts autonomous research to resolve open questions, rewrites draft families when codebase reality differs from the original draft, generates critical questions for unresolved items, and either promotes validated drafts to `status: pending` or blocks with `needs_review: true` when questions remain.
 
 ## Prerequisites
 
@@ -40,6 +39,7 @@ Validate draft behavioral specifications and promote to pending when ready. This
        - Enumerate child subtasks and their current statuses before any promotion
        - Treat every child subtask still in `draft` as an additional review target
        - Review draft subtasks first and defer any parent promotion decision until child review outcomes are known
+       - Confirm the parent is acting as umbrella outcome plus decomposition map rather than hiding major work only in parent prose
      - Parse the behavioral specification sections:
        - User Experience (input, process, output)
        - Expected Behavior
@@ -51,13 +51,19 @@ Validate draft behavioral specifications and promote to pending when ready. This
        - Frontmatter `bundle` block (`presets`, `files`, `commands`)
      - Identify gaps, ambiguities, or assumptions that need clarification
 
-2. **Autonomous Research Phase:**
+2. **Autonomous Research and Draft Repair Phase:**
    - **Attempt Self-Resolution First:**
      - Search project documentation for answers
      - Analyze similar implementations in codebase
      - Review related tasks and their solutions
      - Check architectural decisions and patterns
      - Consult technical documentation and best practices
+   - **Repair draft structure when research changes the shape:**
+     - Rewrite draft subtasks when codebase reality or shipped behavior differs from the original draft
+     - Split draft subtasks when one child is hiding multiple real goals
+     - Add or change normal task dependencies when ordering matters
+     - Mark obsolete draft subtasks `skipped` when the goal is already satisfied or no longer valid
+     - Update the parent decomposition summary to match the repaired child set
    - **Web Search When Appropriate:**
      - If WebSearch tool is available and needed:
        - Search for industry standards or best practices
@@ -102,9 +108,10 @@ Validate draft behavioral specifications and promote to pending when ready. This
    - [ ] **Scope Boundaries Clear**: In-scope and out-of-scope explicitly stated
    - [ ] **Validation Questions Addressed**: All validation questions either answered or documented as blocking
    - [ ] **Vertical Slice Quality (Task/Subtask)**: Scope is decomposed into end-to-end capability slices (standalone task or orchestrator+subtasks), not horizontal layer-only work
+   - [ ] **Original Intention Coverage**: Each major original intention exists as a real child task/subtask instead of being preserved only in parent prose
    - [ ] **Subtask Slice Clarity**: Each subtask has a distinct observable outcome and does not duplicate sibling scope
    - [ ] **Child Readiness Complete** (orchestrators only): Every draft child subtask has been reviewed and either promoted to `pending` or blocked with documented questions
-   - [ ] **Tracer-First for Uncertain Architecture**: For uncertain/novel execution paths, first subtask is a tracer slice validating viability
+   - [ ] **First Slice Is Real Work**: When ordering matters, the first slice is the smallest real capability, not a synthetic research-only task
    - [ ] **Slice Size Signal Present**: Each slice includes advisory size (`small|medium|large`) for planning visibility
    - [ ] **Decision-Complete Spec**: Implementer can execute without inventing missing behavioral decisions
    - [ ] **Defaults Declared**: Ambiguous/unspecified behavior has explicit defaults
@@ -119,10 +126,7 @@ Validate draft behavioral specifications and promote to pending when ready. This
    - [ ] **Operating Modes Covered**: Spec addresses relevant operating modes (dry-run, force, verbose, quiet) or explicitly marks them out-of-scope
    - [ ] **Degenerate Inputs Covered**: Spec considers identity operations (X=Y), empty inputs, and self-referential calls where the same entity appears in both argument positions
    - [ ] **Per-Path Variations Covered**: If spec says "same behavior for X and Y", it enumerates edge cases unique to each path (guard logic, error handling, parameter differences)
-   - [ ] **End-State Coherence** (orchestrator subtasks only): Concepts introduced by this subtask
-         (new fields, modes, formats) are expected to exist in the final deliverable --
-         not be removed by a later subtask. If this subtask adds a concept that a later
-         subtask will consolidate away, flag as SCOPE RISK and consider merging subtasks.
+   - [ ] **End-State Coherence** (orchestrator subtasks only): Concepts introduced by this subtask are expected to exist in the final deliverable and not be removed by a later sibling rewrite without reasoned review-driven reshaping
    - [ ] **Title Length**: Title is max 80 characters
    - [ ] **Folder Slug**: 3-5 word context slug for folder
    - [ ] **File Slug**: 4-7 word action slug for spec file
@@ -239,27 +243,6 @@ While review-task primarily serves as the draft-to-pending gate, it can provide
 
 For non-draft tasks, skip the Readiness Checklist and Promote/Block steps. Focus on content enhancement and question generation only.
 
-### Completed Spike Review
-
-When the reviewed task is a completed spike, treat spike usefulness as a review target:
-
-- Compare the archived spike contract against the shipped public/runtime contract instead of assuming the spike remained accurate.
-- Classify every meaningful difference as exactly one of:
-  - **intentional and adopted**
-  - **intentional but deferred to follow-up**
-  - **spec miss that must be corrected**
-- Verify that the spike left a reusable adoption path:
-  - explicit next task(s) exist
-  - deferred gaps are named, not implied
-  - any promised proof artifact exists if the spike was a proof-of-concept
-- Fail closed on spike usefulness if the spike completed without an explicit follow-up task, even if later implementation succeeded through ad-hoc decisions.
-- In the review summary for completed spikes, explicitly state whether the spike produced:
-  - a reusable contract
-  - a reusable proof artifact
-  - a reusable next-task decision
-
-Treat "concept inventory exists" as insufficient by itself for a successful spike review when the spike was meant to guide real runtime or UX work.
-
 ## Decision Guidance
 
 ### When to Use This Workflow
@@ -269,6 +252,7 @@ Treat "concept inventory exists" as insufficient by itself for a successful spik
 - Refining draft specifications before implementation
 - Researching answers to open questions on draft tasks
 - Checking if a draft is implementation-ready
+- Reshaping uncertain draft families without inventing a dedicated spike subtask
 
 **Don't use review-task when:**
 - Creating new tasks (use draft-task)
@@ -287,11 +271,11 @@ Treat "concept inventory exists" as insufficient by itself for a successful spik
 - Bundle frontmatter (`presets`, `files`, `commands`) validated for completeness
 - Task promoted to pending if ready, or blocked with `needs_review: true`
 - Orchestrator parents are promoted only after draft child subtasks have also passed review
+- Review can rewrite, split, reorder, skip, or dependency-shape draft children when research proves the initial draft wrong
 - Structure and formatting preserved
 - No loss of existing information
 - Clear improvement in task clarity or completeness
 - User receives actionable list of questions to answer (if any)
-- Completed spike reviews identify contract drift and verify explicit follow-up tasks
 
 ## Task Management Integration
 
@@ -357,10 +341,11 @@ cd .ace-tasks && ace-search "needs_review: true" --content
 The review-task workflow serves as the quality gate between specification and implementation:
 
 1. **Research-First Approach**: AI agents attempt to find answers through documentation, codebase analysis, and pattern recognition before escalating
-2. **Readiness Checklist**: Systematic validation ensures behavioral specs are complete before promotion
-3. **Smart Question Filtering**: Only truly unresolvable questions requiring business/design decisions are escalated
-4. **Persistent Question Tracking**: Questions are saved in task files with `needs_review: true` metadata for easy filtering
-5. **Clear Lifecycle Decision**: Every review results in either promotion to pending or documented blocking questions
+2. **Draft Repair Authority**: Review rewrites, splits, reorders, and dependency-shapes uncertain draft families instead of requiring a special spike task type
+3. **Readiness Checklist**: Systematic validation ensures behavioral specs are complete before promotion
+4. **Smart Question Filtering**: Only truly unresolvable questions requiring business/design decisions are escalated
+5. **Persistent Question Tracking**: Questions are saved in task files with `needs_review: true` metadata for easy filtering
+6. **Clear Lifecycle Decision**: Every review results in either promotion to pending or documented blocking questions
 
 This approach enables:
 - **Clear Lifecycle Gate**: Draft tasks must pass validation before entering the implementation pipeline

data/handbook/workflow-instructions/task/work.wf.md

@@ -1,7 +1,7 @@
 ---
 name: task-work
-description: Execute task implementation against behavioral spec using pre-loaded
-  plan
+description: Execute task implementation against behavioral spec using pre-loaded plan
+allowed-tools: Bash, Read, Write
 assign:
   sub-steps:
   - onboard-base
@@ -16,7 +16,7 @@ assign:
 doc-type: workflow
 purpose: Execute task implementation from plan with quality gates
 ace-docs:
-  last-updated: '2026-03-21'
+  last-updated: '2026-04-25'
 ---
 
 # Work on Task
@@ -41,7 +41,7 @@ To avoid known `--content` stalls in some environments:
    - `ace-task plan <ref>` (path mode, reuse cached plan when available)
    - The most recent plan artifact plus current task spec, documented in the step report
 4. If stalls repeat, add a follow-up fix task and capture evidence in the retrospective.
-5. If implementation reveals the spec or spike contract is materially wrong, stale, or missing an adoption path, stop and either update the spec or add a follow-up task before continuing.
+5. If implementation reveals the spec is materially wrong, stale, or missing an adoption path, stop and either update the spec or add a follow-up task before continuing.
 
 ## Primary Directive
 
@@ -59,12 +59,13 @@ Work through the plan checklist, step by step:
 - If the spec says X, implement X — don't gold-plate, don't simplify away requirements
 - If spec and plan conflict, spec wins — the plan is a HOW, not a WHAT
 - If the spec is ambiguous or incomplete: stop and ask, don't assume
-- If runtime work materially changes a public contract promised by a spike (flags, naming, fallback behavior, proof surface, ownership boundary), do not silently drift. Update the task/spec or create a follow-up task before release or demo cleanup.
+- If runtime work materially changes a promised public contract (flags, naming, fallback behavior, proof surface, ownership boundary), do not silently drift. Update the task/spec or create a follow-up task before release or demo cleanup.
+- If implementation reveals the plan targets only a symptom/consumer package for a shared primitive, stop and re-plan at the owner layer before editing. The owner layer is the package that creates, names, persists, routes, or navigates the primitive; adapters and consumers should reuse owner APIs instead of duplicating policy.
 
 **Prior implementation awareness:**
-- Before creating new modules, search for existing implementations of the same concern — especially spike or prototype code from prior subtasks
-- If a sibling task (same parent, earlier sequence) produced spike code: refactor and promote it rather than creating parallel "production" versions
-- Check dependency task reports and the task folder for prior work artifacts (concept inventories, spike reports)
+- Before creating new modules, search for existing implementations of the same concern
+- If a sibling task produced prototype or exploratory code, refactor and promote it rather than creating parallel "production" versions
+- Check dependency task reports and the task folder for prior work artifacts
 - When plan file paths point to locations where code already exists, integrate rather than duplicate
 
 **Execution discipline:**
@@ -74,20 +75,20 @@ Work through the plan checklist, step by step:
 - If a test failure is undiagnosable after one attempt: stop and report
 
 **Task lifecycle:**
-- `draft` status: warn the user that the spec hasn't been reviewed, then continue only with explicit confirmation. In unattended/fork contexts where interactive confirmation is not possible, proceed after marking in-progress — the assignment creation layer is responsible for blocking draft tasks before they reach this point.
+- `draft` status: warn the user that the spec hasn't been reviewed, then continue only with explicit confirmation. In unattended/fork contexts where interactive confirmation is not possible, proceed after marking in-progress -- the assignment creation layer is responsible for blocking draft tasks before they reach this point.
 - Mark in-progress before first change, done after last verification
-- Never modify task frontmatter directly — use `ace-task update <ref> --set key=value`
-- If the task implements a spike outcome, verify before marking done that deferred gaps and adoption follow-ups are explicit rather than left implicit in release notes or retrospectives.
+- Never modify task frontmatter directly -- use `ace-task update <ref> --set key=value`
+- If implementation reveals the reviewed draft structure is materially wrong, update the affected task specs or add follow-up tasks before continuing with misleading assumptions.
 
 ## Code Conventions
 
-- Follow established project patterns — don't introduce new abstractions or styles
+- Follow established project patterns -- don't introduce new abstractions or styles
 - 2-space indentation (Ruby); keep lines under 120 characters
 - Write tests for all new logic; run `ace-test` before committing
 
 ## Task Folder
 
-**Documents:** Task-specific docs (reports, findings, usage docs) go in the task folder — never in the project root.
+**Documents:** Task-specific docs (reports, findings, usage docs) go in the task folder -- never in the project root.
 
 **Codemods** (scripts that transform files): create in `{task-folder}/codemods/`, never in `bin/`
 
@@ -97,7 +98,7 @@ Work through the plan checklist, step by step:
 
 All plan steps checked, all success criteria pass:
 
-1. **Verify working tree is clean** — no uncommitted changes:
+1. **Verify working tree is clean** -- no uncommitted changes:
    ```bash
    git status --short
    ```

data/lib/ace/task/cli/commands/create.rb

@@ -18,6 +18,7 @@ module Ace
 
           example [
             '"Fix login bug"                              # Create task with title',
+            '--title "Fix login bug"                      # Create task with title flag',
             '"Fix auth" --priority high --tags auth,security  # With priority and tags',
             '"Setup DB" --child-of q7w                    # Create as subtask',
             '"Track issue" --github-issue 276             # Link GitHub issue',
@@ -26,8 +27,9 @@ module Ace
             '"Preview only" --dry-run                     # Show what would be created'
           ]
 
-          argument :title, required: true, desc: "Task title"
+          argument :title_arg, required: false, desc: "Task title"
 
+          option :title, type: :string, desc: "Task title (alternative to positional TITLE)"
           option :priority, type: :string, aliases: %w[-p], desc: "Priority (critical, high, medium, low)"
           option :tags, type: :string, aliases: %w[-T], desc: "Tags (comma-separated)"
           option :status, type: :string, aliases: %w[-s], desc: "Initial status (draft, pending, blocked, ...)"
@@ -43,7 +45,8 @@ module Ace
           option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
           option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
 
-          def call(title:, **options)
+          def call(title_arg: nil, **options)
+            title = resolve_title(title_arg, options[:title])
             dry_run = options[:"dry-run"]
             priority = options[:priority]
             tags_str = options[:tags]
@@ -127,6 +130,24 @@ module Ace
 
           private
 
+          def resolve_title(positional_title, flag_title)
+            positional_present = present_string?(positional_title)
+            flag_present = present_string?(flag_title)
+
+            if positional_present && flag_present
+              raise Ace::Support::Cli::Error.new("Choose either positional TITLE or --title, not both")
+            end
+
+            return positional_title if positional_present
+            return flag_title if flag_present
+
+            raise Ace::Support::Cli::Error.new("Title required: provide positional TITLE or --title")
+          end
+
+          def present_string?(value)
+            !value.nil? && !value.to_s.strip.empty?
+          end
+
           def parse_github_issue(raw_values)
             values = Array(raw_values).flatten.compact
             return nil if values.empty?

data/lib/ace/task/organisms/task_manager.rb

@@ -336,10 +336,10 @@ module Ace
             parent_dir, recursive: true
           )
 
-          # Auto-move the parent folder to archive
-          parent_stub = Struct.new(:path).new(parent_dir)
-          mover = Ace::Support::Items::Molecules::FolderMover.new(@root_dir)
-          mover.move(parent_stub, to: "archive")
+          parent = load_parent_from_directory(parent_dir, loader)
+          return unless parent
+
+          archive_parent_via_update(parent)
         end
 
         def parse_archive_date(task)
@@ -387,27 +387,46 @@ module Ace
             }
           end
 
-          unless Atoms::TaskValidationRules.terminal_status?(parent.status.to_s.downcase)
-            Ace::Support::Items::Molecules::FieldUpdater.update(
-              parent.file_path, set: {"status" => "done"}
-            )
-            parent = loader.load(parent.path, id: parent.id, special_folder: parent.special_folder)
-          end
-
-          mover = Ace::Support::Items::Molecules::FolderMover.new(@root_dir)
-          new_parent_path = mover.move(parent, to: "archive", date: parse_archive_date(parent))
-          new_special_folder = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(
-            new_parent_path, root: @root_dir
-          )
+          archived_parent = archive_parent_via_update(parent)
+          return {
+            path: task.path,
+            special_folder: task.special_folder,
+            id: task.id
+          } unless archived_parent
 
           @last_update_note = "Archived parent task #{parent.id} because all subtasks are terminal."
           {
-            path: File.join(new_parent_path, File.basename(task.path)),
-            special_folder: new_special_folder,
+            path: File.join(archived_parent.path, File.basename(task.path)),
+            special_folder: archived_parent.special_folder,
             id: task.id
           }
         end
 
+        def archive_parent_via_update(parent)
+          previous_note = @last_update_note
+          archived_parent = update(
+            parent.id,
+            set: {"status" => "done"},
+            move_to: "archive"
+          )
+
+          if archived_parent && @last_update_note == previous_note
+            @last_update_note = "Archived parent task #{parent.id} because all subtasks are terminal."
+          end
+
+          archived_parent
+        end
+
+        def load_parent_from_directory(parent_dir, loader)
+          parent_id = File.basename(parent_dir).split("-", 2).first
+          return nil unless parent_id
+
+          parent_special = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(
+            parent_dir, root: @root_dir
+          )
+          loader.load(parent_dir, id: parent_id, special_folder: parent_special)
+        end
+
         # Value accessor for FilterApplier
         def task_value_accessor(item, key)
           case key

data/lib/ace/task/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Task
-    VERSION = '0.36.1'
+    VERSION = '0.37.0'
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-task
 version: !ruby/object:Gem::Version
-  version: 0.36.1
+  version: 0.37.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-04-20 00:00:00.000000000 Z
+date: 2026-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-core