Taskfile.yml

# Taskfile for Harmon DevKit
# https://taskfile.dev
version: "3"

output:
  group:
    begin: "::group::{{.TASK}}"
    end: "::endgroup::"

includes:
  # Foreman — deterministic supervisor for milestone-driven agent dispatch
  # (task foreman:plan / dispatch / shepherd / watch ...; the CLI is pinned
  # and fetched via uvx in taskfiles/foreman.yml)
  foreman: taskfiles/foreman.yml

# ── Entry Points ───────────────────────────────────────────────────
tasks:
  default:
    desc: Interactive task menu (tv)
    cmds:
      - task: menu-tv

  menu:
    desc: Interactive task menu (fzf)
    silent: true
    interactive: true
    cmds:
      - |
        selected=$(task --list-all | fzf --reverse --header-lines=1)
        if [ -n "$selected" ]; then
          task_name=$(echo "$selected" | awk '{sub(/:$/, "", $2); print $2}')
          task "$task_name"
        fi

  menu-tv:
    desc: Interactive task menu (tv)
    silent: true
    interactive: true
    cmds:
      - |
        selected=$(task --list-all | grep -v "task: Available" | grep -v "\* menu:" | tv)
        if [ -n "$selected" ]; then
          task_name=$(echo "$selected" | awk '{sub(/:$/, "", $2); print $2}')
          task "$task_name"
        fi

  ci:
    # Full local mirror of the CI pipeline — use on demand when CI is red and
    # you want to iterate locally, without waiting on each PR push. The pre-PR
    # gate is `task verify` + `task security`; this adds the rest.
    # The PR-metadata closing guard stays outside offline `verify`, so run it
    # explicitly before building on `verify` and adding every OTHER check the
    # build workflow runs, so the two cannot drift apart.
    # Note: verify:skills is intentionally omitted here because harmon-devkit
    # is the skills source and its dogfood symlinks refuse self-vendoring.
    desc: Full CI mirror (guard:closing-keywords → verify → test:devcontainer:permissions → security)
    cmds:
      - task: guard:closing-keywords
      - task: verify
      - task: test:devcontainer:permissions
      - task: security

  verify:
    # The definition-of-done gate — everything that must pass before a change
    # is done. Foreman v2 calls this the "check + build + test" tier; the desc
    # below lists this repo's exact steps. For the fast inner loop use `check`;
    # heavier security checks stay in `ci`. The devcontainer permission
    # assertion is daemon-free and subsecond, so it remains in this gate.
    desc: Definition-of-done gate (check → validate → guards → devcontainer → test)
    cmds:
      - task: check
      - task: audit:agent-instructions
      - task: validate
      - task: test:suite
      - task: test

  ci:repo-guards:
    # CI-only aggregate: verify lists its offline members separately.
    # The workflow parity step stays outside this task so it can guard the suite call.
    # This skills source uses native dogfood links; never self-vendor here.
    desc: Repository instruction audit and test suite
    cmds:
      - task: audit:agent-instructions
      - task: test:suite

  test:suite:
    # The ONE list of `test:*` targets that both `verify` and the required Build
    # workflow's `repo-guards` job run (through ci:repo-guards), so
    # the two cannot drift and nothing parses the workflow to police them.
    # A new `test:*` guard that belongs in the gate is added HERE and nowhere
    # else; `test:verify-ci-parity` fails if either caller stops running it.
    # Not in this list: `build`, `validate` and `test` (the project's own tiers
    # — CI runs them in their own job) and the `ci`-only checks.
    # Members run concurrently: each must confine filesystem and Git writes to its own mktemp fixture and bind no port.
    desc: The test:* targets verify and the Build workflow's repo-guards job both run (members run in parallel; set TASK_CONCURRENCY=1 for serial execution)
    deps:
      - task: test:agent-instructions-size
      - task: test:agent-skill-links
      - task: test:agent-registry
      - task: test:label-lifecycle
      - task: test:review-skill
      - task: test:consumer-pin-audit
      - task: test:registry-drift
      - task: test:registry-docs
      - task: test:label-registry
      - task: test:tasks
      - task: test:grep-q-pipes
      - task: test:ci-results
      - task: test:ci-changes-classify
      - task: test:output
      - task: test:status
      - task: test:gh-scopes
      - task: test:related-repos
      - task: test:setup-remote
      - task: test:meta-install
      - task: test:codex-review
      - task: test:integrate-codex
      - task: test:integrate-marker
      - task: test:integrate-readiness
      - task: test:integrate-update-branch
      - task: test:round-push
      - task: test:remote-codex-policy
      - task: test:lint-hygiene
      - task: test:claude-workflow-result
      - task: test:release-title
      - task: test:notify-release
      - task: test:claim-release-merged
      - task: test:setup-github
      - task: test:setup-github-project
      - task: test:classification-reconcile
      - task: test:sync-devkit-release
      - task: test:worktree
      - task: test:session-cleanup
      - task: test:statusline
      - task: test:devcontainer:permissions
      - task: test:link-claude-json
      - task: test:image-staleness
      - task: test:open-devcontainer
      - task: test:bot-autonomy
      - task: test:agent-profile
      - task: test:devcontainer-changed
      - task: test:verify-ci-parity

  test:label-lifecycle:
    desc: Check lifecycle label writes against the canonical transition table
    cmds:
      - ./scripts/test-label-lifecycle.sh

  # ── Quality Checks ────────────────────────────────────────────
  check:
    # Fast local gate (target: well under a minute) — safe for editors, git
    # hooks, and AI agents to run on every change without getting bogged down.
    desc: Fast local gate — all linters (and TypeScript checking when enabled), in parallel (set TASK_CONCURRENCY=1 for serial execution)
    deps:
      - lint

  audit:agent-instructions:
    desc: Warn when AGENTS.md exceeds Codex's default 32 KiB discovery budget
    cmds:
      - ./scripts/check-agent-instructions-size.sh AGENTS.md

  audit:consumer-pin:
    desc: "Check a repo's vendored-skill pin against its .devflow.toml shape (usage: task audit:consumer-pin -- [--repo-root DIR] [--json])"
    cmds:
      - ./ai/skills/universal/orchestrate/assets/consumer-pin-audit.sh {{.CLI_ARGS}}

  lint:
    desc: Run all linters in parallel
    deps:
      - lint:yaml
      - lint:shell
      - lint:markdown
      - lint:actions
      - lint:hygiene
      - lint:shell-robustness
      - lint:pin-pairs

  lint:yaml:
    desc: yamllint
    cmds:
      - yamllint {{.CLI_ARGS | default "."}}

  lint:shell:
    desc: shellcheck + shfmt
    cmds:
      # Shell templates are executable source assets too. Snippets remain
      # excluded because they may be deliberately incomplete fragments.
      - ./scripts/shell-quality.sh check --exclude-snippets {{.CLI_ARGS}}

  lint:markdown:
    # Check-only (no --fix) so this is a read-only gate like lint:prettier /
    # lint:shell: CI and the pre-commit hook fail loudly instead of silently
    # mutating the tree (and, in CI, discarding the fix while reporting green).
    # Auto-fix lives in `task format` / `task format:file`. The bin-vs-npx
    # dispatch + default glob set live in scripts/markdownlint.sh.
    desc: markdownlint-cli2 (check mode)
    cmds:
      - ./scripts/markdownlint.sh check {{.CLI_ARGS}}

  lint:actions:
    desc: actionlint on GitHub workflows
    env:
      # SC2016 flags '$' in single quotes, but we intentionally single-quote
      # jq expressions that use '$var' placeholders.
      SHELLCHECK_OPTS: --exclude=SC2016
    cmds:
      - actionlint

  lint:pin-pairs:
    desc: Version pins and their paired checksum pins moved together (scripts/test-tool-pin-pairs.sh)
    cmds:
      - ./scripts/test-tool-pin-pairs.sh

  lint:hygiene:
    desc: File hygiene (trailing whitespace, EOF newlines, merge markers, etc.)
    cmds:
      - ./scripts/lint-hygiene.sh {{.CLI_ARGS}}

  lint:shell-robustness:
    # Two idioms shellcheck does not model, both of which report a SUCCESS as a
    # failure and cost real gate time (#689): `cmd | grep -q` under pipefail,
    # and a test reporter whose own exit status lands inside the assertion.
    desc: Shell idioms whose exit status lies (`| grep -q`, reporter helpers)
    cmds:
      - ./scripts/lint-shell-robustness.sh {{.CLI_ARGS}}

  lint:commit-msg:
    desc: Validate commit message (conventional commits)
    cmds:
      - npx --yes --package @commitlint/cli --package @commitlint/config-conventional -- commitlint --edit {{.CLI_ARGS}}

  lint:commit-msg:text:
    desc: "Validate a commit message read from stdin (usage: printf '%s' <message> | task lint:commit-msg:text)"
    cmds:
      - npx --yes --package @commitlint/cli --package @commitlint/config-conventional -- commitlint

  # ── Validation ─────────────────────────────────────────────────
  validate:
    desc: Validate project config/artifacts
    cmds:
      - task: openspec:validate
      - task: validate:openspec-skills
      - task: validate:skills
      - task: validate:agents
      - task: validate:independence

  openspec:validate:
    desc: Validate OpenSpec changes and specs (strict)
    cmds:
      - ./scripts/openspec.sh validate --all --strict --no-interactive

  validate:openspec-skills:
    desc: Guard vendored OpenSpec skills (pinned wrapper, frontmatter, permissions)
    cmds:
      - ./scripts/validate-openspec-skills.sh

  validate:skills:
    desc: Guard shared agent skills (unique names across categories, valid SKILL.md frontmatter)
    cmds:
      - ./scripts/verify-skills.sh

  validate:agents:
    desc: Guard shared subagents (flat layout, valid frontmatter, no skill-name collisions)
    cmds:
      - ./scripts/verify-agents.sh

  validate:independence:
    desc: Guard shipped output against personal-dotfiles references
    cmds:
      - ./scripts/verify-independence.sh

  guard:no-commit-to-main:
    desc: Block direct commits to main
    cmds:
      - |
        branch=$(git rev-parse --abbrev-ref HEAD)
        if [ "$branch" = "main" ]; then
          echo "Direct commits to main are blocked. Use a feature branch."
          exit 1
        fi

  guard:release-title:
    # The CI counterpart of a pre-commit hook — enforced by release-content-guard.yml
    # at PR time because the thing it checks (the PR title, which squash-merge feeds
    # to release-please) does not exist locally. A non-releasing title over
    # release-worthy content would merge without cutting a tag. RELEASE_CONTENT_PATHS
    # comes from the release_content_paths copier answer. Pre-flight before opening a
    # PR with an intended title:
    #   PR_TITLE="<title>" BASE_SHA=main task guard:release-title
    # (CI passes PR_TITLE/PR_BODY + BASE_SHA/HEAD_SHA; CHANGED_FILES overrides the diff.)
    desc: "Guard: a PR touching release-worthy paths needs a fix:/feat: title"
    vars:
      RELEASE_CONTENT_PATHS: "ai/skills ai/agents templates scripts"
    cmds:
      - ./scripts/require-release-title.sh {{.RELEASE_CONTENT_PATHS}}

  guard:closing-keywords:
    # Same-repo `Closes #N` must not merge while #N still has unchecked
    # acceptance criteria. CI runs check-closing-keywords.sh directly from a
    # trusted default-branch copy (closing-keywords.yml); this target is the
    # LOCAL pre-flight, documented in AGENTS.md's Development Workflow:
    #   PR_TITLE="<title>" PR_BODY="$(cat body.md)" task guard:closing-keywords
    # With both unset it reads the branch's open PR; before a PR exists it
    # scans the commit messages with inert placeholder metadata.
    # (BASE_SHA/HEAD_SHA override the range; GH_REPO overrides the repo.)
    desc: "Guard: same-repo closing keywords require a completed issue checklist"
    cmds:
      - ./scripts/guard-closing-keywords.sh

  # Entry point for .github/workflows/sync-harmon-devkit.yml: resolves the
  # latest harmon-devkit release, bumps .skills-sync.yaml, vendors, verifies
  # offline, and opens/updates ONE rolling bot/sync-harmon-devkit PR.
  # Never merges anything. `{{.CLI_ARGS}}` passes an explicit tag for the
  # manual recovery path (`task sync:devkit-release -- vX.Y.Z`).
  sync:devkit-release:
    desc: "Pin the latest harmon-devkit release, vendor it, verify, and open/update the sync PR"
    cmds:
      - ./scripts/sync-devkit-release.sh run {{.CLI_ARGS}}

  test:agent-skill-links:
    desc: Unit-test migration-safe Claude-to-.agents skill compatibility links
    cmds:
      - ./scripts/test-agent-skill-links.sh

  # ── Skills sync ────────────────────────────────────────────────
  # Vendor shared agent skills from harmon-devkit, pinned in .skills-sync.yaml.
  # The verify:skills* drift checks skip cleanly until the first `task sync:skills`,
  # so a fresh scaffold stays green. See docs/CHECKLIST.md.
  sync:skills:
    desc: Vendor the pinned skill categories from harmon-devkit into .agents/skills
    cmds:
      - ./scripts/sync-skills.sh sync
      - ./scripts/link-agent-skills.sh sync

  skills:status:
    desc: "Report the vendoring state (network unless --offline)"
    cmds:
      - ./scripts/sync-skills.sh status {{.CLI_ARGS}}

  verify:skills:
    desc: "Skill drift check (network): fail if vendored skills differ from the pinned ref"
    cmds:
      - ./scripts/link-agent-skills.sh verify
      - ./scripts/sync-skills.sh verify

  verify:skills:offline:
    desc: "Fast offline check that the vendored ref matches the manifest (no network)"
    cmds:
      - ./scripts/link-agent-skills.sh verify
      - ./scripts/sync-skills.sh verify-offline

  format:
    desc: Auto-format code
    cmds:
      - ./scripts/shell-quality.sh format --exclude-snippets
      # Best-effort markdown auto-fix (bin-vs-npx dispatch in the helper); must
      # NOT abort `format` on un-auto-fixable rule violations — `lint:markdown`
      # (check-only) is the gate.
      - ./scripts/markdownlint.sh fix

  format:file:
    desc: "Format a single file by extension (usage: task format:file -- <path>)"
    cmds:
      - |
        f={{.CLI_ARGS}}
        [ -z "$f" ] && exit 0
        [ -f "$f" ] || exit 0
        case "$f" in
        *.sh | *.bash) shfmt -w "$f" ;;
        *.md | *.mdx) ./scripts/markdownlint.sh fix "$f" ;;
        esac

  fix:
    desc: Format then lint
    cmds:
      - task: format
      - task: lint

  # ── Tests ──────────────────────────────────────────────────────
  test:
    desc: Run all project tests
    deps:
      - test:tasks
      - test:hooks
      - test:skills
      - test:agents
      - test:hygiene
      - test:archive-hook
      - test:track-work
      - test:claim-label-resolution
      - test:triage-skill
      - test:groom-skill
      - test:shared-issue-assets
      - test:skill-index-lifecycle
      - test:independence
      - test:render-bundle
      - test:confirm-answers
      - test:migrate-label-family
      - test:result-schemas
      - test:result-schema-composition
      - test:schema-parity
      - test:dev-flow-stats
      - test:dev-flow-exit
      - test:run-record
      - test:inline-record
      - test:plan-revise
      - test:devflow-conformance
      - test:devflow-finders
      - test:dev-flow-monitor
      - test:provision-lane
      - test:post-evidence
      - test:record-pass
      - test:render-dev-flow
      - test:retro-run-report
      - test:finder-normalization
      - test:finder-review
      - test:lane-brief-template
      - test:lane-fences
      - test:lint-shell-robustness
      - test:lane-watch
      - test:settle-wait
      - test:lane-launch-and-waits

  test:agent-registry:
    desc: Schema-check the machine-readable agent registry and its cross-record invariants
    cmds:
      - ./scripts/test-agent-registry.sh

  test:result-schemas:
    desc: Schema-check the dev-flow-v2 result/record schemas and their conformance fixtures
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/test-result-schemas.sh

  test:result-schema-composition:
    desc: Check the native composition of the dev-flow-v2 result envelope against its per-role payload schemas
    cmds:
      - node scripts/test-result-schema-composition.mjs

  test:schema-parity:
    desc: Assert dev-flow-support's vendored assets/schemas/ copy is byte-identical to the authoring ai/schemas/
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/test-schema-parity.sh

  test:dev-flow-stats:
    desc: Behavioral test for the Dev flow v2 evidence harvester, success metric, trajectory rendering, and policy replay
    cmds:
      - ./ai/skills/universal/retro/assets/test-dev-flow-stats.sh

  test:dev-flow-exit:
    desc: Behavioral test for the Dev flow v2 policy reader and exit-computation engine against fixture policies
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/test-dev-flow-exit.sh

  test:run-record:
    desc: Behavioral test for the Dev flow v2 run-record writer and slate lock, on fixture repositories only
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/test-run-record.sh

  test:inline-record:
    desc: End-to-end test of the inline confidence-stage path's solo run record (solo-init, receipt, adjudicate, evidence, readiness input, retro discovery), offline
    cmds:
      - ./scripts/test-inline-record.sh

  test:plan-revise:
    desc: Behavioral test for the Dev flow v2 plan-revision writer (base moves), on fixture repositories only
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/test-plan-revise.sh

  test:devflow-finders:
    desc: Test per-reviewer policy fields and recorded operator overrides
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/test-devflow-finders.sh

  test:devflow-conformance:
    desc: Run harmon-init's vendored .devflow.toml v2 conformance corpus against the vendored policy reader (blob-pinned inputs + a pin-mutation control)
    cmds:
      - ./scripts/test-devflow-conformance.sh

  test:dev-flow-monitor:
    desc: Trust contract regression tests for dev-flow-monitor.sh (integer actor IDs, per-write governing revision, fail-closed)
    cmds:
      - ./ai/skills/universal/orchestrate/assets/test-dev-flow-monitor.sh

  test:provision-lane:
    desc: Provision planned lanes through real writers in fixture repositories
    cmds:
      - ./ai/skills/universal/orchestrate/assets/test-provision-lane.sh

  test:record-pass:
    desc: Offline local finder recording and detached checkout lifecycle tests
    cmds:
      - ./ai/skills/universal/review/assets/test-record-pass.sh

  test:post-evidence:
    desc: Offline reserve-first round-evidence publication and registration tests
    cmds:
      - ./ai/skills/universal/review/assets/test-post-evidence.sh

  test:lane-watch:
    desc: Fixture-driven regression tests for the orchestrator lane watcher
    cmds:
      - ./scripts/test-lane-watch.sh

  test:settle-wait:
    desc: Stubbed herdr/gh regression tests for the orchestrator's unit-safe lane and CI settle waits
    cmds:
      - ./ai/skills/universal/orchestrate/assets/test-settle-wait.sh

  test:lane-launch-and-waits:
    desc: Guard the orchestrator's lane-launch env, --no-edit merges, and wait-primitive prose
    cmds:
      - ./scripts/test-lane-launch-and-waits.sh

  test:render-dev-flow:
    desc: Golden-fixture + fake-gh regression tests for the dev-flow-v2 renderer/publisher
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/test-render-dev-flow.sh

  test:retro-run-report:
    desc: Behavioral test for the /retro skill's run-evidence projection (fixture trajectories, stubbed gh and harvester)
    cmds:
      - ./scripts/test-retro-run-report.sh

  test:consumer-pin-audit:
    desc: Behavioral test for the Dev flow v2 consumer pin contract and older-shape policy refusals
    cmds:
      - ./ai/skills/universal/orchestrate/assets/test-consumer-pin-audit.sh

  test:review-skill:
    desc: Fixture-driven regression checks for the /review stage contract
    cmds:
      - ./scripts/test-review-skill.sh

  test:finder-normalization:
    desc: Conformance checks that every finder's raw output decodes to the shared finding core
    cmds:
      - ./ai/skills/universal/review/assets/test-finder-normalization.sh

  test:finder-review:
    desc: Offline guards for the non-Codex local-CLI finder runner
    cmds:
      - ./scripts/test-finder-review.sh

  test:lane-brief-template:
    desc: Render and validate the orchestrator lane-brief template contract
    cmds:
      - ./scripts/test-lane-brief-template.sh

  test:lane-fences:
    desc: Verify orchestrated lane fence derivation and enforcement
    cmds:
      - ./scripts/test-lane-fences.sh

  devflow:render:
    desc: 'Render a dev-flow-v2 projection or publish generated sections (task devflow:render -- <projection|publish> --record <dir> ...)'
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/render-dev-flow.sh {{.CLI_ARGS}}
  test:worktree:
    desc: Behavioral test for worktree:new / worktree:rm (create → verify hooks → remove, in a throwaway fixture repo)
    cmds:
      - ./scripts/test-worktree.sh

  test:session-cleanup:
    desc: Behavioral test for audit:session-artifacts / clean:branches / clean:worktree-records (evidence-gated deletion + negative controls, in a throwaway fixture repo)
    cmds:
      - ./scripts/test-session-cleanup.sh

  test:agent-instructions-size:
    desc: Unit-test the non-blocking AGENTS.md size advisory
    cmds:
      - ./scripts/test-agent-instructions-size.sh

  test:registry-drift:
    desc: Bind label provisioning, provider wrappers, and Foreman adapters to the agent registry (offline drift gate)
    cmds:
      - ./scripts/test-registry-drift.sh

  test:registry-docs:
    # The answers-file name is configurable (`copier copy --answers-file …`),
    # and the check reads project_management out of it to know whether this
    # repo renders the GitHub Projects document at all. The script is a
    # verbatim twin of harmon-init's own, so the name is passed in rather than
    # templated into it — as an ENV value, not a command argument: a filename
    # containing an apostrophe would terminate a quoted shell argument early.
    # `tojson` emits a JSON string, which is also a valid YAML double-quoted
    # scalar, so quotes and backslashes in the name survive both layers. The
    # `string` filter first because copier hands this over as a PurePosixPath,
    # which `tojson` cannot serialize.
    desc: Bind the published family/harness tables in docs/project-management.md to the agent registry
    env:
      COPIER_ANSWERS_FILE: ".copier-answers.yml"
    cmds:
      - ./scripts/test-registry-docs.sh

  test:label-registry:
    # COPIER_ANSWERS_FILE tells the verbatim-twin script which tracker this
    # repo rendered — the linear project-management document shares the GitHub
    # one's path and must not be held to the label-taxonomy markers. Same
    # env-not-argument reasoning as test:registry-docs above.
    desc: Bind label provisioning, the docs taxonomy table, and the status inventory to the label registry
    env:
      COPIER_ANSWERS_FILE: ".copier-answers.yml"
    cmds:
      - ./scripts/test-label-registry.sh

  test:tasks:
    desc: Guard the Taskfile itself (compiles; setup tasks are safe no-ops)
    cmds:
      - ./scripts/test-tasks.sh

  test:grep-q-pipes:
    desc: Reject printf/echo pipelines into early-exiting grep
    cmds:
      - ./scripts/test-grep-q-pipes.sh

  test:verify-ci-parity:
    desc: Fail if the Build workflow stops calling test:suite or verify stops running it
    cmds:
      - ./scripts/test-verify-ci-parity.sh

  test:ci-changes-classify:
    desc: Unit-test the fail-closed docs-only CI classifier
    cmds:
      - ./scripts/test-ci-changes-classify.sh

  test:ci-results:
    desc: Unit-test CI aggregate and closing-keyword fail-closed truth tables
    cmds:
      - ./scripts/test-ci-results.sh

  audit:ruleset:
    desc: Compare the checked-in branch ruleset with GitHub's live ruleset (read-only)
    cmds:
      - ./scripts/audit-ruleset.sh

  test:output:
    desc: Unit-test shared color/Unicode fallbacks and spinner cleanup
    cmds:
      - ./scripts/test-output.sh

  test:status:
    desc: Unit-test the status board-writes + local-credential checks (stubbed CLIs, no network)
    # Run under a hostile ambient environment on purpose (#1395): the bot and agent
    # profiles export FOREMAN_DEVCONTAINER and a GH_TOKEN, and Claude Code on the
    # web presets GH_TOKEN/GITHUB_TOKEN, so the test must pass with them set. The
    # GH_HOST, GH_REPO, GH_REST_HOST and STATUS_NO_NETWORK canaries make the test's
    # family clear (GH_*, GITHUB_*, STATUS_*) fail if it narrows to a name list.
    cmds:
      - env FOREMAN_DEVCONTAINER=bot GH_TOKEN=dummy GITHUB_TOKEN=dummy GH_HOST=ambient.invalid GH_REPO=ambient/repo GH_REST_HOST=ambient.invalid STATUS_NO_NETWORK=1 ./scripts/test-status.sh

  test:gh-scopes:
    desc: Unit-test the gh scope refresh task's refusals and post-refresh verification (stubbed gh, no network)
    cmds:
      - ./scripts/test-setup-gh-scopes.sh

  test:related-repos:
    desc: Unit-test the related-repo bootstrap fallback and idempotency (stubbed gh/git, no network)
    cmds:
      - ./scripts/test-bootstrap-related-repos.sh

  test:setup-remote:
    desc: Unit-test task setup:remote — idempotency, the lefthook shim, sibling clone/fetch cases, and the SessionStart wrapper (stubbed tools, no network)
    cmds:
      - ./scripts/test-setup-remote.sh

  test:meta-install:
    desc: Unit-test the .meta sidecar installer's ~-expansion and refusals
    cmds:
      - ./scripts/test-meta-install.sh

  test:codex-review:
    desc: Unit-test codex-review.sh target selection (offline, stubbed codex)
    cmds:
      - ./scripts/test-codex-review.sh

  test:integrate-codex:
    desc: Unit-test current-head Codex cloud-review evidence (offline, stubbed gh)
    cmds:
      - ./scripts/test-integrate-codex.sh

  test:integrate-marker:
    desc: Unit-test the integration stage's gate-then-push marker parser (require-marker.sh)
    cmds:
      - ./scripts/test-integrate-marker.sh

  test:integrate-readiness:
    desc: Unit-test the integration readiness gate + read-only gh wrapper (offline, stubbed gh)
    cmds:
      - ./scripts/test-integrate-readiness.sh
      - ./scripts/test-readiness-app-token.sh

  test:integrate-update-branch:
    desc: Unit-test the guarded server-side catch-up helper update-branch.sh (offline, stubbed gh)
    cmds:
      - ./scripts/test-integrate-update-branch.sh

  test:round-push:
    desc: Unit-test the dev-flow-v2 diff-aware round-push broker (offline, local bare remotes)
    cmds:
      - ./ai/skills/universal/review/assets/test-round-push.sh
  test:remote-codex-policy:
    desc: Guard the remote second-model rule — no Codex credential vocabulary on a remote-environment surface (offline)
    cmds:
      - ./scripts/test-remote-codex-policy.sh

  test:claude-workflow-result:
    desc: Test Claude failure reporting and the optional zero-usage retry
    cmds:
      - ./scripts/test-claude-workflow-result.sh

  test:lint-hygiene:
    desc: Behavioral fixtures for lint-hygiene's trigger-phrase adjacency scan
    cmds:
      - ./scripts/test-lint-hygiene.sh

  test:lint-shell-robustness:
    desc: Unit-test the status-lying shell idiom guard (lint-shell-robustness.sh)
    cmds:
      - ./scripts/test-lint-shell-robustness.sh


  test:release-title:
    desc: Unit-test the release-content title guard (require-release-title.sh)
    cmds:
      - ./scripts/test-release-title.sh

  test:notify-release:
    desc: Unit-test the harmon-init release dispatch (offline, stubbed gh)
    cmds:
      - ./scripts/test-notify-devkit-release.sh

  test:claim-release-merged:
    desc: Unit-test terminal delivery claim release and review cleanup (offline, stubbed gh)
    cmds:
      - ./scripts/test-claim-release-merged.sh

  test:setup-github:
    desc: Unit-test repository-setting outcomes and failure propagation (stubbed gh, no network)
    cmds:
      - ./scripts/test-setup-github.sh

  test:track-work:
    desc: Unit-test the track-work skill's issue/PR tracking checks (offline)
    cmds:
      - ./scripts/test-track-work.sh
      - ./scripts/test-claim-transaction.sh
      - ./scripts/test-release-claim.sh
      - ./scripts/test-clear-needs-review.sh
      - task: test:file-review-finding

  test:file-review-finding:
    desc: Unit-test review follow-up filing (offline, stubbed gh)
    cmds:
      - ./scripts/test-file-review-finding.sh

  test:triage-skill:
    desc: "Unit-test the triage skill's contract scripts (offline, stubbed gh/claude)"
    cmds:
      - ./scripts/test-triage-skill.sh

  test:groom-skill:
    desc: "Unit-test the groom skill's contract scripts (offline, stubbed gh/claude)"
    cmds:
      - ./scripts/test-groom-skill.sh

  test:shared-issue-assets:
    desc: "Assert no drift across shared issue skill assets (offline)"
    cmds:
      - ./scripts/test-shared-issue-assets.sh

  test:classification-reconcile:
    desc: Unit-test the classification reconciler's decisions and the event workflow's filter (hermetic, no network)
    cmds:
      - ./scripts/test-classification-reconcile.sh

  test:sync-devkit-release:
    desc: "Unit-test the harmon-devkit release→sync-PR automation (offline, stubbed gh/task)"
    # Run under a hostile ambient environment on purpose (#1395): the bot and agent
    # profiles export FOREMAN_DEVCONTAINER and a GH_TOKEN, Claude Code on the web
    # presets GH_TOKEN/GITHUB_TOKEN, and the sync helper reads SYNC_DEVKIT_TAG,
    # SYNC_DEVKIT_ALLOW_DOWNGRADE and AGENT_SKILLS_DIR from its caller. The test
    # clears those three itself; this run presets all six to prove it passes with
    # them set.
    cmds:
      - env FOREMAN_DEVCONTAINER=bot GH_TOKEN=dummy GITHUB_TOKEN=dummy SYNC_DEVKIT_TAG=v0.48.0 SYNC_DEVKIT_ALLOW_DOWNGRADE=true AGENT_SKILLS_DIR=.agents/elsewhere ./scripts/test-sync-devkit-release.sh

  test:setup-github-project:
    desc: Unit-test the GitHub Project field reconciliation (stubbed gh, no network)
    cmds:
      - ./scripts/test-setup-github-project.sh

  test:devcontainer:root:
    desc: Smoke test the primary (AI bot) devcontainer via the devcontainers CLI
    cmds:
      - ./scripts/devcontainer-smoke.sh .devcontainer/devcontainer.json

  test:devcontainer:dev:
    desc: Smoke test the dev (human) devcontainer via the devcontainers CLI
    cmds:
      - ./scripts/devcontainer-smoke.sh .devcontainer/dev/devcontainer.json

  test:devcontainer:agent:
    # Builds and starts the agent posture, then proves live what its unit test
    # proves statically: the egress filter refuses an unlisted host and records
    # it, refused harnesses stay refused, and no forbidden credential or Docker
    # reached the container. Needs Docker, like the other smoke tasks.
    desc: Smoke test the agent (unattended) devcontainer via the devcontainers CLI
    cmds:
      - ./scripts/devcontainer-smoke.sh .devcontainer/agent/devcontainer.json

  test:devcontainer:permissions:
    desc: Unit-assert devcontainer permission invariants (no container needed)
    cmds:
      - ./scripts/devcontainer-assert.sh unit
      - ./scripts/test-devcontainer-git-ownership.sh

  test:statusline:
    desc: Unit-test the devcontainer status line renderer (no container needed)
    cmds:
      - ./scripts/test-statusline.sh

  test:link-claude-json:
    desc: Unit-test the ~/.claude.json persistence helper (no container needed)
    cmds:
      - ./scripts/test-link-claude-json.sh

  test:image-staleness:
    desc: Unit-test the image-staleness warning (no container needed)
    cmds:
      - ./scripts/test-image-staleness.sh

  test:open-devcontainer:
    desc: Unit-test the client-side dev container launcher (no VS Code needed)
    cmds:
      - ./scripts/test-open-devcontainer.sh

  test:bot-autonomy:
    # No devcontainer paths: filter gates this in CI — it runs as part of the
    # unconditionally-required `verify` job, so a registry change that adds an
    # uncovered harness slug fails on its own, regardless of which paths a PR
    # touches.
    desc: Unit-test bot-autonomy.sh's registry coverage, Codex parity, and per-module fixtures (no container needed)
    cmds:
      - ./scripts/test-bot-autonomy.sh

  test:agent-profile:
    # Wired into `verify` with no devcontainer paths: filter, like
    # test:bot-autonomy — the agent posture's single source, deny list, env
    # guard, Docker rule, and egress list are checked on every PR.
    desc: Unit-test the agent posture (single source, Claude/Codex policy, env guard, Docker, egress; no container needed)
    cmds:
      - ./scripts/test-agent-profile.sh

  test:devcontainer-changed:
    desc: Unit-test the devcontainer-build.yml change detector (devcontainer-changed.sh)
    cmds:
      - ./scripts/test-devcontainer-changed.sh


  test:hooks:
    desc: Round-trip the Taskfile targets the Claude hooks delegate to
    cmds:
      - ./scripts/test-hooks.sh
      - task: test:review-trigger-allow

  test:review-trigger-allow:
    desc: Exact review-trigger hook command and repository scope
    cmds:
      - ./scripts/test-review-trigger-allow.sh

  test:skills:
    desc: Unit-test skills tooling and registry-driven breakdown vocabulary discovery
    cmds:
      - ./scripts/test-skills.sh
      - ./scripts/test-breakdown-labels.sh

  test:claim-label-resolution:
    desc: Behavior-test portable claim identity and ownership-label resolution
    cmds:
      - ./scripts/test-claim-label-resolution.sh

  test:agents:
    desc: Unit-test the shared-subagent source guard (offline)
    cmds:
      - ./scripts/test-agents.sh

  test:hygiene:
    desc: Unit-test lint-hygiene's exec-bit check on shebanged files
    cmds:
      - ./scripts/test-hygiene.sh

  test:archive-hook:
    desc: Offline regression tests for the SessionEnd transcript-archive hook template
    cmds:
      - ./scripts/test-archive-hook.sh

  test:skill-index-lifecycle:
    desc: Guard public skill indexes against stale lifecycle language
    cmds:
      - ./scripts/test-skill-index-lifecycle.sh

  test:independence:
    desc: Unit-test the shipped-output independence guard (offline, temp repos)
    cmds:
      - ./scripts/test-independence.sh

  test:render-bundle:
    desc: Offline frozen-render producer and binding regressions
    cmds:
      - bash ai/skills/repo/standardize-repo/assets/test-render-bundle.sh

  test:confirm-answers:
    desc: Unit-test the standardize-repo copier answer confirmation gate (offline)
    cmds:
      - ./scripts/test-confirm-answers.sh

  test:migrate-label-family:
    desc: Unit-test the standardize-repo label-family rename/transfer script (offline)
    cmds:
      - ./scripts/test-migrate-label-family.sh

  # ── Second-model review (Codex) ───────────────────────────────
  # Optional second AI model (the OpenAI Codex CLI) reviewing the current
  # change — local and advisory only, never part of verify/ci. Findings are
  # hypotheses for the primary agent to adjudicate (AGENTS.md "Second-Model
  # Review"). The codex:gate:* tasks toggle the Claude Code codex plugin's
  # automatic stop-time review for this repo + machine. See
  # docs/guides/codex-review.md for setup, mechanics, and the loop caps.
  review:
    desc: Second-model verification review of the current change (Codex)
    cmds:
      - task: review:codex

  challenge:
    desc: Second-model adversarial review of the current change (Codex)
    cmds:
      - task: challenge:codex

  triage:
    # Backlog triage with a cheap headless model. Dry-run by default;
    # `task triage -- --execute` is the supervised apply mode (interactive
    # terminal required — issue #455's [HUMAN] gate). The skill contract and
    # its enforcement live in ai/skills/universal/triage.
    desc: "Triage the issue backlog (dry-run; task triage -- --execute to apply, supervised)"
    # interactive: the global `output: group` would otherwise pipe stdout, so
    # the wrapper's supervised-terminal check would refuse --execute even
    # from a real terminal.
    interactive: true
    cmds:
      - ./scripts/triage.sh {{.CLI_ARGS}}

  groom:
    # Backlog groom: verify open issues against the live code and merged PRs,
    # propose dispositions, publish a report, and (once approved) apply
    # through the checked write paths. Audit (dry-run) by default;
    # `task groom -- --execute` is the supervised apply mode (interactive
    # terminal required, same [HUMAN]-gate shape as triage). The skill
    # contract and its enforcement live in ai/skills/universal/groom.
    desc: "Groom the issue backlog (audit by default; task groom -- --execute to apply, supervised)"
    interactive: true
    preconditions:
      - sh: test -x ai/skills/universal/groom/assets/groom.sh
        msg: "Source-owned universal groom skill is missing or not executable (ai/skills/universal/groom/assets/groom.sh) — restore it from this repository"
    cmds:
      - ./ai/skills/universal/groom/assets/groom.sh {{.CLI_ARGS}}

  review:codex:
    desc: "Codex verification review (usage: task review:codex -- [--base <ref>|--uncommitted] [focus text])"
    cmds:
      - ./scripts/codex-review.sh review {{.CLI_ARGS}}

  challenge:codex:
    desc: "Codex adversarial review (usage: task challenge:codex -- [--base <ref>|--uncommitted] [focus text])"
    cmds:
      - ./scripts/codex-review.sh challenge {{.CLI_ARGS}}

  # Non-default local-CLI finders (agent-registry.json finders[], #796). OPT-IN:
  # the CLI is neither installed nor configured by this repo, the finder is not
  # in the shipped default set, and a missing binary refuses rather than exiting
  # 0 — a skipped finder reads as a clean pass. Codex stays the default.
  #
  # The CodeRabbit targets exist and REFUSE, by design: its CLI resolves its own
  # review scope and takes no target from us, so a local pass could not be bound
  # to the round's reviewed_head the way a confidence-stage slot requires. The
  # finder stays registered and the target stays here — the requirement is that
  # it be runnable locally and on the PR — so what is missing is visible rather
  # than silently absent. Tracked as harmon-devkit#809.
  review:coderabbit:
    desc: "CodeRabbit verification review (registered; refuses locally pending harmon-devkit#809)"
    cmds:
      - ./scripts/finder-review.sh review coderabbit {{.CLI_ARGS}}

  challenge:coderabbit:
    desc: "CodeRabbit adversarial review (registered; refuses locally pending harmon-devkit#809)"
    cmds:
      - ./scripts/finder-review.sh challenge coderabbit {{.CLI_ARGS}}

  review:copilot:
    desc: "Copilot verification review (usage: task review:copilot -- [--base <ref>|--uncommitted] [focus text])"
    cmds:
      - ./scripts/finder-review.sh review copilot {{.CLI_ARGS}}

  challenge:copilot:
    desc: "Copilot adversarial review (usage: task challenge:copilot -- [--base <ref>|--uncommitted] [focus text])"
    cmds:
      - ./scripts/finder-review.sh challenge copilot {{.CLI_ARGS}}

  devflow:policy:
    desc: "Resolve a Dev flow v2 .devflow.toml (usage: task devflow:policy -- resolve --policy <file> [--registry <file>] [--rigor <level>] [--json])"
    cmds:
      - node ai/skills/universal/dev-flow-support/assets/devflow-policy.mjs {{.CLI_ARGS}}

  devflow:exit:
    desc: "Compute a Dev flow v2 confidence-stage exit verdict (usage: task devflow:exit -- --run <dir> --stage <challenge|review> --policy <file> [--json])"
    cmds:
      - ./ai/skills/universal/dev-flow-support/assets/dev-flow-exit.sh {{.CLI_ARGS}}

  codex:gate:enable:
    desc: Enable the automatic Claude → Codex stop-gate review (this repo, this machine)
    cmds:
      - ./scripts/codex-gate.sh enable

  codex:gate:disable:
    desc: Disable the automatic Claude → Codex stop-gate review
    cmds:
      - ./scripts/codex-gate.sh disable

  codex:gate:status:
    desc: Show whether the Claude → Codex stop-gate review is enabled
    cmds:
      - ./scripts/codex-gate.sh status

  # ── Security ───────────────────────────────────────────────────
  security:
    desc: Run all free local security checks (Semgrep CE + gitleaks + dependency audit)
    deps:
      - security:sast
      - security:secrets
      - security:audit

  security:secrets:
    desc: Scan for leaked secrets (gitleaks)
    cmds:
      - ./scripts/gitleaks-scan.sh

  security:audit:
    desc: Dependency audit
    cmds:
      - echo "No package manifests to audit yet."

  security:sast:
    desc: Static application security testing (Semgrep Community Edition)
    cmds:
      - ./scripts/run-semgrep.sh {{.CLI_ARGS}}

  security:sca:
    desc: Software composition analysis (free package-manager audit)
    deps:
      - security:audit

  security:sast:snyk:
    desc: "Optional Snyk Code second-opinion scan (manual/local or explicitly scheduled); needs SNYK_TOKEN"
    cmds:
      - snyk code test --exclude=.worktrees,.foreman,.claude --severity-threshold=high {{.CLI_ARGS}}

  security:sca:snyk:
    desc: "Optional Snyk Open Source second-opinion scan (manual/local or explicitly scheduled); needs SNYK_TOKEN"
    cmds:
      - snyk test --all-projects --exclude=.worktrees,.foreman,.claude --severity-threshold=high --show-vulnerable-paths=all {{.CLI_ARGS}}

  # ── Secrets ────────────────────────────────────────────────────
  # Destination-only helpers: the secret value stays on stdin — never in argv,
  # env vars, Taskfile vars, or shell history (see docs/conventions.md).
  secret:set:1p:
    desc: "Set an existing 1Password field from stdin (usage: command | task secret:set:1p VAULT=... ITEM=... FIELD=... [SECTION=...])"
    env:
      VAULT: '{{.VAULT | default ""}}'
      ITEM: '{{.ITEM | default ""}}'
      FIELD: '{{.FIELD | default ""}}'
      SECTION: '{{.SECTION | default ""}}'
    cmds:
      - ./scripts/secret-set-1p.sh

  secret:set:gh:
    desc: "Set a GitHub repo secret from stdin (usage: command | task secret:set:gh NAME=... REPO=owner/repo)"
    env:
      NAME: '{{.NAME | default ""}}'
      REPO: '{{.REPO | default ""}}'
    cmds:
      - ./scripts/secret-set-gh.sh

  # ── Setup ──────────────────────────────────────────────────────
  bootstrap:
    desc: One-time machine setup (Homebrew)
    cmds:
      # Idempotent: skip the installer when Homebrew is already present. The
      # official installer's NONINTERACTIVE mode demands sudo up front and aborts
      # even when there is nothing to install, so guard on `brew` existing.
      - command -v brew >/dev/null 2>&1 || NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  install:
    desc: Install all project dependencies and tools
    cmds:
      # Brewfile deps by absolute path (never a user/global one), but a graceful
      # no-op when Homebrew is absent — this repo's devcontainer bakes its
      # toolchain into the image and ships no brew.
      - ./scripts/install-brewfile.sh
      # copier is needed by the skills tooling tests, which render local Copier
      # templates. On a brew host it comes from the Brewfile above; this script
      # covers the brew-less devcontainer via uv. Local to this repo: generated
      # repos don't render templates, so harmon-init keeps copier out of
      # template/ and it cannot arrive from the template.
      - ./scripts/install-copier.sh
      - task: install:hooks

  install:hooks:
    desc: Install git hooks via lefthook
    cmds:
      - lefthook install

  setup:remote:
    desc: Prepare this checkout for the dev loop on a remote platform (no devcontainer hooks) — git hooks, related repos cloned then fetched beside it, frozen dependencies. Idempotent
    cmds:
      - ./scripts/setup-remote.sh

  # ── GitHub setup ───────────────────────────────────────────────
  # One-time, idempotent repo settings applied via gh (safe to re-run); run once
  # the repo exists on GitHub. The remaining setup steps need a browser or a real
  # credential and stay manual — see docs/CHECKLIST.md (branch ruleset import,
  # Renovate/optional third-party app installs, Actions secrets, the CI GitHub App).
  setup:github:
    desc: >-
      Apply idempotent GitHub repo settings via gh (Dependabot alerts, private
      vulnerability reporting, Actions runner routing)
    vars:
      REPO: "evanharmon1/harmon-devkit"
    cmds:
      - >-
        ./scripts/setup-github.sh --repo "{{.REPO}}" --ci-runs-on '"ubuntu-latest"' {{.CLI_ARGS}}

  setup:github-project:
    desc: >-
      Idempotently create/sync the owner's GitHub Project V2 board + Status
      pipeline (on a personal account also its Product field). Requires the
      Projects scopes — `task setup:gh-scopes`.
    cmds:
      - ./scripts/setup-github-project.sh --owner "evanharmon1" --title "evanharmon1 Project"

  setup:gh-scopes:
    desc: >-
      OPERATOR / DEV PROFILE ONLY: refresh your interactive gh login so it
      carries every scope this repo needs (refuses against a GH_TOKEN env
      credential and without a TTY; verifies the grant landed). Bot containers
      must reissue GH_TOKEN instead.
    # Load-bearing, not cosmetic. This Taskfile sets `output: group` globally,
    # which pipes every task's stdout — so the script's own `[ -t 1 ]` guard saw
    # a pipe and refused with "no TTY" even in a real terminal, making the
    # documented entry point impossible to use. `interactive: true` tells Task
    # to skip output grouping and attach the task to the terminal, which is what
    # both the guard and the browser device-code flow it protects require.
    interactive: true
    cmds:
      - ./scripts/setup-gh-scopes.sh

  setup:github-labels:
    desc: Idempotently create/update this repo's starter labels incl. the foreman arming labels. Requires `gh` with repo write.
    vars:
      REPO: "evanharmon1/harmon-devkit"
    cmds:
      - ./scripts/setup-github-labels.sh --repo "{{.REPO}}" --foreman --release-please

  # One-time, idempotent repo settings applied via gh (safe to re-run); run once
  # the repo exists on GitHub. The remaining setup steps need a browser or a real
  # credential and stay manual — see docs/CHECKLIST.md (branch ruleset import,
  # Renovate/optional third-party app installs, Actions secrets, the CI GitHub App).
  # ── Release ────────────────────────────────────────────────────
  # Releases are intentional via release-please (.github/workflows/release.yml):
  # merge the rolling release PR to cut a release. release:init seeds the first
  # v0.1.0 tag; the release:patch/minor/major tasks remain as a manual override.
  release:init:
    desc: Create initial v0.1.0 tag
    cmds:
      - git tag -a v0.1.0 -m "Initial release"
      - git push origin v0.1.0
      - gh release create v0.1.0 --generate-notes --title "v0.1.0"

  release:patch:
    desc: Bump patch version and release
    vars:
      CURRENT_TAG:
        sh: git describe --tags --abbrev=0 --exclude="*-probe*" 2>/dev/null || echo "v0.0.0"
      NEXT_TAG:
        sh: echo "{{.CURRENT_TAG}}" | awk -F. '{printf "%s.%s.%d", $1, $2, $3+1}'
    cmds:
      - echo "Releasing {{.NEXT_TAG}} (was {{.CURRENT_TAG}})"
      - git tag -a {{.NEXT_TAG}} -m "Release {{.NEXT_TAG}}"
      - git push origin {{.NEXT_TAG}}
      - gh release create {{.NEXT_TAG}} --generate-notes --title "{{.NEXT_TAG}}"

  release:minor:
    desc: Bump minor version and release
    vars:
      CURRENT_TAG:
        sh: git describe --tags --abbrev=0 --exclude="*-probe*" 2>/dev/null || echo "v0.0.0"
      NEXT_TAG:
        sh: echo "{{.CURRENT_TAG}}" | awk -F. '{printf "%s.%d.0", $1, $2+1}'
    cmds:
      - echo "Releasing {{.NEXT_TAG}} (was {{.CURRENT_TAG}})"
      - git tag -a {{.NEXT_TAG}} -m "Release {{.NEXT_TAG}}"
      - git push origin {{.NEXT_TAG}}
      - gh release create {{.NEXT_TAG}} --generate-notes --title "{{.NEXT_TAG}}"

  release:major:
    desc: Bump major version and release
    vars:
      CURRENT_TAG:
        sh: git describe --tags --abbrev=0 --exclude="*-probe*" 2>/dev/null || echo "v0.0.0"
      NEXT_TAG:
        sh: echo "{{.CURRENT_TAG}}" | awk -F. '{printf "v%d.0.0", substr($1,2)+1}'
    cmds:
      - echo "Releasing {{.NEXT_TAG}} (was {{.CURRENT_TAG}})"
      - git tag -a {{.NEXT_TAG}} -m "Release {{.NEXT_TAG}}"
      - git push origin {{.NEXT_TAG}}
      - gh release create {{.NEXT_TAG}} --generate-notes --title "{{.NEXT_TAG}}"

  release:check-coverage:
    desc: "Detect feat/fix commits a tag ships that its changelog section omits (swallowed entries from a release-please merge race)"
    vars:
      TAG: '{{default "" .CLI_ARGS}}'
    env:
      TAG: '{{.TAG}}'
    cmds:
      - ./scripts/check-changelog-coverage.sh "$TAG"

  # ── Worktrees ──────────────────────────────────────────────────
  # One blessed entrypoint for parallel/isolated work, so anything that calls it
  # (a second agent session, a terminal multiplexer, a human) gets the same
  # ready tree instead of rediscovering the setup and the breakers.
  # See docs/conventions.md § Worktrees.
  #
  # Foreman is NOT routed through this task: it creates worktrees itself, inside
  # the pinned upstream CLI, and nothing here redirects that. This entrypoint
  # only makes sure the two agree on `.worktrees/` as the location.
  worktree:new:
    desc: "Create a ready linked worktree (usage: task worktree:new -- <name> [--branch b] [--base ref] [--no-install])"
    cmds:
      - ./scripts/worktree-new.sh {{.CLI_ARGS}}

  worktree:rm:
    desc: "Remove a linked worktree and prune its gitlink debris (usage: task worktree:rm -- <name> [--force])"
    cmds:
      - ./scripts/worktree-rm.sh {{.CLI_ARGS}}

  # ── Clean ──────────────────────────────────────────────────────
  clean:
    desc: Remove build artifacts and caches
    cmds:
      - rm -rf .task

  # ── Session cleanup ────────────────────────────────────────────
  # audit:* reports, clean:* acts — and deletion only ever runs on positive
  # evidence (a PR merged into the default branch at exactly the local tip,
  # or verified-fresh ancestry into the remote default), because squash-merge
  # makes ancestry blind to delivered branches. Every deletion is a guarded
  # compare-and-delete against the verified tip. Dry run by default; never a
  # force flag; never touches a worktree or a remote branch.
  audit:session-artifacts:
    desc: "Report session leftovers (unpushed branches, gone upstreams vs merged PRs, other worktrees, review sidecars) — mutates nothing"
    cmds:
      - ./scripts/audit-session-artifacts.sh

  clean:branches:
    desc: "Delete local branches only on positive merge evidence (dry run; 'task clean:branches -- --delete' to act)"
    cmds:
      - ./scripts/clean-branches.sh {{.CLI_ARGS}}

  clean:remote-refs:
    desc: Prune remote-tracking refs whose remote branch is gone, on every remote (git fetch --all --prune)
    cmds:
      - git fetch --all --prune

  clean:worktree-records:
    desc: Prune stale worktree admin records only — pins a detached commit before its record goes (human settles the pin); never removes a worktree directory
    cmds:
      - ./scripts/clean-worktree-records.sh

  # ── Status ─────────────────────────────────────────────────────
  status:
    desc: Project status dashboard
    interactive: true
    cmds:
      - ./scripts/status.sh

  status:git:
    desc: Git status section
    interactive: true
    cmds:
      - ./scripts/status.sh git

  status:gh:
    desc: GitHub status section
    interactive: true
    cmds:
      - ./scripts/status.sh gh

  status:creds:
    desc: Credential section (gh, Codex, Claude Code logins + gh token scopes — local probes plus one bounded scope check; STATUS_NO_NETWORK=1 skips it)
    interactive: true
    cmds:
      - ./scripts/status.sh creds

  status:code:
    desc: Codebase stats section
    interactive: true
    cmds:
      - ./scripts/status.sh code

  status:env:
    desc: Environment info section
    interactive: true
    cmds:
      - ./scripts/status.sh env

  status:image:
    desc: Warn if the container's image-baked config has drifted from the checkout (silent when fresh)
    cmds:
      - bash .devcontainer/scripts/check-image-staleness.sh

  status:setup:
    desc: Setup completeness audit (GitHub, toolchain, devcontainer, dev env)
    interactive: true
    cmds:
      - ./scripts/status.sh setup

  # ── Utilities ──────────────────────────────────────────────────
  util:bunch-add:
    desc: Scaffold the Bunch launcher in .meta (mirrors what the template generates)
    cmds:
      - ./scripts/meta-create.sh bunch 'Harmon DevKit' 'harmon-devkit' '~/git'

  util:bunch-install:
    desc: Move the Bunch file to iCloud and replace it with a symlink (macOS)
    cmds:
      - ./scripts/meta-install.sh bunch 'Harmon DevKit' '~/Library/Mobile Documents/com~apple~CloudDocs/Bunches'

  util:obsidian-add:
    desc: Scaffold the Obsidian project note in .meta (mirrors what the template generates)
    cmds:
      - ./scripts/meta-create.sh obsidian 'Harmon DevKit' 'Evan Harmon'

  util:obsidian-install:
    desc: Move the Obsidian note to the vault and replace it with a symlink (macOS)
    cmds:
      - ./scripts/meta-install.sh obsidian 'Harmon DevKit' '~/Local/Memex/Professional'