@calmo/task-runner 4.1.0 → 4.2.0

package/.jules/nexus.md

@@ -19,3 +19,8 @@
 
 **Insight:** Blindly retrying failing tasks is a "Product Anti-pattern". Retrying a `SyntaxError` or invalid user input 3 times (with exponential backoff!) is annoying and wasteful.
 **Action:** We must distinguish between "Transient" (network, resource lock) and "Permanent" (logic, validation) failures. Exposing a `shouldRetry` predicate gives the user control without complicating the core runner logic.
+
+## 2026-01-24 - The Cleanup Paradox
+
+**Insight:** "Continue On Error" is often misused for Cleanup logic. Users mark critical tasks as "Optional" just to ensure subsequent cleanup tasks run, which incorrectly allows *other* dependents to run too. True "Teardown" requires the *dependent* to assert its resilience, not the *dependency* to declare its weakness.
+**Action:** Invert the control. Instead of the failing task saying "I don't matter" (`continueOnError`), the cleanup task should say "I run anyway" (`runCondition: 'always'`). This preserves the criticality of the workflow while ensuring resource hygiene.

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.1.0"
+  ".": "4.2.0"
 }

package/AGENTS.md

@@ -26,6 +26,8 @@ Keep this managed block so 'openspec update' can refresh the instructions.
 - **Strict Null Safety:** Do not use `??` or optional chaining `?.` when you can guarantee existence via prior validation. Use non-null assertions `!` only when the invariant is locally provable or enforced by a validator.
 - **Dead Code Elimination:** Avoid `v8 ignore` comments. If code is unreachable, restructure the logic to prove it is unreachable to the compiler, or remove the branch if the invariant is guaranteed.
 - **Signal Combination:** Prefer `AbortSignal.any()` over manual event listeners when combining multiple `AbortSignal`s to simplify logic and avoid memory leaks.
+- **Map Lookups:** Avoid double lookups in Maps (e.g., `has()` followed by `get()`). Check the result of `get()` against `undefined` to perform the check in a single operation.
+- **String Replacement:** Always favor `String.prototype.replaceAll` over `String.prototype.replace` with global regex for clarity.
 
 ## Operational Protocols
 

package/CHANGELOG.md

@@ -18,6 +18,33 @@
 * refactor: Refactor TaskRunner to reduce cognitive complexity (#89) ([95c67d9](https://github.com/thalesraymond/task-runner/commit/95c67d9)), closes [#89](https://github.com/thalesraymond/task-runner/issues/89)
 * Refactor TaskGraphValidator to address SonarCloud issues (#88) ([77c1538](https://github.com/thalesraymond/task-runner/commit/77c1538)), closes [#88](https://github.com/thalesraymond/task-runner/issues/88)
 
+## [4.2.0](https://github.com/thalesraymond/task-runner/compare/task-runner-v4.1.0...task-runner-v4.2.0) (2026-02-15)
+
+
+### Features
+
+* 🎸 mvp for plugin system ([7d85610](https://github.com/thalesraymond/task-runner/commit/7d856103651416826bdf6b440d9aa613ab2ac997))
+* add middleware support proposal ([#123](https://github.com/thalesraymond/task-runner/issues/123)) ([e93c2f1](https://github.com/thalesraymond/task-runner/commit/e93c2f1bd34764dbb084ff9645836ec20fdef026))
+* **spec:** add task loop proposal ([#157](https://github.com/thalesraymond/task-runner/issues/157)) ([a89a846](https://github.com/thalesraymond/task-runner/commit/a89a8462cd7ff2a54625805e30ee0c14eae95fa2))
+
+
+### Bug Fixes
+
+* 🛰️ Sonar Specialist: Fix issues in `src/TaskRunner.ts` ([#128](https://github.com/thalesraymond/task-runner/issues/128)) ([fd87799](https://github.com/thalesraymond/task-runner/commit/fd877993497539728b6c7ba55d1a34ea7e1d7737))
+
+
+### Performance Improvements
+
+* ⚡ Optimize Mermaid graph generation performance ([#155](https://github.com/thalesraymond/task-runner/issues/155)) ([18d3e93](https://github.com/thalesraymond/task-runner/commit/18d3e934631907a2c41ceb2c60942d3ec50b9dc5))
+* ⚡ Optimize WorkflowExecutor loop performance ([#153](https://github.com/thalesraymond/task-runner/issues/153)) ([c0457f0](https://github.com/thalesraymond/task-runner/commit/c0457f00f9a1315f7b23829fec08d3bceba37a14))
+* optimize cascadeFailure to O(N) using index pointer ([#135](https://github.com/thalesraymond/task-runner/issues/135)) ([1ecd7b8](https://github.com/thalesraymond/task-runner/commit/1ecd7b8fe1c72ebc7f97aaaa6bc9aeacdb830ae2))
+* optimize EventBus scheduling with queueMicrotask ([#154](https://github.com/thalesraymond/task-runner/issues/154)) ([4d74788](https://github.com/thalesraymond/task-runner/commit/4d74788aa689da0f296986dc15fe8a4fd080bbc7))
+* optimize Mermaid graph generation by removing redundant ID loop ([#158](https://github.com/thalesraymond/task-runner/issues/158)) ([940bdc5](https://github.com/thalesraymond/task-runner/commit/940bdc5c377a0b54567f73e968202f8c7e5c5020))
+* optimize mermaid graph generation deduplication ([#150](https://github.com/thalesraymond/task-runner/issues/150)) ([ff5db6d](https://github.com/thalesraymond/task-runner/commit/ff5db6d7a8ac22c414f260d04e13e06ec894b30c))
+* optimize TaskStateManager initialization to avoid double map lookups ([#132](https://github.com/thalesraymond/task-runner/issues/132)) ([02c516c](https://github.com/thalesraymond/task-runner/commit/02c516cc030b27b4c3bb143107e25c91503b0dd8))
+* remove redundant processLoop call in WorkflowExecutor ([#151](https://github.com/thalesraymond/task-runner/issues/151)) ([8286223](https://github.com/thalesraymond/task-runner/commit/8286223c6e28f5a60414a554b877792f73e1b147))
+* **validator:** optimize graph validation (3x speedup) ([#127](https://github.com/thalesraymond/task-runner/issues/127)) ([66f97e7](https://github.com/thalesraymond/task-runner/commit/66f97e7bc3999d38b78640e29cd47b086532a97a))
+
 ## [4.1.0](https://github.com/thalesraymond/task-runner/compare/task-runner-v4.0.4...task-runner-v4.1.0) (2026-01-24)
 
 

package/README.md

@@ -21,6 +21,7 @@ Try the [Showcase App](https://task-runner-mu.vercel.app/) to see the runner in
 - **Event System**: Subscribe to lifecycle events for logging or monitoring.
 - **Runtime Validation**: Automatically detects circular dependencies and missing dependencies.
 - **Conditional Execution**: Skip tasks dynamically based on context state.
+- **Plugin System**: Extend functionality with custom logic and event listeners.
 
 ## Usage Example
 
@@ -139,6 +140,39 @@ console.log(graph);
 // Output: graph TD; A-->B; ...
 ```
 
+## Plugin System
+
+You can extend the `TaskRunner` with plugins to inject custom logic or listen to events without modifying the core.
+
+### Creating a Plugin
+
+A plugin is an object with a `name`, `version`, and an `install` method.
+
+```typescript
+import { Plugin, PluginContext } from "@calmo/task-runner";
+
+const MyLoggerPlugin: Plugin<MyContext> = {
+  name: "my-logger-plugin",
+  version: "1.0.0",
+  install: (context: PluginContext<MyContext>) => {
+    context.events.on("taskStart", ({ step }) => {
+      console.log(`[Plugin] Starting task: ${step.name}`);
+    });
+  },
+};
+```
+
+### Using a Plugin
+
+Register the plugin using the `use()` method on the `TaskRunner` instance.
+
+```typescript
+const runner = new TaskRunner(context);
+runner.use(MyLoggerPlugin);
+
+await runner.execute(steps);
+```
+
 ## Skip Propagation
 
 If a task fails or is skipped, the `TaskRunner` automatically marks all subsequent tasks that depend on it as `skipped`. This ensures that your pipeline doesn't attempt to run steps with missing prerequisites.

package/conductor/code_styleguides/general.md

@@ -0,0 +1,23 @@
+# General Code Style Principles
+
+This document outlines general coding principles that apply across all languages and frameworks used in this project.
+
+## Readability
+- Code should be easy to read and understand by humans.
+- Avoid overly clever or obscure constructs.
+
+## Consistency
+- Follow existing patterns in the codebase.
+- Maintain consistent formatting, naming, and structure.
+
+## Simplicity
+- Prefer simple solutions over complex ones.
+- Break down complex problems into smaller, manageable parts.
+
+## Maintainability
+- Write code that is easy to modify and extend.
+- Minimize dependencies and coupling.
+
+## Documentation
+- Document *why* something is done, not just *what*.
+- Keep documentation up-to-date with code changes.

package/conductor/code_styleguides/javascript.md

@@ -0,0 +1,51 @@
+# Google JavaScript Style Guide Summary
+
+This document summarizes key rules and best practices from the Google JavaScript Style Guide.
+
+## 1. Source File Basics
+- **File Naming:** All lowercase, with underscores (`_`) or dashes (`-`). Extension must be `.js`.
+- **File Encoding:** UTF-8.
+- **Whitespace:** Use only ASCII horizontal spaces (0x20). Tabs are forbidden for indentation.
+
+## 2. Source File Structure
+- New files should be ES modules (`import`/`export`).
+- **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.**
+- **Imports:** Do not use line-wrapped imports. The `.js` extension in import paths is mandatory.
+
+## 3. Formatting
+- **Braces:** Required for all control structures (`if`, `for`, `while`, etc.), even single-line blocks. Use K&R style ("Egyptian brackets").
+- **Indentation:** +2 spaces for each new block.
+- **Semicolons:** Every statement must be terminated with a semicolon.
+- **Column Limit:** 80 characters.
+- **Line-wrapping:** Indent continuation lines at least +4 spaces.
+- **Whitespace:** Use single blank lines between methods. No trailing whitespace.
+
+## 4. Language Features
+- **Variable Declarations:** Use `const` by default, `let` if reassignment is needed. **`var` is forbidden.**
+- **Array Literals:** Use trailing commas. Do not use the `Array` constructor.
+- **Object Literals:** Use trailing commas and shorthand properties. Do not use the `Object` constructor.
+- **Classes:** Do not use JavaScript getter/setter properties (`get name()`). Provide ordinary methods instead.
+- **Functions:** Prefer arrow functions for nested functions to preserve `this` context.
+- **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for multi-line strings or complex interpolation.
+- **Control Structures:** Prefer `for-of` loops. `for-in` loops should only be used on dict-style objects.
+- **`this`:** Only use `this` in class constructors, methods, or in arrow functions defined within them.
+- **Equality Checks:** Always use identity operators (`===` / `!==`).
+
+## 5. Disallowed Features
+- `with` keyword.
+- `eval()` or `Function(...string)`.
+- Automatic Semicolon Insertion.
+- Modifying builtin objects (`Array.prototype.foo = ...`).
+
+## 6. Naming
+- **Classes:** `UpperCamelCase`.
+- **Methods & Functions:** `lowerCamelCase`.
+- **Constants:** `CONSTANT_CASE` (all uppercase with underscores).
+- **Non-constant Fields & Variables:** `lowerCamelCase`.
+
+## 7. JSDoc
+- JSDoc is used on all classes, fields, and methods.
+- Use `@param`, `@return`, `@override`, `@deprecated`.
+- Type annotations are enclosed in braces (e.g., `/** @param {string} userName */`).
+
+*Source: [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)*

package/conductor/code_styleguides/typescript.md

@@ -0,0 +1,43 @@
+# Google TypeScript Style Guide Summary
+
+This document summarizes key rules and best practices from the Google TypeScript Style Guide, which is enforced by the `gts` tool.
+
+## 1. Language Features
+- **Variable Declarations:** Always use `const` or `let`. **`var` is forbidden.** Use `const` by default.
+- **Modules:** Use ES6 modules (`import`/`export`). **Do not use `namespace`.**
+- **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.**
+- **Classes:**
+  - **Do not use `#private` fields.** Use TypeScript's `private` visibility modifier.
+  - Mark properties never reassigned outside the constructor with `readonly`.
+  - **Never use the `public` modifier** (it's the default). Restrict visibility with `private` or `protected` where possible.
+- **Functions:** Prefer function declarations for named functions. Use arrow functions for anonymous functions/callbacks.
+- **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for interpolation and multi-line strings.
+- **Equality Checks:** Always use triple equals (`===`) and not equals (`!==`).
+- **Type Assertions:** **Avoid type assertions (`x as SomeType`) and non-nullability assertions (`y!`)**. If you must use them, provide a clear justification.
+
+## 2. Disallowed Features
+- **`any` Type:** **Avoid `any`**. Prefer `unknown` or a more specific type.
+- **Wrapper Objects:** Do not instantiate `String`, `Boolean`, or `Number` wrapper classes.
+- **Automatic Semicolon Insertion (ASI):** Do not rely on it. **Explicitly end all statements with a semicolon.**
+- **`const enum`:** Do not use `const enum`. Use plain `enum` instead.
+- **`eval()` and `Function(...string)`:** Forbidden.
+
+## 3. Naming
+- **`UpperCamelCase`:** For classes, interfaces, types, enums, and decorators.
+- **`lowerCamelCase`:** For variables, parameters, functions, methods, and properties.
+- **`CONSTANT_CASE`:** For global constant values, including enum values.
+- **`_` Prefix/Suffix:** **Do not use `_` as a prefix or suffix** for identifiers, including for private properties.
+
+## 4. Type System
+- **Type Inference:** Rely on type inference for simple, obvious types. Be explicit for complex types.
+- **`undefined` and `null`:** Both are supported. Be consistent within your project.
+- **Optional vs. `|undefined`:** Prefer optional parameters and fields (`?`) over adding `|undefined` to the type.
+- **`Array<T>` Type:** Use `T[]` for simple types. Use `Array<T>` for more complex union types (e.g., `Array<string | number>`).
+- **`{}` Type:** **Do not use `{}`**. Prefer `unknown`, `Record<string, unknown>`, or `object`.
+
+## 5. Comments and Documentation
+- **JSDoc:** Use `/** JSDoc */` for documentation, `//` for implementation comments.
+- **Redundancy:** **Do not declare types in `@param` or `@return` blocks** (e.g., `/** @param {string} user */`). This is redundant in TypeScript.
+- **Add Information:** Comments must add information, not just restate the code.
+
+*Source: [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)*

package/conductor/product-guidelines.md

@@ -0,0 +1,14 @@
+# Product Guidelines
+
+## Documentation Style
+- Tone: Professional, technical, and friendly.
+- Style: Clear, concise, and focused on accuracy, while remaining approachable with instructional examples.
+- Examples: Focused, bite-sized code snippets illustrating specific features for quick comprehension.
+
+## Brand Messaging & Visual Identity
+- Core Value: Stability and Reliability.
+- Focus: Emphasize robust testing, production-readiness, and the "engine-like" nature of the orchestrator.
+
+## Quality Standards
+- Clarity over brevity in technical explanations.
+- Prioritize accuracy and reliability in all user-facing communications.

package/conductor/product.md

@@ -0,0 +1,16 @@
+# Initial Concept
+A lightweight, type-safe, and domain-agnostic task orchestration engine. It resolves a Directed Acyclic Graph (DAG) of steps, executes independent tasks in parallel, and manages a shared context across the pipeline.
+
+## Target Users
+- Developers building complex CI/CD pipelines.
+- Engineers creating automated data processing workflows.
+
+## Goals
+- Provide a simple and intuitive API for defining and running task graphs.
+
+## Key Features
+- Enhanced observability and logging for complex task graphs.
+- Support for persistent state to allow resuming long-running workflows.
+
+## Complexity & Architecture
+- Provide a hybrid approach with optional plugins for advanced features like persistence.

package/conductor/setup_state.json

@@ -0,0 +1 @@
+{"last_successful_step": "2.5_workflow"}

package/conductor/tech-stack.md

@@ -0,0 +1,19 @@
+# Technology Stack
+
+## Core
+- **Programming Language:** TypeScript
+- **Runtime:** Node.js
+
+## Development Tools
+- **Package Manager:** pnpm
+- **Build Tool:** tsc (TypeScript Compiler)
+
+## Quality Assurance
+- **Test Framework:** Vitest
+- **Code Coverage:** @vitest/coverage-v8
+- **Linting:** ESLint (typescript-eslint)
+- **Formatting:** Prettier
+
+## Infrastructure & Release
+- **Release Management:** release-please
+- **Static Analysis:** SonarCloud

package/conductor/workflow.md

@@ -0,0 +1,334 @@
+# Project Workflow
+
+## Guiding Principles
+
+1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md`
+2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation
+3. **Test-Driven Development:** Write unit tests before implementing functionality
+4. **High Code Coverage:** Aim for 100% code coverage for all modules
+5. **User Experience First:** Every decision should prioritize user experience
+6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution.
+
+## Task Workflow
+
+All tasks follow a strict lifecycle:
+
+### Standard Task Workflow
+
+1. **Select Task:** Choose the next available task from `plan.md` in sequential order
+
+2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]`
+
+3. **Write Failing Tests (Red Phase):**
+   - Create a new test file for the feature or bug fix.
+   - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task.
+   - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests.
+
+4. **Implement to Pass Tests (Green Phase):**
+   - Write the minimum amount of application code necessary to make the failing tests pass.
+   - Run the test suite again and confirm that all tests now pass. This is the "Green" phase.
+
+5. **Refactor (Optional but Recommended):**
+   - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior.
+   - Rerun tests to ensure they still pass after refactoring.
+
+6. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like:
+   ```bash
+   pytest --cov=app --cov-report=html
+   ```
+   Target: 100% coverage for new code. The specific tools and commands will vary by language and framework.
+
+7. **Document Deviations:** If implementation differs from tech stack:
+   - **STOP** implementation
+   - Update `tech-stack.md` with new design
+   - Add dated note explaining the change
+   - Resume implementation
+
+8. **Commit Code Changes:**
+   - Stage all code changes related to the task.
+   - Always use conventional commits
+   - Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`.
+   - Perform the commit.
+
+9. **Attach Task Summary with Git Notes:**
+   - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`).
+   - **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change.
+   - **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit.
+     ```bash
+     # The note content from the previous step is passed via the -m flag.
+     git notes add -m "<note content>" <commit_hash>
+     ```
+
+10. **Get and Record Task Commit SHA:**
+    - **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash.
+    - **Step 10.2: Write Plan:** Write the updated content back to `plan.md`.
+
+11. **Commit Plan Update:**
+    - **Action:** Stage the modified `plan.md` file.
+    - **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`).
+
+### Phase Completion Verification and Checkpointing Protocol
+
+**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`.
+
+1.  **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
+
+2.  **Ensure Test Coverage for Phase Changes:**
+    -   **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit.
+    -   **Step 2.2: List Changed Files:** Execute `git diff --name-only <previous_checkpoint_sha> HEAD` to get a precise list of all files modified during this phase.
+    -   **Step 2.3: Verify and Create Tests:** For each file in the list:
+        -   **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`).
+        -   For each remaining code file, verify a corresponding test file exists.
+        -   If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`).
+
+3.  **Execute Automated Tests with Proactive Debugging:**
+    -   Before execution, you **must** announce the exact shell command you will use to run the tests.
+    -   **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `CI=true npm test`"
+    -   Execute the announced command.
+    -   If tests fail, you **must** inform the user and begin debugging. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance.
+
+4.  **Propose a Detailed, Actionable Manual Verification Plan:**
+    -   **CRITICAL:** To generate the plan, first analyze `product.md`, `product-guidelines.md`, and `plan.md` to determine the user-facing goals of the completed phase.
+    -   You **must** generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes.
+    -   The plan you present to the user **must** follow this format:
+
+        **For a Frontend Change:**
+        ```
+        The automated tests have passed. For manual verification, please follow these steps:
+
+        **Manual Verification Steps:**
+        1.  **Start the development server with the command:** `npm run dev`
+        2.  **Open your browser to:** `http://localhost:3000`
+        3.  **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly.
+        ```
+
+        **For a Backend Change:**
+        ```
+        The automated tests have passed. For manual verification, please follow these steps:
+
+        **Manual Verification Steps:**
+        1.  **Ensure the server is running.**
+        2.  **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'`
+        3.  **Confirm that you receive:** A JSON response with a status of `201 Created`.
+        ```
+
+5.  **Await Explicit User Feedback:**
+    -   After presenting the detailed plan, ask the user for confirmation: "**Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed.**"
+    -   **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation.
+
+6.  **Create Checkpoint Commit:**
+    -   Stage all changes. If no changes occurred in this step, proceed with an empty commit.
+    -   Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`).
+
+7.  **Attach Auditable Verification Report using Git Notes:**
+    -   **Step 7.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation.
+    -   **Step 7.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit.
+
+8.  **Get and Record Phase Checkpoint SHA:**
+    -   **Step 8.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`).
+    -   **Step 8.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: <sha>]`.
+    -   **Step 8.3: Write Plan:** Write the updated content back to `plan.md`.
+
+9. **Commit Plan Update:**
+    - **Action:** Stage the modified `plan.md` file.
+    - **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '<PHASE NAME>' as complete`.
+
+10.  **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note.
+
+### Quality Gates
+
+Before marking any task complete, verify:
+
+- [ ] All tests pass
+- [ ] Code coverage meets requirements (100%)
+- [ ] Code follows project's code style guidelines (as defined in `code_styleguides/`)
+- [ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc)
+- [ ] Type safety is enforced (e.g., type hints, TypeScript types, Go types)
+- [ ] No linting or static analysis errors (using the project's configured tools)
+- [ ] Works correctly on mobile (if applicable)
+- [ ] Documentation updated if needed
+- [ ] No security vulnerabilities introduced
+
+## Development Commands
+
+**AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.**
+
+### Setup
+```bash
+# Example: Commands to set up the development environment (e.g., install dependencies, configure database)
+# e.g., for a Node.js project: npm install
+# e.g., for a Go project: go mod tidy
+```
+
+### Daily Development
+```bash
+# Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format)
+# e.g., for a Node.js project: npm run dev, npm test, npm run lint
+# e.g., for a Go project: go run main.go, go test ./..., go fmt ./...
+```
+
+### Before Committing
+```bash
+# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests)
+# e.g., for a Node.js project: npm run check
+# e.g., for a Go project: make check (if a Makefile exists)
+```
+
+## Testing Requirements
+
+### Unit Testing
+- Every module must have corresponding tests.
+- Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach).
+- Mock external dependencies.
+- Test both success and failure cases.
+
+### Integration Testing
+- Test complete user flows
+- Verify database transactions
+- Test authentication and authorization
+- Check form submissions
+
+### Mobile Testing
+- Test on actual iPhone when possible
+- Use Safari developer tools
+- Test touch interactions
+- Verify responsive layouts
+- Check performance on 3G/4G
+
+## Code Review Process
+
+### Self-Review Checklist
+Before requesting review:
+
+1. **Functionality**
+   - Feature works as specified
+   - Edge cases handled
+   - Error messages are user-friendly
+
+2. **Code Quality**
+   - Follows style guide
+   - DRY principle applied
+   - Clear variable/function names
+   - Appropriate comments
+
+3. **Testing**
+   - Unit tests comprehensive
+   - Integration tests pass
+   - Coverage adequate (100%)
+
+4. **Security**
+   - No hardcoded secrets
+   - Input validation present
+   - SQL injection prevented
+   - XSS protection in place
+
+5. **Performance**
+   - Database queries optimized
+   - Images optimized
+   - Caching implemented where needed
+
+6. **Mobile Experience**
+   - Touch targets adequate (44x44px)
+   - Text readable without zooming
+   - Performance acceptable on mobile
+   - Interactions feel native
+
+## Commit Guidelines
+
+### Message Format
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting, missing semicolons, etc.
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests
+- `chore`: Maintenance tasks
+
+### Examples
+```bash
+git commit -m "feat(auth): Add remember me functionality"
+git commit -m "fix(posts): Correct excerpt generation for short posts"
+git commit -m "test(comments): Add tests for emoji reaction limits"
+git commit -m "style(mobile): Improve button touch targets"
+```
+
+## Definition of Done
+
+A task is complete when:
+
+1. All code implemented to specification
+2. Unit tests written and passing
+3. Code coverage meets project requirements
+4. Documentation complete (if applicable)
+5. Code passes all configured linting and static analysis checks
+6. Works beautifully on mobile (if applicable)
+7. Implementation notes added to `plan.md`
+8. Changes committed with proper message
+9. Git note with task summary attached to the commit
+
+## Emergency Procedures
+
+### Critical Bug in Production
+1. Create hotfix branch from main
+2. Write failing test for bug
+3. Implement minimal fix
+4. Test thoroughly including mobile
+5. Deploy immediately
+6. Document in plan.md
+
+### Data Loss
+1. Stop all write operations
+2. Restore from latest backup
+3. Verify data integrity
+4. Document incident
+5. Update backup procedures
+
+### Security Breach
+1. Rotate all secrets immediately
+2. Review access logs
+3. Patch vulnerability
+4. Notify affected users (if any)
+5. Document and update security procedures
+
+## Deployment Workflow
+
+### Pre-Deployment Checklist
+- [ ] All tests passing
+- [ ] Coverage 100%
+- [ ] No linting errors
+- [ ] Mobile testing complete
+- [ ] Environment variables configured
+- [ ] Database migrations ready
+- [ ] Backup created
+
+### Deployment Steps
+1. Merge feature branch to main
+2. Tag release with version
+3. Push to deployment service
+4. Run database migrations
+5. Verify deployment
+6. Test critical paths
+7. Monitor for errors
+
+### Post-Deployment
+1. Monitor analytics
+2. Check error logs
+3. Gather user feedback
+4. Plan next iteration
+
+## Continuous Improvement
+
+- Review workflow weekly
+- Update based on pain points
+- Document lessons learned
+- Optimize for user happiness
+- Keep things simple and maintainable