io.github.joinwell52-AI/fcop

Approve lifecycle stage: ``review`` → ``done`` (v3 directory move). **Lifecycle approval ≠ business acceptance (Rule 0.a.3).** Typically ``ADMIN`` / reviewer after inspecting the paired ``REPORT-*``. Does **not** auto-call ``archive_task`` or mark blocked upstream work as externally delivered. File ops: ``mv _lifecycle/review/TASK-* _lifecycle/done/``. On v2 projects this is a no-op.

Archive a task after governance acceptance (v3: ``_lifecycle/archive/``; v2: ``log/``). **Governance action (Rule 0.a.5).** **Not** Hot Path step 4 for executors. Default actor is ``leader`` or ``ADMIN`` after accepting the paired ``REPORT-*``. Executors must **not** call this unless the task body or ``ADMIN`` explicitly authorises archive-on-completion. **Authorization:** subtasks — direct upstream or governance runtime; main tasks — ``ADMIN`` or the main-task owner only. Archive **≠** business completion (Rule 0.a.3). Does **not** run automatically after ``write_report`` or ``finish_task``. File ops: ``mv`` task (+ matched reports via ``references``) to ``_lifecycle/archive/`` or ``fcop/log/``.

Deep-history cold storage after governance archive (v3 only). Moves a task already in ``_lifecycle/archive/`` (or legacy ``log/``) into ``history/YYYY-MM-DD/<task-stem>/`` with its reports — immutable, date-sharded retention. **Not** business acceptance and **not** a substitute for ``write_report`` or authorised ``archive_task``. Call ``archive_task`` first (v3: ``done/`` → ``archive/``). Main-task deep archive requires the same governance authorization as ``archive_task`` (Rule 0.a.5). File ops: ``mv _lifecycle/archive/TASK-* history/YYYY-MM-DD/<stem>/``.

Migrate **all** tasks from ``_lifecycle/archive/`` into the deep history archive. This is a convenience migration tool. It iterates every task in ``_lifecycle/archive/`` and calls :func:`archive_to_history` for each one, moving each task together with its associated reports into ``history/YYYY-MM-DD/<task-stem>/``. Useful when: - A project is being upgraded and existing archived tasks need to be moved into the new date-sharded history structure. - You have just finished a manual archiving session and want to flush everything from ``_lifecycle/archive/`` into ``history/`` in one step. The ``history/`` directory is created automatically if it does not yet exist.

Compare the installed fcop-mcp version to the latest on PyPI. Prints the local version, the latest PyPI version (if reachable), and a one-line verdict. Does NOT install anything — call ``upgrade_fcop`` afterwards for that.

Claim a task: ``inbox`` → ``active`` (v3 Hot Path start). **Hot Path step 1 (v3):** call before executing on an inbox task. Always follow with ``read_task`` + ``inspect_task``. Does **not** read the task body, write a report, or imply business completion. File ops: ``mv _lifecycle/inbox/TASK-* _lifecycle/active/`` + append ``claim_task`` transition event to frontmatter. On v2 projects this is a no-op with an informational message.

Create a Branch through Core T1; unavailable family digest is null with reasons.

Create an FCoP project with a custom roster of roles. Role codes can be anything — they become part of task filenames, e.g. ``TASK-20260423-001-BOSS-to-CODER.md``. Use ``validate_team_config`` first to catch illegal role codes without writing anything. Since 3.0.2 fresh init produces the **v3 topology** (per spec §1.1): ``fcop/_lifecycle/{inbox,active,review,done,archive}/`` plus retained ``reports/`` / ``issues/`` / ``shared/``. Superseded v2 buckets (``tasks/``, ``log/``) are no longer created on fresh init. Custom teams have **no bundled three-layer docs**, so ``fcop/shared/`` is left empty (apart from the project's own ``shared/README.md``). The recommended next step is to read the closest preset (``fcop://teams/<closest-preset>`` — see the ``teams/_data/README.md`` "Custom teams" section) and hand-author your own ``TEAM-README.md`` / ``TEAM-ROLES.md`` / ``TEAM-OPERATING-RULES.md`` + ``roles/{ROLE}.md`` based on it. The other init artifacts are deposited as usual: ``fcop/fcop.json``, ``LETTER-TO-ADMIN.md``, ``workspace/README.md``, plus the protocol rule files at ``.cursor/rules/*.mdc`` + ``AGENTS.md`` + ``CLAUDE.md`` (existing copies archived under ``.fcop/migrations/``).

Create a new task and place it in the inbox (v3) or tasks folder (v2). This is the canonical **FCoP v3 spec §8 L1** entry-point for task creation — functionally identical to :func:`write_task` but named to match the spec. In a v3 project the task lands in ``_lifecycle/inbox/`` so the recipient can ``claim_task`` it.

Deploy the three-layer team documentation into ``shared/``. Writes ``TEAM-README.md`` (bilingual), ``TEAM-ROLES.md``, ``TEAM-OPERATING-RULES.md``, and per-role bios under ``docs/agents/shared/`` (both ``zh`` and ``en`` variants). When ``force=True`` (default) existing files are archived under ``.fcop/migrations/<timestamp>/shared/`` before being overwritten, so the action is safely reversible. When ``force=False`` existing files are left untouched and reported as skipped.

Pressure valve for agents who disagree with the current FCoP protocol. Writes a timestamped markdown file under ``.fcop/proposals/`` that ADMIN can review later. **This is the ONLY sanctioned way for an agent to push back on the rule files** (``fcop-rules.mdc`` / ``fcop-protocol.mdc``). Agents MUST NOT edit the rule files themselves; those are ADMIN's source of truth. Works before ``init_project`` / ``init_solo`` too — suggestions just land under the project root even if the project is not yet fully initialized.

**协议体检工具（ADR-0032）** — deep compliance scan, not Hot Path. 与 ``fcop_check`` 的区别： - ``fcop_check`` — 日常轻量自检（working-tree drift + session/role 冲突）； **不**在每次 ``write_report`` 后自动调用 - ``fcop_audit`` — 一次性深度体检（协议合规度全量扫描 + 整改方案）； **不**替代协作闭环，**不**等于业务验收或 ``archive_task`` **Not lifecycle closure:** passing audit does not archive tasks or accept reports. Execution Block commands are **suggestions** only. 三个 scope： - ``new`` : 新项目验收 — 协议文件是否完整部署 - ``upgrade`` : 版本升级后验收 — 规则版本 / 文档是否同步 - ``takeover`` : 老 non-fcop 项目首次引入 fcop — 全量合规扫描（含 6 类盲区） - ``auto`` : 自动推断（推荐） 产出物：``fcop/shared/INSPECTION-{date}-{NNN}-{scope}.md`` 报告含 **Execution Block**：每条违规附带可直接复制的整改命令、执行人、 Tier 优先级和回滚方式。

**FCoP audit.** Cross-reference git working tree + frontmatter against the FCoP ledger. Two independent post-hoc audits, both new in 0.7.1 (``fcop_protocol_version: 1.6.0``): 1. **Rule 0.a.1 drift** — files in ``git status --porcelain`` that live outside the FCoP ledger (``_lifecycle/`` or legacy ``docs/agents/{tasks,reports,issues,log}/``) are work performed without the task→execute/dispatch→report collaboration cycle. Missing ``archive_task`` on an open task is **not** drift by itself — executors default to **not** archiving (Rule 0.a.5). 2. **Rule 1 sub-agent role impersonation** — any ``session_id`` that signed files under more than one role code. One session = one role binding for life; cross-role usage is direct evidence that a sub-agent self-claimed a role its parent session was not assigned. This tool is **detection, not prevention**. It surfaces the evidence; the protocol-mandated response is for ADMIN to file an ISSUE-* and decide handoff / co-review / distinct-role per Rule 1, just as for the ``role_occupancy`` table in ``fcop_report()``. **Not Hot Path auto-run:** do **not** invoke after every ``write_report`` by default. For one-shot deep compliance scans use ``fcop_audit`` instead (Rule 9.6). Decomposes to filesystem operations: - ``git status --porcelain -z`` from the project root. - Walk every ``TASK-*.md`` / ``REPORT-*.md`` / ``ISSUE-*.md`` in ``docs/agents/{tasks,reports,issues}`` + ``docs/agents/log/*``. - Read frontmatter only; never task bodies.

**ADMIN / Governance Observer only.** Manually file a governance alert. Use when you (as ADMIN or an authorized governance observer) detect a governance gap that automated scanning has not yet captured. Creates a new ALERT-*.md file in fcop/alerts/.

**ADMIN Governance Alert Inbox.** List governance alerts from fcop/alerts/. Alerts are written automatically by `fcop_check()` when governance drift signals are detected (ADR-0031). Each alert is a structured ALERT-*.md file with severity (high/medium/low), type, and a summary of the governance gap. This is the ADMIN's "red dot" — run this to see what governance gaps the system has surfaced, without needing to manually patrol logs.

**FCoP Rule 0 — first tool call of every new session, also the general project-status report.** Returns one of two reports plus a versions block + optional drift warning (ADR-0006): 1. **Initialization report** when ``docs/agents/fcop.json`` is missing. Lists the detected project path + resolution source and the available init modes (Solo / preset teams / custom). Does NOT ask for a role assignment — there's no team yet. 2. **UNBOUND report** when the project is initialized but this session has no role. Shows project state and a role-assignment template for ADMIN to fill in. In both cases the ``[Versions]`` block reports installed ``fcop-mcp`` / ``fcop`` versions plus the project-local vs packaged versions of the protocol rules. When the project's ``.cursor/rules/*.mdc`` is older than the wheel-bundled copy a drift warning is appended prompting ADMIN to run ``redeploy_rules()``. Agents must NOT invoke redeploy themselves. While UNBOUND (or uninitialized) the agent MUST NOT read task bodies, write any files (except via the explicit init tools), or claim a role from context clues. The initialized report includes the **3.2.5 collaboration cycle** (Rule 0.a.1–0.a.6): ``write_task`` → execute/dispatch → ``write_report`` → wait / authorised ``archive_task``. It does **not** deep-audit the project — use ``fcop_check`` (lightweight) or ``fcop_audit`` (deep) when ADMIN requests. .. note:: This tool replaced ``unbound_report`` in 0.6.3. The deprecated alias was removed in 0.7.0; existing system prompts and ``LETTER-TO-ADMIN.md`` references that still reference ``unbound_report`` must switch to ``fcop_report``.

Move lifecycle stage: ``active`` → ``done`` (v3 directory move only). This is a **lifecycle directory move** — it does **not** replace ``write_report``, upstream acceptance, or authorised ``archive_task`` (Rules 0.a.3, 0.a.5, 0.a.6). **Rule 0.a.6:** after reporting, **stop and wait** for review; do **not** chain ``finish_task`` in the same turn as ``write_report`` or treat it as "business complete". File ops: ``mv _lifecycle/active/TASK-* _lifecycle/done/``. On v2 projects this is a no-op.

List bundled preset teams and their role rosters. Useful before ``init_project`` to pick a template that fits the work. Each team ships with its own three-layer documentation (``TEAM-README.md`` + ``TEAM-ROLES.md`` + ``TEAM-OPERATING-RULES.md``) that gets deployed into ``docs/agents/shared/`` during ``init_project``.

**FCoP governance summary.** Return aggregate statistics from the governance event log: total calls by risk level, most active tools, and any CRITICAL_TAG events that should be reconciled with Tasks and Reviews. Use as a quick health check: CRITICAL_TAG events without corresponding Task + Review coverage are governance gaps that require ADMIN attention. Version policy: OPTIONAL_GOVERNANCE_READ. Legacy prose above applies to v3. v4 dispatch uses public Project operations and structured results; actor is not authority.

Return a concise status snapshot of the current project. Shows whether the project is initialized, which team / roster is loaded, how many open tasks / reports / issues are on disk, and the five most recent activity entries (sorted newest first).

Initialize an FCoP project with a bundled preset team. Since 3.0.2 a fresh init produces the **v3 topology** (per spec §1.1): ``fcop/_lifecycle/{inbox,active,review,done,archive}/`` plus the retained v2 buckets ``reports/`` / ``issues/`` / ``shared/``. The superseded v2 buckets ``tasks/`` and ``log/`` are no longer created on fresh init (use ``python -m fcop migrate --to-v3`` to upgrade an existing v2 project). Writes ``fcop/fcop.json``, deposits ``LETTER-TO-ADMIN.md`` under ``fcop/``, creates the ``workspace/`` cage with a starter README (per Rule 7.5), deploys the team's three-layer docs to ``fcop/shared/`` (TEAM-README / TEAM-ROLES / TEAM-OPERATING-RULES + ``roles/{ROLE}.md``, both zh and en), and (per ADR-0006) deploys the bundled protocol rules to **four** locations so any agent host sees them: ``.cursor/rules/fcop-rules.mdc``, ``.cursor/rules/fcop-protocol.mdc``, ``AGENTS.md``, and ``CLAUDE.md``. Existing copies are archived to ``.fcop/migrations/<timestamp>/`` before being overwritten.

Initialize an FCoP project in **Solo mode** (one AI, no dispatch). Solo mode is for projects where a single agent works directly with ADMIN. Rule 0.b still applies: the agent uses files to split itself into *proposer* and *reviewer*, even though there is no second role. Since 3.0.2 fresh init produces the **v3 topology** (per spec §1.1): ``fcop/_lifecycle/{inbox,active,review,done,archive}/`` plus retained ``reports/`` / ``issues/`` / ``shared/``. Superseded v2 buckets (``tasks/``, ``log/``) are no longer created on fresh init. Beyond ``fcop.json`` and the canonical directories, this also deposits ``fcop/LETTER-TO-ADMIN.md`` (the user manual), creates the ``workspace/`` cage with a starter README (per Rule 7.5), deploys the bundled solo three-layer docs (TEAM-README / TEAM-ROLES / TEAM-OPERATING-RULES + ``roles/ME.md``, both zh and en) to ``docs/agents/shared/``, and (per ADR-0006) drops the bundled protocol rules into ``.cursor/rules/*.mdc`` + ``AGENTS.md`` + ``CLAUDE.md``. Existing copies are archived under ``.fcop/migrations/<timestamp>/`` before being overwritten.

Read a canonical ordered family, precise REPORT heads, readiness and convergence facts.

Validate a task file against FCoP grammar (Hot Path pre-flight). Run **before executing** on a claimed/assigned task, alongside ``read_task``. Catches deterministic violations agents often miss (filename ``to-DEV`` vs frontmatter ``recipient: QA``, mistyped ``protocol``, missing required fields). ``PASS`` does **not** replace reading the task body for acceptance criteria. File ops: read filename + frontmatter and validate grammar only.

**FCoP governance audit.** Read the append-only governance event log. Returns recent tool-call intercept events recorded by the FCoPGovernanceMiddleware (ADR-0030-bis Layer 1). Use this to understand what actions agents have taken and their risk classification.

List the deep history archive. When *date* is supplied (``YYYY-MM-DD``) the tool lists every task entry stored under that date shard. When *date* is omitted it lists all available date shards (newest first).

List issues, optionally filtered.

List reports, optionally filtered.

List REVIEW files, optionally filtered.

List tasks, optionally filtered.

List all ``workspace/<slug>/`` subdirectories with their metadata. Picks up both workspaces created by ``new_workspace`` (they have a ``.workspace.json`` marker) and directories created by hand (shown with just the slug). Use for the at-a-glance "what's inside this project" view.

Record a human approval decision on a ``needs_human`` REVIEW file. Closes the escalation loop opened by ``write_review(decision='needs_human')``. Writes ``human_approval`` sub-structure into the REVIEW frontmatter and returns the updated review summary (per ADR-0026).

Core atomically materializes the caller's decision. Never chooses a winner or archives Root.

Create a workspace subdirectory under ``workspace/<slug>/``. ``workspace/<slug>/`` is FCoP's soft convention for the actual artifacts of a piece of work — code, scripts, data. Keeping those out of the project root prevents yesterday's mini-game from colliding with today's report generator. Idempotent: calling twice with the same slug updates the title / description but never wipes files you already dropped in the folder.

Read a task from the deep history archive. Searches ``history/`` for the task matching *task_id*. Providing *date* restricts the search to that date shard (much faster).

Read the full content of a report file.

Read the full content of a REVIEW file.

Read the full content of a task file (Hot Path pre-flight). **Before executing** on an assigned or claimed task, call this **together with** ``inspect_task`` (Rules 0.a.1 / 0.a.2). Do not mutate the workspace or dispatch from chat/memory alone. File ops: ``cat`` the file under ``_lifecycle/{stage}/TASK-*.md``, legacy ``fcop/tasks/``, or ``fcop/log/`` when archived.

**Legacy v1-v3 only; ADMIN-only.** Re-deploy legacy bundled rules. Declared FCoP 4.0 workspaces reject this tool with ``toolkit:OPERATION_NOT_IMPLEMENTED`` and zero writes, regardless of force/archive. Use package-owned rules and MCP resources for v4; project-root Host instruction files remain application-owned. On supported legacy workspaces only, writes :file:`fcop-rules.mdc` / :file:`fcop-protocol.mdc` to **four** locations so any agent host the project runs under sees the same rules: .. code-block:: text <root>/.cursor/rules/fcop-rules.mdc # Cursor IDE <root>/.cursor/rules/fcop-protocol.mdc # Cursor IDE <root>/AGENTS.md # Codex / Cursor / Devin / generic <root>/CLAUDE.md # Claude Code CLI For an explicitly maintained legacy workspace, run this after ``pip install -U fcop-mcp`` (or ``-U fcop``) to refresh on-disk copies to the newly packaged versions. ``fcop_report()`` shows when this is needed via the version drift warning. Per ADR-0006, agents must NOT invoke this tool themselves — only ADMIN does, explicitly.

Reject / recall: ``review`` → ``active`` (v3 rework loop). Returns the task to ``active/`` for revision after a ``REPORT-*`` or review finding (complements Rule 0.a.6 stop-and-wait). **Lifecycle only** — does not delete reports or auto-call ``archive_task``. File ops: ``mv _lifecycle/review/TASK-* _lifecycle/active/`` + append ``reject_task`` event. On v2 projects this is a no-op.

Request only v4 T6 done->active. Actor is audit data, never authority. The independent authorization and reopen REVIEW are validated and consumed by Project. Trusted evaluators can only be installed at server startup. Repeating the same formal request returns the Core's existing result.

Pin the project root for this MCP session. Useful when the MCP process was spawned with the wrong working directory — typical symptom: ``unbound_report`` shows a project path like ``C:\Users\<you>`` instead of the workspace you actually opened in Cursor. Calling this tool once re-binds every subsequent tool call to the given directory, **without** editing ``mcp.json`` or restarting Cursor. Safe to call while UNBOUND — re-pointing at a directory is not a role-claim and writes nothing. It only mutates in-process state.

Submit for review: ``active`` → ``review`` (v3 lifecycle directory move). **Lifecycle only (Rule 0.a.3).** Does **not** replace ``write_report``, upstream acceptance, or authorised ``archive_task``. Pair with a ``REPORT-*`` before or after submit as your team's operating rules require — this tool alone does not close business work. File ops: ``mv _lifecycle/active/TASK-* _lifecycle/review/``. On v2 projects this is a no-op.

Return the install-method-specific command to upgrade fcop-mcp. Does NOT run pip — MCP servers cannot safely upgrade themselves mid-process, and different install methods (``pip`` in a venv, ``pipx``, ``uvx``) need different commands. This tool prints the right incantation for the user to run in their own shell.

Dry-run validation for a custom team config. Use **before** ``create_custom_team`` to catch illegal role codes (Chinese characters, dashes, reserved names, duplicates) without writing anything to disk.

File an issue under ``docs/agents/issues/``.

Write a completion report for a task. Creates ``REPORT-<task_id>-{REPORTER}-to-{RECIPIENT}.md`` under ``docs/agents/reports/`` (v3: co-located under ``_lifecycle/``). The ``task_id`` is the canonical reference back to the source task. **Stop signal (Rule 0.a.6):** after this call, wait for upstream review / rework — do not keep editing artefacts, dispatch unrelated work, or call ``archive_task`` unless explicitly authorised. Does **not** trigger ``finish_task``, ``approve_task``, or ``archive_task`` automatically. ``status=blocked`` still leaves the task open for upstream action. File ops: write ``REPORT-*.md`` under ``fcop/reports/`` or co-located ``_lifecycle/`` stage.

Write a REVIEW file (governance-layer decision, per ADR-0017/0025).

Create a new task file (Cold Path dispatch or formal intake only). **Not Hot Path execution.** Use when ``ADMIN`` / ``leader`` assigns work, when Cold Path fan-out dispatches subtasks, or when you were explicitly told to land a formal task. Agents **must NOT** self-dispatch without an upstream requirement (Rule 0.a.2). Subtask linking: set ``thread_key`` for thread continuity; set ``parent`` to the upstream task ID (``parent:`` frontmatter — work derivation, distinct from ``references``). Do **not** emit ``parent_task_id`` as normative output (read-only legacy alias only). File ops: write ``TASK-*.md`` under ``_lifecycle/inbox/`` (v3) or ``fcop/tasks/`` (v2). Does **not** claim, finish, or archive. The library assigns a filename of the form ``TASK-YYYYMMDD-NNN-{SENDER}-to-{RECIPIENT}.md`` with FCoP-compliant YAML frontmatter + markdown body. In v3 the recipient ``claim_task``s from inbox.