ace-task 0.31.9 → 0.36.7

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,20 +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.
+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:
@@ -232,16 +243,20 @@ This prevents decomposing into subtasks that add concepts the spike later proves
    * **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)
+     * [ ] 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:
@@ -335,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
@@ -358,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.
@@ -549,4 +577,4 @@ the decomposition was premature. Consider consolidating remaining subtasks.
 ## Notes for Implementer
 - Full usage documentation to be completed during work-on-task step using `wfi://docs/update-usage`
 </template>
-</documents>
+</documents>

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
@@ -248,6 +252,7 @@ For non-draft tasks, skip the Readiness Checklist and Promote/Block steps. Focus
 - 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)
@@ -266,6 +271,7 @@ For non-draft tasks, skip the Readiness Checklist and Promote/Block steps. Focus
 - 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
@@ -335,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,6 +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 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
 
@@ -58,11 +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 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:**
@@ -72,19 +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`
+- 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/`
 
@@ -94,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/atoms/task_frontmatter_defaults.rb

@@ -18,7 +18,17 @@ module Ace
         # @param created_at [Time, nil] Creation time
         # @param parent [String, nil] Parent task ID for subtasks
         # @return [Hash] Frontmatter hash
-        def self.build(id:, status: "pending", priority: nil, tags: [], dependencies: [], created_at: nil, parent: nil, estimate: nil)
+        def self.build(
+          id:,
+          status: "pending",
+          priority: nil,
+          tags: [],
+          dependencies: [],
+          created_at: nil,
+          parent: nil,
+          estimate: nil,
+          github_issue: nil
+        )
           fm = {
             "id" => id,
             "status" => status || "pending",
@@ -29,6 +39,7 @@ module Ace
           fm["dependencies"] = dependencies || []
           fm["tags"] = tags || []
           fm["parent"] = parent if parent
+          fm["github_issue"] = github_issue if github_issue
           fm
         end
 

data/lib/ace/task/atoms/task_validation_rules.rb

@@ -19,7 +19,7 @@ module Ace
         end
 
         def self.valid_id?(id)
-          id.to_s.match?(/^[0-9a-z]{3}\.[a-z]\.[0-9a-z]{3}$/)
+          id.to_s.match?(/\A[0-9a-z]{3}\.[a-z]\.[0-9a-z]{3}(?:\.[0-9a-z])?\z/)
         end
 
         def self.scope_consistent?(status, special_folder)

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

@@ -20,6 +20,7 @@ module Ace
             '"Fix login bug"                              # Create task with title',
             '"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',
             '"Quick task" --in maybe                      # Create in _maybe/ folder',
             '"Draft spec" --status draft --estimate TBD   # Create as draft with estimate',
             '"Preview only" --dry-run                     # Show what would be created'
@@ -31,6 +32,7 @@ module Ace
           option :tags, type: :string, aliases: %w[-T], desc: "Tags (comma-separated)"
           option :status, type: :string, aliases: %w[-s], desc: "Initial status (draft, pending, blocked, ...)"
           option :estimate, type: :string, aliases: %w[-e], desc: "Effort estimate (e.g. TBD, 2h, 1d)"
+          option :"github-issue", type: :array, desc: "Linked GitHub issue number"
           option :"child-of", type: :string, desc: "Parent task reference (creates subtask)"
           option :in, type: :string, aliases: %w[-i], desc: "Target folder (e.g. next, maybe)"
           option :"dry-run", type: :boolean, aliases: %w[-n], desc: "Preview without writing"
@@ -48,6 +50,7 @@ module Ace
             tags = tags_str ? tags_str.split(",").map(&:strip).reject(&:empty?) : []
             status = options[:status]
             estimate = options[:estimate]
+            github_issue = parse_github_issue(options[:"github-issue"])
             child_of = options[:"child-of"]
             in_folder = options[:in]
 
@@ -64,6 +67,7 @@ module Ace
               puts "  Status:   #{status}" if status
               puts "  Priority: #{priority}" if priority
               puts "  Estimate: #{estimate}" if estimate
+              puts "  GitHub:   #{github_issue}" if github_issue
               puts "  Tags:     #{tags.join(", ")}" if tags.any?
               puts "  Parent:   #{child_of}" if child_of
               puts "  Folder:   #{in_folder}" if in_folder
@@ -72,10 +76,29 @@ module Ace
 
             manager = Ace::Task::Organisms::TaskManager.new
 
-            task = if child_of
-              manager.create_subtask(child_of, title, status: status, priority: priority, tags: tags, estimate: estimate)
-            else
-              manager.create(title, status: status, priority: priority, tags: tags, estimate: estimate)
+            task = begin
+              if child_of
+                manager.create_subtask(
+                  child_of,
+                  title,
+                  status: status,
+                  priority: priority,
+                  tags: tags,
+                  estimate: estimate,
+                  github_issue: github_issue
+                )
+              else
+                manager.create(
+                  title,
+                  status: status,
+                  priority: priority,
+                  tags: tags,
+                  estimate: estimate,
+                  github_issue: github_issue
+                )
+              end
+            rescue Ace::Task::Organisms::TaskManager::CreateRetriesExhaustedError => e
+              raise Ace::Support::Cli::Error, e.message
             end
 
             unless task
@@ -90,6 +113,9 @@ module Ace
 
             puts "Created task #{task.id}"
             puts "  Path: #{task.file_path}"
+            if manager.last_update_note && !manager.last_update_note.strip.empty?
+              puts "Info: #{manager.last_update_note}"
+            end
 
             if options[:git_commit]
               Ace::Support::Items::Molecules::GitCommitter.commit(
@@ -98,6 +124,22 @@ module Ace
               )
             end
           end
+
+          private
+
+          def parse_github_issue(raw_values)
+            values = Array(raw_values).flatten.compact
+            return nil if values.empty?
+            raise Ace::Support::Cli::Error.new("Only one --github-issue may be provided") if values.length > 1
+
+            candidate = values.first.to_s.strip
+            raise Ace::Support::Cli::Error.new("Invalid GitHub issue '#{values.first}': expected numeric ID") unless candidate.match?(/\A\d+\z/)
+
+            id = candidate.to_i
+            raise Ace::Support::Cli::Error.new("Invalid GitHub issue '#{values.first}': expected positive numeric ID") if id <= 0
+
+            id
+          end
         end
       end
     end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Task
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-task github-sync
+        class GithubSync < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Synchronize linked GitHub issues for a task or all linked tasks
+          DESC
+
+          example [
+            "q7w                         # Sync one task",
+            "--all                       # Sync all linked tasks"
+          ]
+
+          argument :ref, required: false, desc: "Task reference (full ID, short ref, or suffix)"
+          option :all, type: :boolean, aliases: %w[-a], desc: "Sync all linked tasks"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(ref: nil, **options)
+            all = options[:all]
+
+            if !all && (ref.nil? || ref.strip.empty?)
+              raise Ace::Support::Cli::Error.new("Provide a task reference or use --all")
+            end
+
+            manager = Ace::Task::Organisms::TaskManager.new
+            result = manager.github_sync(ref: ref, all: all)
+            raise Ace::Support::Cli::Error.new("Task '#{ref}' not found") if result.nil?
+            print_failures(result[:failures])
+
+            if result[:failed].to_i.positive?
+              raise Ace::Support::Cli::Error.new(
+                "GitHub sync incomplete: synced #{result[:synced]}, failed #{result[:failed]}, skipped #{result[:skipped]}"
+              )
+            elsif all
+              puts "GitHub sync complete: synced #{result[:synced]} linked task(s), skipped #{result[:skipped]} task(s)"
+            elsif result[:synced].positive?
+              puts "GitHub sync complete: #{result[:task_id]}"
+            else
+              puts "No linked GitHub issues for task #{result[:task_id]}"
+            end
+          end
+
+          private
+
+          def print_failures(failures)
+            Array(failures).each do |failure|
+              warn "GitHub sync failed for #{failure[:task_id]}: #{failure[:error]}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -24,6 +24,7 @@ module Ace
             "q7w                          # Reuse fresh plan or generate new",
             "q7w --refresh                # Force regeneration",
             "q7w --content                # Print full plan content",
+            "q7w --timeout 30             # Fail fast if plan generation stalls",
             "q7w --model gemini:flash-latest  # Override planning model"
           ]
 
@@ -32,6 +33,7 @@ module Ace
           option :refresh, type: :boolean, desc: "Force plan regeneration"
           option :content, type: :boolean, desc: "Print full plan content instead of path"
           option :model, type: :string, desc: "Provider:model override for plan generation"
+          option :timeout, type: :integer, desc: "LLM request timeout in seconds for plan generation"
 
           option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
           option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
@@ -58,7 +60,7 @@ module Ace
 
             context_files = capture_context_files(task)
             model = options[:model] || default_model(config)
-            generator = plan_generator(model)
+            generator = plan_generator(model, timeout: options[:timeout])
             content = generator.generate(
               task: task,
               context_files: context_files,
@@ -104,13 +106,15 @@ module Ace
             end
           end
 
-          def plan_generator(model, cli_args: nil)
+          def plan_generator(model, cli_args: nil, timeout: nil)
             klass = self.class.generator_class || Molecules::TaskPlanGenerator
-            klass.new(model: model, cli_args: cli_args)
+            kwargs = {model: model, cli_args: cli_args}
+            kwargs[:timeout] = timeout if timeout
+            klass.new(**kwargs)
           end
 
           def default_model(config)
-            config.dig("task", "plan", "model") || "gemini:flash-latest"
+            config.dig("task", "plan", "model") || "role:planner"
           end
         end
       end