{"id":30876181,"url":"https://github.com/kubohiroya/mrtask","last_synced_at":"2026-05-02T17:32:55.791Z","repository":{"id":313657584,"uuid":"1052185375","full_name":"kubohiroya/mrtask","owner":"kubohiroya","description":"command-line tool that helps developers manage task-specific worktrees in mono-repositories","archived":false,"fork":false,"pushed_at":"2025-09-07T16:26:59.000Z","size":50,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-07T17:34:05.323Z","etag":null,"topics":["git","monorepo","node","npm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubohiroya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-07T15:27:03.000Z","updated_at":"2025-09-07T16:27:03.000Z","dependencies_parsed_at":"2025-09-07T17:45:17.883Z","dependency_job_id":null,"html_url":"https://github.com/kubohiroya/mrtask","commit_stats":null,"previous_names":["kubohiroya/mrtask"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kubohiroya/mrtask","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubohiroya%2Fmrtask","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubohiroya%2Fmrtask/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubohiroya%2Fmrtask/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubohiroya%2Fmrtask/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubohiroya","download_url":"https://codeload.github.com/kubohiroya/mrtask/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubohiroya%2Fmrtask/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274121957,"owners_count":25225801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","monorepo","node","npm"],"created_at":"2025-09-08T02:07:26.835Z","updated_at":"2026-05-02T17:32:55.779Z","avatar_url":"https://github.com/kubohiroya.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mrtask — Parallel Development for Monorepos with git worktree\n\n[![npm version](https://img.shields.io/npm/v/mrtask?style=flat-square)](https://www.npmjs.com/package/mrtask)\n[![license](https://img.shields.io/npm/l/mrtask?style=flat-square)]\n\n`mrtask` is a small CLI that lets teams develop multiple features in parallel in a mono-repo using git worktree. It creates isolated, task‑scoped worktrees, tracks each task with a simple YAML file, and adds lightweight guardrails to keep changes focused and conflict‑free.\n\nIt now integrates with [dep‑fence](https://github.com/kubohiroya/dep-fence) (v0.3.x) to provide predictable “before commit/push” checks that are easy to understand and configure.\n\n\n\n## Why mrtask?\n\nMono-repos make cross‑package changes easy, but they also invite accidental scope creep and tricky merges. Common needs:\n\n- Work on multiple tasks in parallel without stepping on each other.\n- Keep each task’s changes constrained to intended directories.\n- Avoid push surprises when upstream moved.\n- Keep a lightweight, machine‑readable record of what a branch is for.\n\n`mrtask` layers a simple lifecycle and guardrails on top of `git worktree` so teams can move fast with confidence.\n\n---\n\n## Workflow Overview\n\n“CMD nodes = mrtask commands; others = repo/GitHub states”\n\n```mermaid\nstateDiagram-v2\n    classDef cmd fill:#FFF3B0,stroke:#F2A50C,stroke-width:2px,color:#111\n\n    [*] --\u003e CMD_CREATE\n    CMD_CREATE: mrtask create\n    class CMD_CREATE cmd\n\n    CMD_CREATE --\u003e OPEN\n    state OPEN {\n        [*] --\u003e CODE_CHANGES\n        CODE_CHANGES: commits / changes\n    }\n\n    OPEN --\u003e CMD_PR\n    CMD_PR: mrtask pr\n    class CMD_PR cmd\n\n    OPEN --\u003e CMD_CANCEL\n    OPEN --\u003e CMD_REMOVE\n\n    NOT_ACCEPTED --\u003e OPEN\n    REVIEW --\u003e CMD_CANCEL\n    REVIEW --\u003e CMD_REMOVE\n\n    CMD_PR --\u003e REVIEW\n    REVIEW --\u003e MERGE_ACCEPTED\n    REVIEW --\u003e NOT_ACCEPTED\n\n    MERGE_ACCEPTED --\u003e CMD_DONE\n    CMD_DONE: mrtask done\n    class CMD_DONE cmd\n\n    CMD_CANCEL: mrtask cancel\n    class CMD_CANCEL cmd\n    CMD_REMOVE: mrtask remove\n    class CMD_REMOVE cmd\n\n    CMD_DONE --\u003e [*]: complete\n    CMD_CANCEL --\u003e [*]: canceled\n    CMD_REMOVE --\u003e [*]: removed\n```\n\n## Core Ideas\n\n- Task = a small, focused unit of work tracked by a `.mrtask/\u003cid\u003e.yml` file.\n- Logical branch is stable (the task identity); physical branches are auto‑unique per worktree.\n- Isolated worktrees let you context‑switch without cross‑polluting `node_modules` or build artifacts.\n- Guardrails run at pre-commit and pre-push to keep changes on the rails.\n\n---\n\n## Features\n\n- Creates and manages task‑scoped git worktrees.\n- Stores task metadata (title, dirs, branch, tags) in YAML.\n- Generates PR drafts from the task + current diff.\n- Integrates dep‑fence guards for safe, predictable checks:\n  - allowed‑dirs (pre-commit/pre-push)\n  - mtime‑compare (warn by default)\n  - upstream‑conflict (pre-push/CI)\n - Safe close-out: `mrtask done` verifies that the branch is merged before cleaning up (never merges by itself).\n - Explicit acceptance: `mrtask accept` can merge a PR via GitHub CLI (or optional local fast‑forward).\n\n---\n\n## Requirements\n\n- Git ≥ 2.20 (git worktree)\n- Node.js ≥ 18\n- A workspace tool like pnpm/yarn/npm is recommended\n\n---\n\n## Installation\n\n```bash\nnpm install -g mrtask\n# or\npnpm add -g mrtask\n# or\nyarn global add mrtask\n\nmrtask --help\n```\n\n---\n\n## Quick Start\n\nAt a glance\n\n- Default safety: most commands are dry‑run friendly; use `--no-dry-run` for side effects.\n- IDE‑friendly: worktrees are created next to your repo (sibling) by default.\n- Clear scope: directory guards keep changes inside intended packages.\n- Easy targeting: you can address a task by YAML path, id/prefix, or the 8‑char short hash shown in `mrtask list`. Omitting an id targets “the task of the current worktree/branch”.\n\n1) Create an isolated task worktree\n\n```bash\nmrtask create feature/login-ui login-ui -d \"Implement login form\" packages/app\n```\n\n2) Install Git hooks (recommended)\n\n```bash\npnpm run hooks:install  # adds pre-commit / pre-push that run the guards\n```\n\n3) Open a PR when ready\n\n```bash\n# Preview (no git side effects)\nmrtask pr \u003cid\u003e --dry-run\n\n# Then actually push upstream and open/compare as needed\nmrtask pr \u003cid\u003e --push --no-dry-run\n```\n\n4) Wrap up\n\n```bash\nmrtask done \u003cid\u003e   # archives YAML to done/, removes worktree, deletes branch\n```\n\n---\n\n## Daily Flow (Happy Paths)\n\nSingle‑task flow (create → pr → done)\n\n```bash\n# create a task for packages/app and start coding in the new worktree\nmrtask create feature/login-ui login-ui -d \"Implement login form\" packages/app\n\n# commit changes inside the worktree; guards warn/block if you touch outside allowed dirs\ngit add -A \u0026\u0026 git commit -m \"feat(app): implement login\"\n\n# create PR (from inside the worktree; no id needed)\nmrtask pr --push --draft --open --no-dry-run\n\n# after merge, clean up (inside any directory)\nmrtask done --taskid \u003cshort8\u003e\n```\n\nCancel (close without merge)\n\n```bash\nmrtask cancel --taskid \u003cshort8\u003e\n```\n\nRemove (delete record/worktree/branch)\n\n```bash\nmrtask remove --taskid \u003cshort8\u003e\n```\n\n---\n\n## Concepts \u0026 Defaults\n\n- Worktree placement\n  - Default is sibling: `\u003ccurrent\u003e/../\u003cbranch_name\u003e` (worktree lives beside your main checkout and uses the branch path).\n  - Directory collisions abort the command before invoking `git worktree add`.\n  - Switch with `--wt-mode home|repo-subdir` at `add` time.\n  - All historical locations are auto‑detected for cleanup (`.mrtask/wt/\u003cid\u003e`, `$MRTASK_HOME/...`, `\u003crepo\u003e/.worktrees/\u003cid\u003e`, `\u003crepo-parent\u003e/\u003cbranch_path\u003e`, `\u003crepo-parent\u003e/\u003ctask-id\u003e`, legacy `\u003crepo-parent\u003e/\u003crepo-name\u003e-wt/\u003cid\u003e`).\n\n- Target resolution (which task?):\n  - Omitting an id on `pr/done/cancel/remove` resolves to the task of the current worktree/branch.\n  - You can also specify `--task \u003cyaml\u003e`, `--taskid \u003cid|short8\u003e`, `--branch \u003cname\u003e`, or `--worktree \u003cpath\u003e`.\n\n- ID formats\n  - YAML path, full id, id prefix, 8‑char short hash (as shown by `mrtask list`).\n\n- Guards (directory change policy)\n  - YAML: `guards: { level: ignore|warn|error }`; legacy `--strict/--no-strict` map to `error/warn` and are deprecated.\n  - For isolated tasks (create) you can explicitly set guards via `--guards` when creating.\n  - For shared tasks (add) the branch’s guard config is auto‑recomputed as the union of open tasks on that branch. Use `--guards ignore|warn|error` to set the per‑task preference written into YAML.\n\n- Dry‑run by default\n  - `mrtask pr` (and `ci`) are safe to run without side effects until `--no-dry-run` is passed. `--dry-run` is the default for these commands.\n\n---\n\n## Worktree Layout (Before/After)\n\nBelow shows how the filesystem changes with the default sibling placement. Replace `\u003crepo\u003e` with your repository name, `\u003ctask-id\u003e` with the generated task id, and `\u003cbranch_path\u003e` with the branch path (for example `feature/login-ui`).\n\nExample context\n\n```text\n/projects/\n  \u003crepo\u003e/            # your main working copy (on main)\n  (no task worktrees yet)\n```\n\n### create — creates a sibling worktree (isolated)\n\nCommand\n\n```bash\ncd /projects/\u003crepo\u003e\nmrtask create feature/login-ui login-ui packages/app\n```\n\nBefore\n\n```text\n/projects/\n  \u003crepo\u003e/\n    .git/\n    packages/\n      app/\n        (no .mrtask yet)\n```\n\nAfter\n\n```text\n/projects/\n  \u003crepo\u003e/\n    .git/\n    packages/\n      app/\n        .mrtask/\n          \u003ctask-id\u003e.yml           # task metadata is versioned in main\n\n  feature/\n    login-ui/                     # new worktree checked out on feature/login-ui\n      (package layout mirrors repo; edit here for this task)\n```\n\nNotes\n- The task YAML is placed under the primary package (`packages/app/.mrtask/\u003ctask-id\u003e.yml`) for discoverability on main.\n- The worktree is a separate checkout at `/projects/\u003cbranch_path\u003e` (e.g. `/projects/feature/login-ui`). Legacy directories under `/projects/\u003crepo\u003e-wt/\u003ctask-id\u003e` or `/projects/\u003crepo-parent\u003e/\u003ctask-id\u003e` are still detected for cleanup.\n\n### add — add a shared (lightweight) task under an existing worktree\n\nUse when you want to track sub‑tasks without creating more worktrees. The YAML is created under the target package, guards are auto‑recomputed for the branch, and no new worktree is created.\n\n```bash\n# choose a parent explicitly by YAML / id / short8\nmrtask add child-qa packages/app --parent ./.mrtask/\u003cparent-id\u003e.yml\n\n# or let mrtask auto‑select a parent on the same branch based on dir match\nmrtask add child-qa packages/app\n```\n\n Output shows:\n - `✔ Added shared task \u003cid\u003e`\n - `YAML: packages/app/.mrtask/\u003cchild-id\u003e.yml`\n - `Worktree: \u003cresolved-parent-worktree\u003e on branch \u003cbranch\u003e`\n\n### add (shared) — no new worktree (before/after)\n\nCommand\n\n```bash\ncd /projects/\u003crepo\u003e\n# assume you already have a parent task/worktree on feature/login-ui\nmrtask add child-qa packages/app --parent ./.mrtask/\u003cparent-id\u003e.yml\n```\n\nBefore\n\n```text\n/projects/\n  \u003crepo\u003e/\n    packages/app/\n      (no child YAML yet)\n  feature/\n    login-ui/                   # existing worktree on feature/login-ui\n```\n\nAfter\n\n```text\n/projects/\n  \u003crepo\u003e/\n    packages/app/\n      .mrtask/\n        \u003cchild-id\u003e.yml           # new shared subtask YAML on main\n  feature/\n    login-ui/                    # unchanged (no new worktree is created)\n      .mrtask/dep-fence.config.ts  # guards updated to union of open tasks\n```\n\nNotes\n- Shared tasks do not create additional worktrees; they live under their parent’s branch/worktree.\n- Use `mrtask list` on main to see parents with their subtasks (hierarchical by default). Use `--flat` for a flat view.\n\n### done — removes worktree, archives YAML to done/\n\nCommand\n\n```bash\nmrtask done --taskid \u003cshort8\u003e\n```\n\nBefore\n\n```text\n/projects/\n  \u003crepo\u003e/\n    packages/app/.mrtask/\n      \u003ctask-id\u003e.yml\n  \u003cbranch_path\u003e/\n```\n\nAfter\n\n```text\n/projects/\n  \u003crepo\u003e/\n    packages/app/.mrtask/\n      done/\n        \u003ctask-id\u003e.yml             # archived record\n  \u003cbranch_path\u003e/ (worktree removed)\n```\n\n### cancel — removes worktree, archives YAML to cancel/\n\nCommand\n\n```bash\nmrtask cancel --taskid \u003cshort8\u003e\n```\n\nBefore\n\n```text\n/projects/\n  \u003crepo\u003e/\n    packages/app/.mrtask/\n      \u003ctask-id\u003e.yml\n  \u003cbranch_path\u003e/\n```\n\nAfter\n\n```text\n/projects/\n  \u003crepo\u003e/\n    packages/app/.mrtask/\n      cancel/\n        \u003ctask-id\u003e.yml             # archived as canceled\n  \u003cbranch_path\u003e/ (worktree removed)\n```\n\n### remove — removes worktree and deletes YAML\n\nCommand\n\n```bash\nmrtask remove --taskid \u003cshort8\u003e\n```\n\nBefore\n\n```text\n/projects/\n  \u003crepo\u003e/\n    packages/app/.mrtask/\n      \u003ctask-id\u003e.yml\n  \u003cbranch_path\u003e/\n```\n\nAfter\n\n```text\n/projects/\n  \u003crepo\u003e/\n    packages/app/.mrtask/\n      (no \u003ctask-id\u003e.yml)          # record removed\n  \u003cbranch_path\u003e/ (worktree removed)\n```\n\nTips\n- You can target a task by omitting the id inside its worktree, or explicitly via `--task`, `--taskid`, `--branch`, or `--worktree`.\n- Historical locations for worktrees (`.mrtask/wt/\u003cid\u003e`, `$MRTASK_HOME/...`, `\u003crepo\u003e/.worktrees/\u003cid\u003e`, `\u003crepo-parent\u003e/\u003cbranch_path\u003e`, `\u003crepo-parent\u003e/\u003ctask-id\u003e`, legacy `\u003crepo-parent\u003e/\u003crepo-name\u003e-wt/\u003cid\u003e`) are also detected during cleanup.\n\n---\n\n### Guard Timeline (where checks run)\n\nThe main diagram stays intentionally simple. This companion diagram shows exactly where guard checks execute and which rules run.\n\n```mermaid\nstateDiagram-v2\n    classDef cmd fill:#FFF3B0,stroke:#F2A50C,stroke-width:2px,color:#111\n    classDef guard fill:#E8F7FF,stroke:#0EA5E9,color:#0B3B5C\n    classDef error fill:#FFE8E8,stroke:#EF4444,color:#7F1D1D\n    classDef warn fill:#FFF9E6,stroke:#F59E0B,color:#78350F\n    classDef action fill:#cFc9E6,stroke:#F59E0B,color:#78350F\n\n    [*] --\u003e ADD\n    ADD: mrtask add\n    class ADD cmd\n\n    ADD --\u003e OPEN\n    state OPEN {\n        [*] --\u003e PRE_COMMIT\n        PRE_COMMIT: pre-commit (hook)\n        PRE_COMMIT --\u003e PRE_PUSH\n        PRE_PUSH: pre-push (hook/CI)\n    }\n\n    PRE_COMMIT --\u003e PR\n    PRE_PUSH --\u003e PR\n    PR: mrtask pr\n    class PR cmd\n    PR --\u003e REVIEW\n    REVIEW --\u003e NOT_ACCEPTED\n    NOT_ACCEPTED --\u003e OPEN\n    REVIEW --\u003e MERGE_ACCEPTED\n    REVIEW --\u003e MRTASK_REMOVE\n    REVIEW --\u003e MRTASK_CANCEL\n    MRTASK_CANCEL: mrtask cancel\n    MRTASK_REMOVE: mrtask remove\n    MRTASK_REMOVE --\u003e [*]: removed\n    MRTASK_CANCEL --\u003e [*]: canceled\n    class MRTASK_CANCEL cmd\n    class MRTASK_REMOVE cmd\n        \n    MERGE_ACCEPTED --\u003e MERGE\n    MERGE: merge\n    MERGE --\u003e DONE\n    DONE: mrtask done\n    class DONE cmd\n    DONE --\u003e [*]: complete\n\n    class PRE_COMMIT action \n    class PRE_PUSH action\n    class MERGE action \n\n    note right of PRE_COMMIT\n      Guards:\n      - allowed-dirs (ERROR)\n      - mtime-compare (WARN)\n    end note\n\n    note right of PRE_PUSH\n      Guards:\n      - upstream-conflict (ERROR)\n      - allowed-dirs (ERROR)\n      - mtime-compare (WARN)\n    end note\n\n    note right of PR\n      CI reruns the same rules as pre-push\n    end note\n\n    note right of MERGE\n      To merge explicitly from CLI, use:\n      - mrtask accept (via GitHub gh)\n      - or local fast-forward with --local-ff\n    end note\n\n    note right of DONE\n      Verification at done:\n      - merged check (fetch --all; ancestor or tree equality)\n      - cleanup: move YAML to .mrtask/done/, remove worktree, safe local branch delete\n      - never merges; use `mrtask accept` for acceptance\n    end note\n```\n\nWhy two diagrams?\n- The main diagram teaches the lifecycle fast, without visual noise.\n- The guard timeline makes enforcement explicit for those wiring hooks/CI.\n\n---\n\n## Guards \u0026 Policies (dep‑fence 0.3.x)\n\n`mrtask` runs a thin guard runner and uses guard rules from `dep-fence/guards`. Configure all rules in a single file at the repo root:\n\n- `.mrtask/dep-fence.config.ts` (default)\n- Override with `DEP_FENCE_CONFIG=/path/to/config.ts`\n\nRun modes\n- `pre-commit` — checks staged files (local hygiene)\n- `pre-push` — checks for upstream conflicts and scope creep (team safety)\n- `manual` — on demand run for CI or local checks\n\nInstall hooks\n\n```bash\npnpm run hooks:install\n```\n\nRun manually\n\n```bash\npnpm run guard -- --mode pre-commit\npnpm run guard -- --mode pre-push\n```\n\nCI example (GitHub Actions)\n\n```yaml\n- name: dep-fence (pre-push parity)\n  run: pnpm run guard -- --mode pre-push\n```\n\n### The Three Rules\n\n1) allowed‑dirs\n- Purpose: prevent unrelated, cross‑repo‑area changes from slipping into a commit.\n- Behavior: in pre-commit, fails if any staged file falls outside allowed globs.\n- Config: `allow: string[]`, `action: 'error'|'warn'`\n\n2) mtime‑compare (lightweight)\n- Purpose: gently warn when code changed after the guard/SSOT changed.\n- Behavior: if any file in `groupA` is newer than the max mtime in `groupB`, warn/error.\n- Config: `groupA`, `groupB`, `epsilonMs`, `onlyTracked`, `action`\n\n3) upstream‑conflict (optimistic)\n- Purpose: block pushes if other authors modified protected files since your merge‑base.\n- Behavior: checks commits since merge‑base against `watch` globs; fails on foreign authors.\n- Config: `watch`, `baseRef`, `allowedAuthors`, `action`\n\nRecommended defaults\n- pre-commit: allowed‑dirs (error), mtime‑compare (warn)\n- pre-push: upstream‑conflict (error), allowed‑dirs (error), mtime‑compare (warn)\n\nOptional: per‑worktree session\n\nAdd `.mrtask/session.json` to narrow `allow`/`watch` for a specific worktree:\n\n```json\n{\n  \"allow\": [\"packages/foo/**\", \"packages/shared/**\", \"tools/types/**\"]\n}\n```\n\n---\n\n## Commands (Quick Reference)\n\n`mrtask init`\n- Initialize or print the home path used by integrations. Optional for most users.\n\n`mrtask create \u003cbranch\u003e \u003cslug\u003e [-d \u003ctext\u003e] \u003cdir1\u003e [dir2..]`\n- Create an isolated task: feature branch, worktree, and YAML.\n  - `--guards \u003cignore|warn|error\u003e`: directory guards level written to YAML\n  - `--wt-mode \u003csibling|home|repo-subdir\u003e`: worktree placement (default: sibling)\n  - `--sparse`, `--dry-run`, `--silent`, CSV via `-t \u003cfile.csv:line\u003e`\n\n`mrtask add \u003cslug\u003e [-d \u003ctext\u003e] \u003cdir1\u003e [dir2..] [--parent \u003cid|short8|yaml\u003e]`\n- Add a shared task: create YAML only, reusing an existing worktree on the branch.\n  - Auto-selects a parent on the same branch by dir match when `--parent` is omitted.\n  - Recomputes branch guards as the union of open tasks; `--guards` writes the per-task preference.\n  - Deprecated: `--strict`/`--no-strict` map to `error/warn` and are deprecated.\n\n`mrtask list [--all] [--status \u003copen|done|cancelled\u003e] [--short]`\n- List tasks discovered under workspace packages.\n\n`mrtask show \u003cid\u003e`\n- Show details of one task.\n\n`mrtask dump [--all] [--status \u003cstatus\u003e] [--ndjson]`\n- Machine‑friendly JSON/NDJSON of tasks for automation.\n\n`mrtask pr [id|path] [--base main] [--remote origin] [--push] [--draft] [--open] [--dry-run|--no-dry-run] [--task \u003cyaml\u003e] [--taskid \u003cid\u003e] [--branch \u003cname\u003e] [--worktree \u003cpath\u003e]`\n- Build a PR draft from the task + current diff. With `--push`, sets upstream and prints/open compare/PR. With `--dry-run`, no git operations are performed (e.g. `--push` is ignored).\n - Accepts: YAML path / id prefix / 8-char short hash (as shown by `mrtask list`).\n\n`mrtask ci \u003cid|path\u003e [--template .github/workflows/dep-fence-guards.yml] [--add \u003cglob...\u003e] [--message \u003cmsg\u003e] [--base main] [--remote origin] [--draft] [--open] [--dry-run|--no-dry-run]`\n- Bootstrap CI workflow into the task’s worktree, stage optional files, commit, push, and create/open a PR.\n  - Defaults to `--dry-run`; use `--no-dry-run` to execute.\n  - Typical: `mrtask ci --add \"packages/*/UNUSED_*\" --template .github/workflows/dep-fence-guards.yml --push --draft --open --no-dry-run`\n\n`mrtask done [id] [--task \u003cyaml\u003e] [--taskid \u003cid\u003e] [--branch \u003cname\u003e] [--worktree \u003cpath\u003e]`\n- Verify merged state, then move YAML to `.mrtask/done/`, remove worktree, delete branch safely.\n- If not merged, it refuses and prints hints to create/merge a PR or to use `mrtask accept`.\n - Accepts: YAML path / id prefix / 8-char short hash.\n\n`mrtask cancel [id] [--task \u003cyaml\u003e] [--taskid \u003cid\u003e] [--branch \u003cname\u003e] [--worktree \u003cpath\u003e]`\n- Mark canceled: move YAML to `.mrtask/cancel/`, remove worktree, force‑delete branch.\n - Accepts: YAML path / id prefix / 8-char short hash.\n\n`mrtask remove [id] [--task \u003cyaml\u003e] [--taskid \u003cid\u003e] [--branch \u003cname\u003e] [--worktree \u003cpath\u003e]`\n- Delete record entirely: delete YAML, remove worktree, force‑delete branch.\n - Accepts: YAML path / id prefix / 8-char short hash.\n\n`mrtask accept \u003cid|path\u003e [--strategy squash|merge|rebase] [--delete-branch] [--yes] [--base main] [--remote origin] [--local-ff]`\n- Merge acceptance step (opt‑in). Uses GitHub CLI (`gh`) to merge the open PR for the branch, or tries a local fast‑forward when `--local-ff` is set.\n- Keep this separate from `done` to respect repo policies (branch protection, merge queues, squash/rebase preferences).\n\n`mrtask doctor`\n- Check for orphaned worktrees, broken links, invalid YAML.\n\n---\n\n### Guards in YAML\n\nWhen specified, the task YAML includes:\n\n```yaml\nguards:\n  level: warn # or error|ignore\n```\n\nIf omitted, the default behavior is equivalent to `warn` but the field is not written.\n\n---\n\n## Examples\n\nHappy path (add → pr → done)\n\n```mermaid\nstateDiagram-v2\n    classDef cmd fill:#FFF3B0,stroke:#F2A50C,stroke-width:2px,color:#111\n\n    [*] --\u003e CMD_CREATE\n    CMD_CREATE: mrtask create\n    class CMD_CREATE cmd\n    CMD_CREATE --\u003e OPEN\n    state OPEN {\n      [*] --\u003e TaskOpen\n      TaskOpen: Task YAML (mrtask/ID.yml)\n      TaskOpen: Branch created (feature)\n      TaskOpen: Worktree created\n    }\n\n    OPEN --\u003e CMD_PR\n    CMD_PR: mrtask pr\n    class CMD_PR cmd\n    CMD_PR --\u003e REVIEW\n    REVIEW --\u003e CMD_DONE: merge accepted\n\n    CMD_DONE: mrtask done\n    class CMD_DONE cmd\n    CMD_DONE --\u003e DONE\n    state DONE {\n      [*] --\u003e Cleanup\n      Cleanup: YAML moved to done\n      Cleanup: Worktree removed\n      Cleanup: Branch deleted\n      Cleanup --\u003e [*]\n    }\n```\n\nGuards: See “Guard Timeline”. Pre-commit runs before commits; pre-push/CI runs before PR/push.\n\nCancel path (add → pr → cancel)\n\n```mermaid\nstateDiagram-v2\n    classDef cmd fill:#FFF3B0,stroke:#F2A50C,stroke-width:2px,color:#111\n\n    [*] --\u003e CMD_CREATE\n    CMD_CREATE: mrtask create\n    class CMD_CREATE cmd\n    CMD_CREATE --\u003e OPEN\n    state OPEN {\n      [*] --\u003e TaskOpen\n      TaskOpen: Task YAML (mrtask/ID.yml)\n      TaskOpen: Branch created\n      TaskOpen: Worktree created\n    }\n\n    OPEN --\u003e CMD_PR\n    CMD_PR: mrtask pr\n    class CMD_PR cmd\n    CMD_PR --\u003e REVIEW\n    REVIEW --\u003e CMD_CANCEL: close without merge\n\n    CMD_CANCEL: mrtask cancel\n    class CMD_CANCEL cmd\n    CMD_CANCEL --\u003e CANCEL\n    state CANCEL {\n      [*] --\u003e Cleanup\n      Cleanup: YAML moved to cancel\n      Cleanup: Worktree removed\n      Cleanup: Branch deleted (forced)\n      Cleanup --\u003e [*]\n    }\n```\n\nGuards: See “Guard Timeline”. Same pre-commit and pre-push coverage applies.\n\nRemove path (add → remove)\n\n```mermaid\nstateDiagram-v2\n    classDef cmd fill:#FFF3B0,stroke:#F2A50C,stroke-width:2px,color:#111\n\n    [*] --\u003e CMD_CREATE\n    CMD_CREATE: mrtask create\n    class CMD_CREATE cmd\n    CMD_CREATE --\u003e OPEN\n    state OPEN {\n      [*] --\u003e TaskOpen\n      TaskOpen: Task YAML (mrtask/ID.yml)\n      TaskOpen: Branch created\n      TaskOpen: Worktree created\n    }\n\n    OPEN --\u003e CMD_REMOVE\n    CMD_REMOVE: mrtask remove\n    class CMD_REMOVE cmd\n    CMD_REMOVE --\u003e REMOVE\n    state REMOVE {\n      [*] --\u003e Cleanup\n      Cleanup: YAML deleted\n      Cleanup: Worktree removed\n      Cleanup: Branch deleted (forced)\n      Cleanup --\u003e [*]\n    }\n```\n\nGuards: See “Guard Timeline”. Pre-commit still applies; no PR/push in this path.\n\n---\n\n## Troubleshooting\n\n- Guards are too strict and block work\n  - Start with `mtime-compare` at `warn`, and invest in good `allow` globs for `allowed-dirs`.\n- upstream‑conflict keeps failing\n  - `git fetch --all` and rebase/merge as needed. The rule fails when protected files have upstream changes by other authors since your base.\n- Unexpected path excluded by a glob\n  - Review order and negations in `.mrtask/dep-fence.config.ts`. Put `!` exclusions last for readability.\n- `mrtask done` says \"Not merged\"\n  - Create/merge a PR first: `mrtask pr \u003cid\u003e --push --open` and merge on the platform, or run `mrtask accept \u003cid\u003e --strategy squash` to merge via GitHub CLI. Then run `mrtask done \u003cid\u003e` again.\n\n---\n\n## Design Notes\n\n- Logical branch names stay constant; physical branches get auto‑unique suffixes for multiple worktrees.\n- SSOT: per‑package `.mrtask/` stays in `main`. Guard config lives centrally at `.mrtask/dep-fence.config.ts`.\n- Hooks focus on staged changes at pre-commit; pre-push/CI re‑checks with upstream awareness.\n- Rules are path/glob based with no hidden timing or freshness heuristics beyond optional mtime tolerance.\n\n---\n\n## Author\n\nHiroya Kubo \u003chiroya@cuc.ac.jp\u003e\n\n## License\n\nMIT — see `LICENSE`.\n\n---\n\n## Related Sites\n\n- mrtask (GitHub): https://github.com/kubohiroya/mrtask\n- mrtask (npm): https://www.npmjs.com/package/mrtask\n- dep-fence (GitHub): https://github.com/kubohiroya/dep-fence\n- dep-fence (npm): https://www.npmjs.com/package/dep-fence\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubohiroya%2Fmrtask","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubohiroya%2Fmrtask","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubohiroya%2Fmrtask/lists"}