Apm Git Taskflow

Required setup workflow

1. Identify TASK_ID:
   • from active memory_bank/specs/SPEC_{TASK_ID}.md, or
   • from an explicit identifier provided by the user or orchestrator.
2. Detect base branch (usually current integration branch, e.g., main).
3. Ensure .apm/worktrees/ exists.
4. Create or reuse task branch:
   • if branch exists, reuse;
   • if not, create from base branch.
5. Create or reuse task worktree under .apm/worktrees/{TASK_ID}.
6. If memory_bank/tasks/{TASK_ID}.md exists and the user wants git traceability in task notes, record compact git context there:
   • Base branch
   • Task branch
   • Worktree path

Worktree resource management

Git worktrees check out only tracked files. Heavy untracked resources (virtual environments, datasets, model artifacts, caches) are absent in a new worktree by default.

Resource classification

Shared runtime protocol (default)

Default policy: keep a single repo-level runtime and reuse it across all worktrees. Do not create a separate .venv (or separate node_modules) per worktree.

If your environment/tooling expects paths to exist inside the worktree, you may create convenience symlinks after step 5 (worktree creation):

MAIN_TREE="$(git -C .apm/worktrees/{TASK_ID} rev-parse --path-format=absolute --git-common-dir | xargs -I{} dirname {})"
WT_DIR=".apm/worktrees/{TASK_ID}"

[ -d "$MAIN_TREE/.venv" ] && ln -sfn "$MAIN_TREE/.venv" "$WT_DIR/.venv"
[ -d "$MAIN_TREE/node_modules" ] && ln -sfn "$MAIN_TREE/node_modules" "$WT_DIR/node_modules"
[ -d "$MAIN_TREE/data" ] && ln -sfn "$MAIN_TREE/data" "$WT_DIR/data"

Adapt paths to the project layout documented in memory_bank/ARCHITECTURE.md. If the project uses DVC, dvc checkout inside the worktree resolves data references from the shared DVC cache automatically.

Dependency change handling (safe updates)

When a task changes dependencies (pyproject.toml, requirements*.txt, package.json, lockfiles), update the shared runtime using a managed toolchain:

• Prefer a lockfile-driven approach (e.g., uv.lock, pnpm-lock.yaml, etc.).
• Apply changes via safe sync tools (e.g., uv sync, package-manager install) to update the shared .venv / node_modules.
• Serialize updates: do not run concurrent dependency updates across parallel tasks.
• After sync, run a short verification relevant to the task scope.

Artifact integration after merge

After merging a task branch into the base branch, untracked task-local artifacts (new models, reports, generated data) remain only in the worktree directory. Before git worktree remove:

1. Copy new untracked artifacts from the worktree to the corresponding locations in the main tree.
2. Verify artifact integrity (checksums, config snapshots).
3. Remove the worktree.

Configuration

Projects may override the default symlink list via memory_bank/ARCHITECTURE.md (section "Shared resources" or equivalent). If present, follow the project-specific list instead of the defaults above.

Wave Integration Gate

Run after all task branches in a wave are merged and artifacts are migrated. This gate validates the integrated codebase before proceeding to the next wave or final handoff.

Gate steps

1. Build/compile check: run the project's build or import validation (language-appropriate). For Python: verify all imports resolve (python -c "import <main_module>").
2. Type check: if contract/Protocol files exist, run the project's type checker (e.g., mypy, pyright). Focus on contract-defined interfaces.
3. Test suite: run tests in layer order — unit tests first, then contract tests, then cross-task integration tests. If pipeline/E2E tests exist, run those last. If no tests exist yet (e.g., Wave 1 greenfield), note it and skip gracefully.
4. Dependency audit: verify the lockfile is consistent and no per-worktree runtime was created (no .venv or node_modules inside .apm/worktrees/).
5. Environment hygiene: confirm all worktrees are cleaned up. No orphan branches remain.

Gate outcome

• Pass: all checks succeed (or are gracefully skipped with justification). Proceed to next wave or final handoff.
• Fail: fix the failure, re-run the failing check. Do not proceed until the gate passes.

PR contract

Create PR when:

• the task is complete, or
• the user explicitly requests PR creation.

PR body must include:

1. Task context (TASK_ID and objective)
2. What changed
3. Verification evidence
4. Risks / deferred items
5. Conflict notes (if conflicts were resolved)

If PR cannot be opened automatically (missing remote/permissions/tooling):

• prepare a PR package (title + full body + verification summary + diff summary),
• return it to the user and wait for further instruction.

Conflict policy

• Resolve mechanical conflicts (non-semantic merge conflicts) directly.
• After mechanical conflict resolution, rerun relevant verification.
• Escalate semantic conflicts (requirements, behavior intent, architecture meaning) to the user before final merge.

Guardrails

• Do not run write-heavy parallel streams in the same branch/worktree.
• Do not mix multiple TASK_IDs in one task branch.
• Do not auto-merge semantic conflicts.
• Do not proceed to next wave if integration gate fails.