taskforce-loop-engineering 0.7.0

package/skills/taskforce-loop-engineering/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: "taskforce-loop-engineering"
+description: "Durable explicit task/project loops with verification, revisions, live progress, and governed completion."
+---
+
+# Taskforce Loop Engineering
+
+Use this skill only when the user explicitly invokes Loop Engineering, says `走 loop`, `loop engineering`, `丢进 Ironman loop`, `loop Ironman`, `task-runner`, names a loop queue, or asks to operate an existing loop.
+
+Do not route ordinary chat, research, explanations, or simple direct tasks into a loop unless the user explicitly invokes it.
+
+## Conversation Contract
+
+Interpret explicit loop language as follows:
+
+- `走 loop：<task>`: enqueue and immediately execute one runner tick with notification.
+- `走 loop 并立刻执行`: synonym for the default above.
+- `走 loop，只入队`, `只排队`, `暂不执行`, or `不立即执行`: enqueue without starting a tick.
+- `继续当前 loop，补充要求：…`: amend the active task in place. Preserve the task id and worker session, write a versioned amendment, update the task contract/dev plan/acceptance plan, and require the worker to reread the latest amendment before checkpoints and completion.
+- A new explicit `走 loop` request while another task is active is a correction/replacement, not ordinary backlog. Supersede the active task at a safe boundary, retain its evidence and lineage, then start the replacement after the lock is released.
+- Status, progress, evidence, or failure questions are read-only and must not start another tick unless the user explicitly asks to continue/run.
+
+In this workspace, the default queue is `ironman-task-runner` when no queue is named. Use the installed workspace wrapper when present:
+
+```bash
+node scripts/loops/ironman-task-runner.mjs route --message "<original user message>" --confirm-execute [source options]
+node scripts/loops/ironman-task-runner.mjs run-once --notify
+node scripts/loops/ironman-task-runner.mjs status --json
+node scripts/loops/ironman-task-runner.mjs peek --json
+```
+
+Pass the original request faithfully. Preserve source channel, target, account, message id, and reply-to metadata so progress, human gates, and terminal results return to the originating conversation. Missing delivery routing must fail closed.
+
+## Task vs Project Classification
+
+Classify scope before enqueueing.
+
+### Scoped task
+
+A bounded change, diagnosis, review, or deliverable with a clear local acceptance target can use one task contract.
+
+### Project-level objective
+
+Treat a request as project-level when the user asks to build/develop/finish a complete product or system, achieve an overall outcome, or otherwise describes a multi-milestone terminal goal.
+
+For a project-level objective:
+
+1. Run project intake and create a project spec.
+2. Write an explicit terminal-state/completion contract.
+3. Build a complete backlog covering every requirement and known acceptance dimension.
+4. Link queue tasks to the project backlog and terminal contract.
+5. Continue through implementation, verification, revisions, and the next actionable backlog item within the authorized safety boundary.
+6. Stop only when total project acceptance passes, or a genuine human authorization/product decision/external-state blocker prevents meaningful progress.
+
+Never silently narrow a complete-project request into “first milestone” and call that the Loop complete. A single queue task or milestone may be complete while the project remains active.
+
+Recommended commands:
+
+```bash
+loop-engineering project-intake --root <workspace> --name <project> --brief "<full brief>" --type auto
+loop-engineering project-plan --root <workspace> --project <project>
+loop-engineering project-status --root <workspace> --project <project>
+```
+
+The project completion contract must contain:
+
+- terminal user-visible outcome;
+- in-scope and explicitly out-of-scope capabilities;
+- complete requirement/backlog mapping;
+- acceptance checks and evidence locations;
+- operational/security/data/deployment requirements when relevant;
+- unresolved decisions and required authority;
+- a rule that milestone completion cannot satisfy project completion;
+- final acceptance status with unmet items and blockers.
+
+If implementation reveals missing work, amend the project backlog/contract before continuing. Do not redefine the terminal goal downward to fit completed work.
+
+## Completion Semantics
+
+Use precise language:
+
+- `阶段完成` or `任务完成`: one task/milestone passed its own acceptance checks.
+- `项目完成` or `Loop 跑完`: only when the project completion contract is fully accepted and no required work remains.
+- `blocked`: only for a concrete blocker requiring human authority/input or an external state change, with evidence and a specific unblock request.
+- `needs_revision`: acceptance found actionable gaps; create a changed-strategy revision rather than claiming completion.
+- `superseded`: a newer explicit loop request replaced the task; preserve lineage and evidence.
+
+Final reporting for project work must always state both task/milestone status and total-project status.
+
+## Safety and Authority
+
+Loop invocation authorizes the requested workflow, not unlimited external action.
+
+Require separate explicit confirmation for:
+
+- external messages, publication, social posting, or outreach;
+- destructive deletion or difficult-to-recover changes;
+- production configuration/deployment changes not already clearly requested;
+- credential creation/change/exposure;
+- paid model/API usage beyond an established budget;
+- memory deletion or migration;
+- device/process instrumentation such as `frida`, `tcpdump`, `adb`, `mitmproxy`, hooks, attach/spawn, decrypt, `su`, `kill`, or `pkill`.
+
+Human permission prompts and missing authorization are stop conditions, not retryable failures. `INSTALL_FAILED_USER_RESTRICTED`, device unauthorized, permission denied, and equivalent states require a concrete human-action gate.
+
+Timeouts must terminate the spawned process group. After instrumentation timeouts, verify that no child instrumentation/proxy process remains.
+
+## Operating Flow
+
+1. Read existing project docs, loop configs, queue state, and relevant dirty worktree state.
+2. Classify task vs project and define the correct contract before execution.
+3. Use `route-message` or the installed conversation wrapper to preserve source metadata and apply immediate/queue-only/amend/supersede semantics.
+4. Run preflight before mutable work.
+5. Execute one bounded tick or the project’s next actionable backlog item.
+6. Emit ordered progress: planning, preflight, worker start, checkpoints, verification, acceptance, final judgement.
+7. Inspect run artifacts; never infer success only from dispatcher exit code.
+8. If acceptance fails, write a revision request with changed diagnosis/tactic/evidence/verification.
+9. Run `doctor` after configuration or queue changes.
+10. For projects, re-read project status and completion contract, then automatically advance to the next safe actionable item.
+11. Report terminal status with evidence, unmet items, blockers, and next action.
+
+Do not add cron/timers until one manual tick passes.
+
+## Core CLI
+
+Prefer the installed CLI:
+
+```bash
+loop-engineering verify --root <workspace>
+loop-engineering doctor --root <workspace> [--json]
+loop-engineering summarize --root <workspace> --limit 20
+loop-engineering route-message --root <workspace> --message "<message>" --queue <queue> --route --confirm-execute [--supersede-active | --amend-active] [source options]
+loop-engineering queue-status --root <workspace> --queue <queue>
+loop-engineering queue-peek --root <workspace> --queue <queue>
+loop-engineering run-queue --root <workspace> --config configs/loops/queues/<queue>.json
+loop-engineering queue-revision-next --root <workspace> --queue <queue> --task-id <id>
+loop-engineering queue-lineage --root <workspace> --queue <queue> --task-id <id>
+loop-engineering queue-lineage-bundle --root <workspace> --queue <queue> --task-id <id>
+loop-engineering queue-human-decision --root <workspace> --queue <queue> --task-id <id> --decision approve|request_changes|reject
+loop-engineering queue-human-input-resolve --root <workspace> --queue <queue> --gate-id <task:checkpoint> --input "<response>"
+loop-engineering queue-terminal-notify --root <workspace> --queue <queue> (--notify-command "<command>" | --dry-run)
+loop-engineering queue-human-input-notify --root <workspace> --queue <queue> (--notify-command "<command>" | --dry-run)
+```
+
+If the package is available only in the workspace:
+
+```bash
+node packages/loop-engineering/bin/loop-engineering.mjs <command>
+```
+
+Use `run-queue-drain` only when batch draining is explicitly intended. Conversation routing normally runs one task/tick and uses supersede/amend behavior.
+
+## Revision Discipline
+
+A dispatcher-successful run is not automatically accepted. Inspect `final_judgement.json`, acceptance reviews, checkpoints, and verification evidence.
+
+When acceptance needs changes:
+
+- mark `needs_revision`;
+- retain the failed source task;
+- use `queue-revision-next`;
+- require a changed diagnosis, implementation tactic, evidence source, or verification step;
+- inspect lineage before forcing repeated attempts.
+
+Default revision policy may stop after three rounds, two repeated goal signatures, or repeated unchanged strategy. `--force` requires an explicit human override after lineage review.
+
+## Code Work
+
+For L2 code-changing tasks, prefer isolated worktrees. The runner prepares reviewable local changes and verification evidence; it does not implicitly commit, push, publish, deploy, merge, or delete branches.
+
+Safe review flow:
+
+```bash
+loop-engineering code-task-status --root <workspace> --queue <queue>
+loop-engineering code-worktree-inspect --root <workspace> --queue <queue> --task-id <id>
+loop-engineering code-worktree-diff --root <workspace> --queue <queue> --task-id <id>
+loop-engineering code-task-autoflow --root <workspace> --queue <queue> --task-id <id> --until closeout
+loop-engineering code-patch-apply-plan --root <workspace> --patch <patch> --json
+```
+
+Applying a patch and cleaning a worktree require their explicit confirmation flags. Preserve unrelated user changes and never treat a dirty worktree as disposable.
+
+## Observability and Artifacts
+
+Use read-only diagnostics before mutation:
+
+```bash
+loop-engineering doctor --root <workspace> --json
+loop-engineering summarize --root <workspace> --queue <queue> --limit 20
+loop-engineering project-status --root <workspace> --project <project>
+```
+
+Task artifacts live under:
+
+```text
+runtime/loops/<queue>/tasks/<task_id>/
+runtime/loops/<queue>/runs/
+runtime/loops/<queue>/{inbox,active,done,failed,canceled}/
+```
+
+Expected evidence includes `task_contract.json`, `acceptance_plan.json`, `dev_plan.json`, checkpoints, acceptance reviews, `final_judgement.json`, revision requests, amendments, supersede markers, progress notifications, and lineage bundles.
+
+Project artifacts live under:
+
+```text
+configs/loops/projects/<project>.json
+runtime/loops/projects/<project>/
+```
+
+Summaries must cite the latest run/task/project evidence, verification performed, unmet checks, and blocker reason. Keep raw noisy logs in runtime artifacts; durable memory receives only distilled decisions, recurring failures, accepted safety rules, and verified completion facts.
+
+## Scheduler Policy
+
+Use scheduler ticks only after manual verification. Adaptive schedules may speed up with successful queued work and back off on empty queues, failures, long runs, or human gates.
+
+Progress notification must be scoped and idempotent. Report failures, human gates, status changes, and terminal completion promptly; throttle routine progress and idle updates.
+
+## Final Checklist
+
+Before saying a loop is finished, verify:
+
+- Was this a scoped task or project-level objective?
+- Is the correct contract present and current?
+- Were all amendments applied?
+- Did verification and acceptance pass?
+- Is `final_judgement.json` acceptable?
+- For a project, are all completion-contract items accepted and the backlog terminal?
+- Are there any unmet requirements, pending revisions, gates, or external-write confirmations?
+- Does the report distinguish milestone status from total-project status?
+- Are evidence paths and next actions included?
+
+If any project requirement remains, report a phase/task result and continue with the next authorized item; do not claim the project or Loop is complete.

package/skills/taskforce-loop-engineering/references/npm-package.md

@@ -0,0 +1,117 @@
+# npm Package
+
+Package name: `taskforce-loop-engineering`
+Version: `0.7.0`
+
+Install from npm:
+
+```bash
+npm install -g taskforce-loop-engineering
+```
+
+Installed commands:
+
+```bash
+loop-engineering init --root /path/to/workspace
+loop-engineering verify --root /path/to/workspace
+loop-engineering run --root /path/to/workspace --config configs/loops/<id>.json
+loop-engineering status --root /path/to/workspace
+loop-engineering doctor --root /path/to/workspace
+loop-engineering summarize --root /path/to/workspace --limit 20
+loop-engineering project-intake --root /path/to/workspace --name <project> --brief "Project brief"
+loop-engineering project-plan --root /path/to/workspace --project <project>
+loop-engineering project-status --root /path/to/workspace --project <project>
+loop-engineering enqueue --root /path/to/workspace --queue <queue> --title "Title" --task "Task body"
+loop-engineering queue-init --root /path/to/workspace --queue <queue>
+loop-engineering code-queue-init --root /path/to/workspace --queue <queue>
+loop-engineering run-queue --root /path/to/workspace --config configs/loops/queues/<queue>.json
+loop-engineering queue-status --root /path/to/workspace --queue <queue>
+loop-engineering queue-scheduler-tick --root /path/to/workspace --config configs/loops/queues/<queue>.json
+loop-engineering queue-peek --root /path/to/workspace --queue <queue>
+loop-engineering queue-cancel --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering queue-requeue --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering queue-revision-next --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering queue-lineage --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering queue-lineage-bundle --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering queue-human-decision --root /path/to/workspace --queue <queue> --task-id <id> --decision approve|request_changes|reject
+loop-engineering code-worktree-list --root /path/to/workspace --queue <queue>
+loop-engineering code-worktree-inspect --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering code-worktree-diff --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering code-worktree-export --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering code-patch-verify --root /path/to/workspace --patch runtime/loops/<queue>/patches/<id>.patch
+loop-engineering code-patch-apply-plan --root /path/to/workspace --patch runtime/loops/<queue>/patches/<id>.patch
+loop-engineering code-patch-apply --root /path/to/workspace --patch runtime/loops/<queue>/patches/<id>.patch --confirm-apply
+loop-engineering code-review-bundle --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering code-task-closeout --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering code-task-autoflow --root /path/to/workspace --queue <queue> --task-id <id>
+loop-engineering code-task-autoflow --root /path/to/workspace --queue <queue> --all-actionable --until closeout
+loop-engineering code-task-finish --root /path/to/workspace --queue <queue> --task-id <id> --confirm-apply --confirm-cleanup
+loop-engineering code-task-run --root /path/to/workspace --queue <queue> --title "Title" --task "Task body" --confirm-apply --confirm-cleanup
+loop-engineering code-task-dashboard --root /path/to/workspace --queue <queue>
+loop-engineering code-task-status --root /path/to/workspace --queue <queue>
+loop-engineering code-worktree-cleanup-plan --root /path/to/workspace --queue <queue>
+loop-engineering code-worktree-cleanup --root /path/to/workspace --queue <queue> --confirm-cleanup
+agent-loop status --root /path/to/workspace
+LOOP_WORKDIR=/path/to/workspace run-loop-cron.sh configs/loops/<id>.json
+```
+
+`code-queue-init` creates an L2 assisted code queue config. Each task runs in
+an isolated git worktree and branch, then runs configured verification commands
+and records diff/status summaries. It does not push, merge, or delete
+worktrees.
+
+`queue-scheduler-tick` is the adaptive queue cadence command. It treats 10
+minutes as the bootstrap interval, writes live cadence state to
+`runtime/loops/<queue>/scheduler/state.json`, speeds up after successful work
+when tasks remain queued, and backs off for empty queues, failures, human gates,
+or long runs.
+
+`project-intake` is the high-level entry for fuzzy project briefs. It writes a
+deterministic project spec draft, human-readable plan, action policy, checks,
+and initial backlog under `runtime/loops/projects/<project>/` without enqueuing
+or executing work. `project-plan` solidifies that draft into
+`configs/loops/projects/<project>.json`, generates the queue config, and writes
+the initial backlog artifact. `project-status` aggregates the project queues
+without changing queue state.
+
+`code-worktree-list`, `code-worktree-inspect`, `code-worktree-diff`,
+`code-worktree-export`, `code-patch-verify`, `code-patch-apply-plan`,
+`code-patch-apply`, `code-review-bundle`, `code-task-closeout`,
+`code-task-autoflow`, `code-task-finish`, `code-task-run`, `code-task-dashboard`,
+`code-task-status`, `code-worktree-cleanup-plan`, and
+`code-worktree-cleanup`
+are review and
+handoff commands for code queues.
+They report branch, path, dirty status, verification status, diff summaries,
+patch output, exported patch artifacts, untracked files, whether an exported
+patch still passes `git apply --check --binary`, whether it is safe to apply,
+review bundle files, which retained worktrees are cleanup candidates, and
+confirmation-gated cleanup of reviewed worktrees. Closeout artifacts summarize
+the task's final review, patch, apply-plan, cleanup, and next-action state.
+Status ledgers summarize task-level queue, worktree, patch, review, closeout,
+cleanup, and next-action state without writing artifacts.
+Dashboards summarize queue counts, task counts, next-action counts,
+cleanup/orphan state, priority tasks, and recommended commands without writing
+artifacts.
+Finish applies one reviewed patch to the main workspace and removes that one
+reviewed worktree only after default patch, review, and closeout artifacts are
+present and both `--confirm-apply` and `--confirm-cleanup` are supplied; it
+also writes a finish artifact. Status and dashboard views read finish artifacts:
+tasks ready to land report `ready_to_finish`, and successfully finished tasks
+report `landed` with finish status, patch-applied, and worktree-cleaned fields.
+Task run enqueues one code task, processes one worktree queue run, runs
+autoflow through closeout, finishes the reviewed task, and reruns configured
+worktree verification commands in the main workspace.
+Autoflow runs export, patch verification, apply-plan, and review generation by
+default, and can also write closeout artifacts with `--until closeout`; it skips
+existing artifacts unless `--force` is supplied. Batch autoflow with
+`--all-actionable` reads the status ledger and runs the same safe flow across
+tasks that need export, review, or closeout artifacts.
+Actual patch application requires `--confirm-apply` and still does not stage,
+commit, push, merge, or change queue state.
+Actual worktree cleanup requires `--confirm-cleanup`; dirty worktrees require a
+default exported patch, passing patch verification, and an existing review
+bundle.
+
+The package contains `bin/`, `lib/`, `scripts/`, `templates/`, and
+`skills/taskforce-loop-engineering/`.

package/templates/code-worktree-queue.json

@@ -0,0 +1,41 @@
+{
+  "queue": "code-tasks",
+  "description": "L2 assisted code task queue. Each task runs in an isolated git worktree and records verification plus diff summaries. It never pushes, merges, or deletes worktrees.",
+  "dispatcher": "node scripts/dispatch-code-task.mjs",
+  "preflightConfig": "configs/loops/workspace-health.json",
+  "timeoutMs": 1800000,
+  "leaseMs": 1860000,
+  "staleActiveMs": 3600000,
+  "retry": {
+    "maxAttempts": 1,
+    "retryDelayMs": 0,
+    "retryExitCodes": [
+      1
+    ],
+    "requiresHumanActionPatterns": [
+      "INSTALL_FAILED_USER_RESTRICTED",
+      "device unauthorized",
+      "no devices/emulators found",
+      "Permission denied",
+      "Operation not permitted",
+      "requires human",
+      "需要人工",
+      "权限未开"
+    ]
+  },
+  "revisionPolicy": {
+    "enabled": true,
+    "maxRevisionRounds": 3,
+    "sameFailureThreshold": 2,
+    "requireStrategyChange": true
+  },
+  "worktree": {
+    "enabled": true,
+    "baseDir": "runtime/loops/code-tasks/worktrees",
+    "branchPrefix": "loop/code-tasks",
+    "verifyCommands": [
+      "npm test"
+    ],
+    "keepOnSuccess": true
+  }
+}

package/templates/queue-runner.json

@@ -0,0 +1,52 @@
+{
+  "queue": "agent-tasks",
+  "description": "Generic queue runner config. Keep dispatcher local to the target workspace.",
+  "dispatcher": "node scripts/dispatch-task.mjs",
+  "preflightConfig": "configs/loops/workspace-health.json",
+  "timeoutMs": 1800000,
+  "leaseMs": 1860000,
+  "staleActiveMs": 3600000,
+  "scheduler": {
+    "initialInterval": "10m",
+    "minInterval": "1m",
+    "maxInterval": "4h",
+    "speedupFactor": 0.5,
+    "backoffFactor": 2,
+    "idleBackoffFactor": 2,
+    "humanGateBackoffFactor": 3,
+    "longRunHeadroomFactor": 1.25,
+    "jitter": "30s",
+    "progressReport": {
+      "enabled": true,
+      "minInterval": "30m",
+      "idleInterval": "4h",
+      "notifyOnFailure": true,
+      "notifyOnHumanGate": true,
+      "notifyOnCompletion": true,
+      "notifyOnStatusChange": true
+    }
+  },
+  "retry": {
+    "maxAttempts": 1,
+    "retryDelayMs": 0,
+    "retryExitCodes": [
+      1
+    ],
+    "requiresHumanActionPatterns": [
+      "INSTALL_FAILED_USER_RESTRICTED",
+      "device unauthorized",
+      "no devices/emulators found",
+      "Permission denied",
+      "Operation not permitted",
+      "requires human",
+      "需要人工",
+      "权限未开"
+    ]
+  },
+  "revisionPolicy": {
+    "enabled": true,
+    "maxRevisionRounds": 3,
+    "sameFailureThreshold": 2,
+    "requireStrategyChange": true
+  }
+}

package/templates/workspace-health.json

@@ -0,0 +1,35 @@
+{
+  "id": "workspace-health",
+  "goal": "Keep this workspace loop-ready and detect obvious drift.",
+  "level": "L1",
+  "mode": "report-only",
+  "maxRuntimeMs": 120000,
+  "description": "A safe first loop: local read-only checks plus durable run ledger.",
+  "humanGates": [
+    "source edits",
+    "external messages",
+    "destructive commands",
+    "production config changes"
+  ],
+  "breaker": {
+    "maxConsecutiveFailures": 3,
+    "sameFailureThreshold": 2
+  },
+  "checks": [
+    {
+      "id": "git-status",
+      "type": "command",
+      "cmd": "git status --short",
+      "expectExitCode": 0,
+      "timeoutMs": 10000,
+      "allowNonEmptyOutput": true
+    },
+    {
+      "id": "loop-config-dir",
+      "type": "files",
+      "paths": [
+        "configs/loops"
+      ]
+    }
+  ]
+}