> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase20-session06-file-mutation-core/tasks.md).

# Task Checklist

**Session ID**: `phase20-session06-file-mutation-core` **Total Tasks**: 22 **Estimated Duration**: 3.5-4 hours **Created**: 2026-06-28

***

Legend: `[x]` completed; `[ ]` pending; `[P]` parallelizable; `[SNNMM]` session ref; `TNNN` task ID.

***

## Setup (3 tasks)

* [x] T001 \[S2006] Verify Session 01 file-capability baseline, Session 05 phase sequence state, and current file-intent/executor posture (`.spec_system/specs/phase20-session01-truthful-capability-baseline/validation.md`)
* [x] T002 \[S2006] Create temp-directory acceptance coverage for mutation, rollback, conflict, stale hash, backup failure, path rejection, idempotency, and redaction before implementation (`apps/server/tests/fileMutationManager.test.ts`)
* [x] T003 \[S2006] Create protocol acceptance coverage for file mutation request/result metadata, rollback metadata, and blocked raw-field rejection (`packages/protocol/tests/fileMutation.test.ts`)

***

## Foundation (5 tasks)

* [x] T004 \[S2006] Add protocol file mutation operation, request, result, backup, rollback, and safe metadata contracts with schema-validated input and explicit error mapping (`packages/protocol/src/orchestrationCommandCenter.ts`)
* [x] T005 \[S2006] \[P] Add shared protocol tests for file mutation parsing, safe path labels, expected hash requirements, compact result metadata, and raw content/patch rejection (`packages/protocol/tests/fileMutation.test.ts`)
* [x] T006 \[S2006] Create `FileMutationManager` with injected workspace root, state root, file intent manager, command-center manager, clock, and filesystem dependencies (`apps/server/src/managers/fileMutationManager.ts`)
* [x] T007 \[S2006] Implement repo-relative path validation, realpath checks, symlink escape rejection, traversal rejection, URL-like input rejection, NUL rejection, and generated/ignored policy rejection (`apps/server/src/managers/fileMutationManager.ts`)
* [x] T008 \[S2006] Implement SHA-256 hashing, preflight metadata, backup id generation, backup file writes, and local backup metadata storage (`apps/server/src/managers/fileMutationManager.ts`)

***

## Implementation (7 tasks)

* [x] T009 \[S2006] Implement read and preview/preflight operations that return safe metadata without mutating files (`apps/server/src/managers/fileMutationManager.ts`)
* [x] T010 \[S2006] Implement write and edit operations with expected hash guards, duplicate-trigger prevention while in-flight, backup-before-mutation, transaction boundaries, and compensation on failure (`apps/server/src/managers/fileMutationManager.ts`)
* [x] T011 \[S2006] Implement delete operation with expected hash guards, duplicate-trigger prevention while in-flight, backup-before-mutation, transaction boundaries, and compensation on failure (`apps/server/src/managers/fileMutationManager.ts`)
* [x] T012 \[S2006] Implement move and rename operations with source/destination validation, expected hash guards, duplicate-trigger prevention while in-flight, transaction boundaries, and compensation on failure (`apps/server/src/managers/fileMutationManager.ts`)
* [x] T013 \[S2006] Integrate active file-intent conflict checks before mutating operations with explicit override or cleared-intent handling (`apps/server/src/managers/fileMutationManager.ts`)
* [x] T014 \[S2006] Record compact file execution runs with operation, path labels, before/after hashes, changed byte count, backup id, rollback state, and no content or patch bodies (`apps/server/src/managers/fileMutationManager.ts`)
* [x] T015 \[S2006] Implement rollback for write, edit, delete, move, and rename with idempotency protection, missing-backup handling, explicit rollback failure mapping, and safe execution metadata (`apps/server/src/managers/fileMutationManager.ts`)

***

## Testing And Documentation (5 tasks)

* [x] T016 \[S2006] Add server tests proving write, edit, delete, move, and rename mutate real temp-directory files and read/preview paths do not mutate (`apps/server/tests/fileMutationManager.test.ts`)
* [x] T017 \[S2006] Add server tests proving rollback restores prior content or paths, duplicate rollback is idempotent, backup failure prevents mutation, and mutation failure records recovery state (`apps/server/tests/fileMutationManager.test.ts`)
* [x] T018 \[S2006] Add server tests proving conflict, stale hash, symlink escape, absolute path, traversal, URL-like input, NUL input, generated/ignored directory, and destination-exists failures leave files unchanged (`apps/server/tests/fileMutationManager.test.ts`)
* [x] T019 \[S2006] Update command-center manager/protocol compatibility tests for compact file execution metadata and no file content, patch body, broad absolute path, token, secret, provider payload, or diagnostic leakage (`apps/server/tests/commandCenterManager.test.ts`, `packages/protocol/tests/orchestrationCommandCenter.test.ts`)
* [x] T020 \[S2006] Document the manager-level file mutation boundary, backup location, redaction rules, and Session 07 no-claim integration handoff (`apps/server/README_server.md`, `docs/api/README_api.md`)

***

## Verification (2 tasks)

* [x] T021 \[S2006] Run focused protocol and server checks (`npx vitest run packages/protocol/tests/fileMutation.test.ts packages/protocol/tests/orchestrationCommandCenter.test.ts apps/server/tests/fileMutationManager.test.ts apps/server/tests/commandCenterManager.test.ts`; `npm --workspace packages/protocol run typecheck`; `npm --workspace apps/server run typecheck`)
* [x] T022 \[S2006] Run workspace quality and whitespace gates (`npm run format:check`; `npm run lint`; `npm run typecheck --workspaces --if-present`; `npm test`; `git diff --check`)

***

## Completion Checklist

* [x] All tasks marked `[x]`
* [x] All tests and checks passing
* [x] All files ASCII-encoded with LF line endings
* [x] implementation-notes.md updated
* [x] Ready for `implement` to start the implement -> creview -> validate sequence

***

## Next Steps

Run the `implement` workflow step.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase20-session06-file-mutation-core/tasks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.