Build Feature

Build Feature

Execute tasks from an approved plan, one task at a time, with strict confidence gating and mandatory validation. Update the plan as execution proceeds.

Confidence note: Confidence ≥90% is a motivation/diagnostic, not a requirement. The implementation gate is still ≥80% confidence for IMPLEMENT tasks.

Operating Mode

BUILDING ONLY

Allowed: modify code, add/update tests, produce non-code artifacts, run validations, commit changes, update the plan doc.

Not allowed: implement tasks below threshold, do work not in the plan, skip validation, commit failing outputs, silently change scope.

Prerequisites

• Plan exists: docs/plans/<feature-slug>-plan.md
• Task(s) to build are:
  • Type: IMPLEMENT
  • Confidence ≥80% (overall and all implied dimension minimums via the plan rubric)
  • All dependencies completed
  • No blockers noted in the task

If any selected IMPLEMENT task is <80% → STOP and run /re-plan for that task.

If a selected task is 80–89%: it is eligible to build, but treat the “unknowns” as real—ensure the task has explicit risks/verification steps (or update the plan before proceeding).

Fast Path (with argument)

If user provides a slug or card ID (e.g., /build-feature commerce-core or /build-feature BRIK-ENG-0020):

• Skip discovery entirely
• If slug: read docs/plans/<slug>-plan.md directly
• If card ID: look up plan link from card file
• Target: <2 seconds to start building

Discovery Path (no argument)

If user provides no argument, read the pre-computed index (single file):

docs/business-os/_meta/discovery-index.json

Present the readyForBuild array (filtered to those with pending tasks) as a table:

## Ready for Build

| Slug | Title | Pending Tasks | Business |
|------|-------|---------------|----------|
| xa-client-readiness | XA Client Readiness | 15 | PIPE |

Enter a slug to start building, or a specific TASK-ID.

Also check the planned array for cards with plan links.

Inputs

• The plan doc: docs/plans/<feature-slug>-plan.md
• Optional: fact-find brief: docs/plans/<feature-slug>-fact-find.md
• Optional: user-specified task IDs to build first

If the user does not specify tasks, build in ascending TASK order among eligible IMPLEMENT tasks.

Execution Skill Dispatch (Progressive Disclosure)

For each task, read Deliverable and Execution-Skill from the plan and route accordingly:

Startup aliases (from plan field Startup-Deliverable-Alias) are clarity labels, not replacement deliverable types:

If a referenced execution skill is missing, stop and run /re-plan to either:

• add the missing skill as a prerequisite task, or
• re-scope the task to an available execution path.

Pre-Build Check (Required)

Before executing any task work, verify all of the following:

A) Plan integrity

• The plan file exists and is the active source of truth.
• The target task exists and includes:
  • Type, Deliverable, Execution-Skill, Affects (file paths), Depends on, Confidence breakdown, Acceptance, Validation contract, Planning validation (for M/L effort), Rollout/rollback notes, Documentation impact.
  • For business-artifact/mixed tasks: Artifact-Destination, Reviewer, Approval-Evidence, Measurement-Readiness.
• The task is not marked Superseded/Blocked/Needs-input.

If any required task fields are missing → treat as a confidence drop → STOP → /re-plan.

B) Eligibility gate

Confirm:

• Task Type = IMPLEMENT, SPIKE, or INVESTIGATE
• Overall confidence ≥80%
• All dependency tasks are complete (per plan status)
• No open DECISION tasks gate this work

Task type differences:

• IMPLEMENT: Standard execution work. Use TDD for code/mixed tasks, artifact cycle for business-artifact tasks.
• SPIKE: Produces a prototype or executable proof. Must have explicit validation criteria. On completion, its output (evidence) may be used by /re-plan to promote downstream tasks.
• INVESTIGATE: Produces a decision memo or analysis artifact — not implementation delivery. Validation is: the decision memo exists and answers the question. Commit the memo/notes, then mark complete. Skip step 3 execution cycles and instead: perform investigation, produce artifact, verify exit criteria, commit artifact, update plan.
• CHECKPOINT: Horizon re-assessment gate — not code. See "CHECKPOINT Handling" below.

Execution-track differences (for IMPLEMENT tasks):

• code or mixed: Use the TDD cycle (tests first, fail, implement, pass).
• business-artifact: Use the artifact cycle (draft, review against validation contract, finalize, evidence capture).

If not eligible → STOP → /re-plan.

C) Local readiness gate

• Working tree is clean (or you explicitly understand any local diffs and they are unrelated and will not be mixed).
• Baseline is sane:
  • For code/mixed tasks: if the repo has a standard "quick check" (typecheck/lint/unit), run it before starting.
  • For business-artifact tasks: verify required source docs/data and channel constraints are available before drafting.
  • If baseline is failing for unrelated reasons, do not proceed without documenting it in the plan and/or resolving via a separate, explicitly planned task.

D) File-reading gate

Before changing anything:

• Read all files listed in "Affects" (both primary and [readonly])
• Read any immediately adjacent files needed to understand invariants (callers, types, schemas, tests)
• For code/mixed tasks, check for test stubs from planning (L-effort tasks should have them; use as starting point for TDD)

Scope boundaries:

• Primary files (no prefix): may be modified as part of this task
• [readonly] files: must NOT be modified — these are dependencies for understanding only

If you need to modify:

• A file not in "Affects" → STOP → /re-plan (new scope)
• A [readonly] file → STOP → /re-plan (scope was wrong, dependency is actually a modification target)

E) Validation Contract Gate

Before implementing, verify the task has a complete validation contract:

• For code/mixed tasks:
  • Enumerated test cases (TC-XX) covering all acceptance criteria
  • Expected outcomes specified for each TC
  • Test type and location identified
  • For M/L tasks: test case specs are detailed enough to write tests
• For business-artifact tasks:
  • Enumerated validation checks (VC-XX) covering all acceptance criteria
  • Pass conditions specified for each VC
  • Artifact-Destination is explicit and actionable
  • Reviewer is named
  • Approval-Evidence capture path/method is defined
  • Measurement-Readiness is explicit (owner + cadence + tracking location)

If validation contract is incomplete → treat as confidence drop → STOP → /re-plan.

A task without enumerated validation cases cannot be built, regardless of its stated confidence.

F) Scout verification gate (when Scouts field is present)

If the task has a Scouts field, verify each scouted assumption still holds before building:

• Re-run any probe tests from planning — if they now fail, the assumption has changed. STOP → /re-plan.
• Re-check doc lookups if a dependency version has changed since planning.
• Verify type-level scouts by running tsc on any type assertions from planning.

If scouts were marked "inconclusive" during planning, treat them as risks — proceed cautiously but be ready to stop if the assumption proves false during implementation.

If any scout fails → treat as confidence drop → STOP → /re-plan.

G) Topology freshness gate (required after re-plan decomposition)

If the most recent /re-plan split tasks, added/removed tasks, or changed dependency topology, ensure /sequence-plan has already run on the updated plan before continuing build.

• Verify active task IDs/dependencies/Blocks are internally consistent and the Parallelism Guide reflects the current graph.
• If decomposition occurred but sequencing is stale or missing, STOP and run /sequence-plan first, then resume /build-feature.

Build Loop (One Task per Cycle)

1) Select the next eligible task

Rules:

• Only one IMPLEMENT task at a time.
• Only tasks ≥80% confidence.
• Dependencies must be done.
• If the next task is a CHECKPOINT → execute the checkpoint protocol (see below) instead of the normal build loop.

Dispatch rule:

• If Execution-Skill for the selected task is not build-feature, invoke that specialized skill with the task context and expected output path.
• After specialized execution, return to this workflow for confidence reassessment, final validation, commit, and plan updates.

2) Restate the task constraints (from the plan)

Extract from the plan into your working context:

• Acceptance criteria
• Validation plan (tests/checklists/reviews to run)
• Rollout/rollback requirements (flags, migrations, backwards compatibility)
• Observability expectations (logging/metrics)
• Documentation impact (standing docs to update)

If any of these are unclear during execution → treat as confidence drop → STOP → /re-plan.

3) Execute using track-appropriate cycle

Choose the execution cycle based on the task's Execution-Track / Deliverable in the plan:

• Code/mixed: follow TDD path (3a–3f)
• Business-artifact: follow artifact path (3g–3l)

a) [Code/mixed] Audit existing tests for extinction

Before writing new tests, check for existing tests related to the code you're modifying:

1. Find related tests: Search for test files covering the affected modules/components
2. Evaluate test validity: Read each test and verify it tests current behavior, not obsolete contracts
3. Identify extinct tests: Tests are "extinct" if they:
   • Assert behavior that no longer exists
   • Test removed/renamed APIs or props
   • Pass or fail for reasons unrelated to current functionality
   • Were not updated when the functional code last changed
4. Update or remove extinct tests: Do not layer new tests on top of outdated ones
   • Update extinct tests to reflect current behavior
   • Remove tests for functionality that no longer exists
   • Document any test removals in the commit message

Why this matters: Extinct tests give false confidence signals. A passing test suite that includes outdated tests does not validate current behavior.

b) [Code/mixed] Write or complete tests first

• If test stubs exist from planning (L-effort tasks):
  1. Convert test.todo() / it.skip() to active tests with full assertions
  2. Remove the .todo or .skip modifier
  3. Implement the test body based on the TC-XX specification in the stub comment
• If no stubs exist: write tests based on the task's validation contract (TC-XX specifications)
• Tests should cover the expected behavior before any implementation code is written
• Mock accuracy gate (before writing any mock):
  • Read the source file for each component under test and each module/hook you plan to mock.
  • Verify real import paths from source (do not assume module locations).
  • Verify hook return shapes (all properties/destructured fields used by the component).
  • Verify export patterns (default, named exports, wrappers like memo(...)) before using jest.requireActual or module destructuring.
  • Define mocked object returns as stable const references outside mock factory functions to avoid React dependency-array re-render loops (see docs/testing-policy.md, Rule 6).

Activating test stubs:

// Before (from planning):
test.todo('should return 409 when entity was modified'); // TC-02

// After (build starts):
test('should return 409 when entity was modified', async () => {
  // TC-02: Concurrent modification → 409 Conflict
  const result = await updateCard(id, { baseEntitySha: 'stale' });
  expect(result.status).toBe(409);
  expect(result.body.error).toBe('CONFLICT');
});

c) [Code/mixed] Run tests — verify they fail for the right reasons

• Tests should fail because the feature/fix doesn't exist yet
• If tests pass unexpectedly → investigate (feature may already exist, or test is wrong)
• If tests fail for unexpected reasons → STOP → /re-plan

d) [Code/mixed] Implement minimum code to make tests pass

• Write only what's needed to make tests green
• Keep changes tightly scoped to the task
• Follow established patterns referenced in the plan (or discovered during file-reading)
• If implementation duplicates existing code, use the existing pattern or extract a shared utility — note any new shared abstractions in the commit message
• Do not "sneak in" refactors or over-engineer; if refactor is required, add a new task via /re-plan

e) [Code/mixed] Refactor if needed (tests stay green)

• Clean up implementation while keeping tests passing
• This is for minor cleanup only, not architectural changes

f) [Code/mixed] Update documentation

• Update all docs listed in the task's "Documentation impact" field
• If the task specifies "None", skip this step
• If implementation revealed additional docs needing updates not listed in the plan, update them and note the deviation

g) [Business-artifact] Staleness check on hypothesis landscape

• If the fact-find brief includes a Hypothesis & Validation Landscape, scan it for time-sensitive assumptions (supplier quotes, market pricing, regulatory rules, competitor positioning, demand signals) whose validity may have decayed since planning.
• If any key hypothesis depends on data older than 14 days, flag it and verify before drafting. If the assumption no longer holds, STOP → /re-plan.
• If no hypothesis landscape exists or all inputs are fresh, proceed.

h) [Business-artifact] Draft the artifact

• Produce the minimum viable artifact described in task acceptance.
• Keep scope tightly aligned to task and deliverable type (email/brief/asset/sheet/message).
• Save/update at the path or destination defined in the plan.

i) [Business-artifact] Run validation checks (VC-XX)

• Execute every enumerated VC from the validation contract.
• Verify channel/format constraints and compliance/brand requirements.
• If any VC fails unexpectedly and fix is non-obvious → STOP → /re-plan.

j) [Business-artifact] Review and approval handoff

• Route artifact to the owner/reviewer specified in the plan (or capture review-ready evidence if async).
• Capture explicit owner acknowledgement (who, when, where) and store proof at the Approval-Evidence destination defined in plan.
• Record approval status (approved / changes requested / blocked).
• If blocked by unresolved preference/decision → STOP and surface DECISION task.

k) [Business-artifact] Finalize artifact

• Incorporate approved revisions.
• Re-run affected VC checks after changes.
• Confirm final artifact destination publish/handoff is complete.
• Confirm measurement tracking is ready at the declared Measurement-Readiness location.

l) [Business-artifact] Update documentation

• Update playbooks/runbooks/docs listed in "Documentation impact".
• Record any deviations discovered during artifact execution.

3b) Confidence Reassessment Based on Validation Outcomes (Mandatory)

After the execution cycle completes, reassess task confidence based on what validation revealed.

Validation Outcome → Confidence Impact

Hard Stop on Confidence Drop

If post-validation confidence drops below 80%:

• STOP immediately — do not commit
• Document what validation revealed
• Run /re-plan for this task and any dependent tasks

This creates a feedback loop: validation outcomes directly inform confidence, which gates further work.

4) Final validation (mandatory)

Run validation aligned to execution track:

• For code/mixed tasks: Typecheck, lint, and full relevant test suites (not just new tests)
• For business-artifact tasks: all VC checks pass, artifact is published to Artifact-Destination, reviewer/owner acknowledgement is captured with Approval-Evidence, and measurement readiness/tracking is confirmed

Rule: never commit failing execution outputs. If failures occur:

• If the fix is straightforward and clearly within the task scope, fix it
• If the failure indicates unclear behavior, unexpected dependencies, or uncertain approach:
  • STOP → /re-plan

5) Confidence and effort re-check during execution

If you encounter any of the following, treat it as a confidence regression:

• unexpected dependency or integration boundary
• ambiguous long-term design choice not addressed in the plan
• blast radius larger than documented
• unclear contract/data shape
• unclear channel/approval/compliance requirement for business artifacts
• validation failures that are non-obvious

Effort misclassification check:

If the actual work exceeds the classified effort level, STOP and /re-plan:

• S-effort task requires 3+ files → should be M or L
• M-effort task requires 6+ files or 3+ integration boundaries → should be L
• Any task introduces a new pattern but wasn't classified L → should be L
• Any task needs e2e tests but wasn't classified L → should be L

Do not continue building an under-classified task. The validation requirements exist to match the actual risk.

Action:

• STOP immediately
• Capture what you learned (files, symptoms, failing tests, actual scope)
• Run /re-plan for the task with corrected effort classification

6) Commit (task-scoped)

Create commits that are unambiguously tied to the task.

Commit requirements:

• Include the TASK ID in the subject line.
• Keep the commit scope limited to the task.
• Include the repository's required AI co-author trailer.

Recommended format:

feat(<feature-slug>): <short change summary> (TASK-XX)
fix(<feature-slug>): <short change summary> (TASK-XX)
test(<feature-slug>): <short change summary> (TASK-XX)
docs(plans): mark TASK-XX complete

Co-authorship: include Co-authored-by: using the exact convention already present in this repo's history/policy.

7) Update the plan (required after each task)

After committing the task, update docs/plans/<feature-slug>-plan.md:

Per-task updates:

Add or update:

• Status: Complete (YYYY-MM-DD)
• Implementation Notes: what changed, and where
• Validation Evidence: commands run + results summary
• Commit(s): commit hash(es) for traceability

If execution changed understanding:

• note confidence changes (and why)
• if confidence would now be <80%, do not "paper over" it—stop and /re-plan

Plan-level updates:

• Update Last-updated
• If your plan uses an effort-weighted Overall-confidence, recompute only if you materially changed confidence values (optional; do not churn it unnecessarily)
• If the plan has a Task Summary table, update it (e.g., add a Status column if not present, or mark TASK-XX as Done). If it does not, do status tracking inside each TASK section.

Suggested per-task completion snippet:

Add under the task:

#### Build Completion (YYYY-MM-DD)
- **Status:** Complete
- **Commits:** <hash1>, <hash2>
- **Execution cycle:**
  - Validation cases executed: <TC-XX and/or VC-XX>
  - Cycles: <red-green count or draft-review count>
  - Initial validation: <FAIL expected / draft pending review>
  - Final validation: PASS
- **Confidence reassessment:**
  - Original: XX%
  - Post-validation: YY%
  - Delta reason: <validation confirmed | edge case found | dependency discovered>
- **Validation:**
  - Ran: `<commands/checklists>` — PASS
- **Documentation updated:** <list of docs updated, or "None required">
- **Implementation notes:** <what changed, any deviations from plan>

8) Repeat

Move to the next eligible IMPLEMENT task and repeat the cycle.

9) Archive completed plan

When all tasks in the plan are marked Complete, archive the plan:

1. Set frontmatter Status: Archived (not Complete).
2. Move the plan file to docs/plans/archive/.
3. Commit: docs(plans): archive <plan-name> — all tasks complete

CHECKPOINT Handling

When the next task in sequence is a CHECKPOINT task, execute this protocol instead of the normal build loop:

1) Gather evidence from completed tasks

Summarize what was learned during the build so far:

• Which tasks completed successfully and what they revealed
• Any unexpected findings, scope changes, or confidence adjustments
• Whether the "Horizon assumptions to validate" listed in the CHECKPOINT have been confirmed or disproved

2) Run /re-plan on remaining tasks

Invoke /re-plan targeting all tasks that come after the CHECKPOINT in the plan. This re-assessment uses evidence from completed tasks (E2/E3 class) to:

• Reassess confidence on remaining tasks using real implementation evidence
• Split tasks that are too large or depend on unproven assumptions
• Abandon or defer tasks that are no longer viable given what was learned
• Insert new tasks discovered during execution
• Update the plan with any new findings

If /re-plan decomposes or topology-edits the remaining tasks, run /sequence-plan before evaluating readiness to continue building.

3) Evaluate re-plan results

After /re-plan completes:

• If decomposition/topology changes occurred and sequencing has not run yet: STOP and run /sequence-plan, then re-evaluate.
• If remaining tasks are ≥80% and no open questions: Mark the CHECKPOINT as complete, then continue the build loop with the next eligible task.
• If some tasks were revised but are still ≥80%: Mark CHECKPOINT complete, continue building the revised tasks.
• If remaining tasks dropped below 80%: Mark CHECKPOINT complete, then follow the normal below-threshold protocol (stop building those tasks, report to user).
• If the approach was fundamentally invalidated: Mark CHECKPOINT complete, stop building, and report the dead end with evidence for what went wrong and what alternatives exist.

4) Update the plan

Mark the CHECKPOINT task as Complete (YYYY-MM-DD) with a note summarizing:

• Assumptions validated / invalidated
• Tasks revised, added, or removed
• Decision to continue, revise, or stop

Why CHECKPOINTs matter

Without CHECKPOINTs, a plan with 8 dependent tasks could build all 8 before discovering task 2's assumption was wrong — wasting tasks 3–8. With a CHECKPOINT after task 3, the re-assessment catches the problem after 3 tasks instead of 8. The cost of a CHECKPOINT (one /re-plan invocation) is far less than the cost of a dead-end deep in implementation.

Stopping Conditions (Hard Stops)

Rules

• One IMPLEMENT task per cycle.
• Never build below 80% confidence.
• Never skip validation.
• Never commit failing execution outputs.
• Do not expand scope beyond the plan.
• Update the plan after every completed task.

Feedback to Future Planning

When confidence changes based on validation outcomes, capture the learning for future work:

This feedback loop improves future /fact-find and /plan-feature accuracy. When completing a task, explicitly note any learnings that should inform future planning.

Escalation to user: Only ask the user when:

• Business rules/UX intent cannot be inferred from repo or docs
• Two approaches are truly equivalent and require preference
• You have exhausted evidence sources and the uncertainty remains

When you do ask:

• Ask the minimum number of questions required to proceed
• Each question must state what decision it gates
• Include a recommended default with risk assessment if appropriate

Quality Checks

A build cycle is considered complete only if:

• Pre-build checks (A–E) all passed before executing task work.
• Existing related tests were audited for extinction (code/mixed tasks).
• Code/mixed tasks: tests were written/completed BEFORE implementation code (TDD).
• Code/mixed tasks: tests initially failed for the expected reasons (feature not yet implemented).
• Business-artifact tasks: hypothesis landscape staleness checked before drafting (if available).
• Business-artifact tasks: artifact drafted, reviewed, finalized, and published/handoff completed against VC checks.
• Business-artifact tasks: reviewer/owner acknowledgement captured and linked in Approval-Evidence.
• Business-artifact tasks: post-delivery tracking readiness confirmed in Measurement-Readiness destination.
• Implementation is scoped exactly to the task (no scope creep).
• Actual scope matched classified effort (if not, stopped and re-planned with correct effort).
• Standing documentation updated per "Documentation impact" field (or confirmed "None").
• All required validations passed (code commands and/or VC checklists).
• Commits include TASK ID and are scoped to the task.
• Plan doc updated with Status, Commits, Validation evidence.
• Confidence was re-assessed; if <80%, stopped and triggered /re-plan.
• No failing execution output was committed.

Execution Quality Checks

• Confidence was reassessed after execution cycle completed.
• Post-validation confidence is documented in plan.
• If confidence dropped below 80%, stopped and triggered /re-plan.
• Cycle counts documented (red-green for code, draft-review for business artifacts).
• All enumerated validation cases (TC-XX and/or VC-XX) from plan were executed.

Completion Messages

Use one of the following outcomes:

A) All eligible tasks complete:

"All eligible IMPLEMENT tasks are complete and validated. Plan updated with completion status and validation evidence. Remaining work: <none / list>. Ready for PR review."

B) Some tasks remain but are not eligible:

"Completed N/M IMPLEMENT tasks (≥80% confidence). Tasks are not eligible (confidence <80% or blocked). Recommend /re-plan for those tasks before continuing."

C) Stopped mid-task due to confidence regression:

"Stopped during TASK-XX due to newly discovered complexity or unclear blast radius. No further execution will proceed until /re-plan updates the plan for TASK-XX (and any dependent tasks)."

Business OS Integration (Default)

When plan frontmatter includes Card-ID, /build-feature integrates with Business OS by default.

Escape hatch: set Business-OS-Integration: off in plan frontmatter to skip card/stage-doc/lane writes for intentionally standalone work.

Fail-closed rule: if any API call fails, stop and surface the error.

When Card-ID is Present (and integration is on)

Step 1: Start Build Transition (First Task Only)

Before starting first task, perform build-start transition via API.

1a) Read the card to get current lane + entity SHA:

{
  "method": "GET",
  "url": "${BOS_AGENT_API_BASE_URL}/api/agent/cards/PLAT-ENG-0023",
  "headers": { "X-Agent-API-Key": "${BOS_AGENT_API_KEY}" }
}

Response includes { entity, entitySha }.

1b) Create build stage doc if missing:

{
  "method": "GET",
  "url": "${BOS_AGENT_API_BASE_URL}/api/agent/stage-docs?cardId=PLAT-ENG-0023&stage=build",
  "headers": { "X-Agent-API-Key": "${BOS_AGENT_API_KEY}" }
}

If none exists, create it via POST /api/agent/stage-docs.

1c) Deterministic lane transition (Planned -> In progress):

If current Lane is Planned, update directly and set Last-Progress:

{
  "method": "PATCH",
  "url": "${BOS_AGENT_API_BASE_URL}/api/agent/cards/PLAT-ENG-0023",
  "headers": {
    "X-Agent-API-Key": "${BOS_AGENT_API_KEY}",
    "Content-Type": "application/json"
  },
  "body": {
    "baseEntitySha": "<entitySha from GET>",
    "patch": {
      "Lane": "In progress",
      "Last-Progress": "YYYY-MM-DD"
    }
  }
}

Conflict handling: on 409 CONFLICT, refetch and retry once. If retry conflicts, stop.

Step 2: Update Card Progress (After Each Task)

After each task commit + plan update:

• PATCH card Last-Progress
• PATCH build stage doc content (progress tracker + build log)

Step 3: Check for Completion (After Each Task)

When all eligible IMPLEMENT tasks are complete and validations passed:

• Update build stage doc transition checklist
• Perform deterministic Done transition (Step 4)

Step 4: Deterministic lane transition (In progress -> Done)

Move card directly to Done when all completion-gate criteria are true:

• All eligible IMPLEMENT tasks complete with evidence
• All required validations passing (tests and/or VC checks)
• Documentation impact addressed
• No unresolved blocking DECISION tasks

{
  "method": "PATCH",
  "url": "${BOS_AGENT_API_BASE_URL}/api/agent/cards/PLAT-ENG-0023",
  "headers": {
    "X-Agent-API-Key": "${BOS_AGENT_API_KEY}",
    "Content-Type": "application/json"
  },
  "body": {
    "baseEntitySha": "<entitySha from GET>",
    "patch": {
      "Lane": "Done",
      "Last-Progress": "YYYY-MM-DD"
    }
  }
}

Do not move to Done if any completion criterion is unmet.

Step 5: Discovery index freshness

After card/stage-doc writes and deterministic lane transitions, rebuild discovery index:

docs/business-os/_meta/rebuild-discovery-index.sh > docs/business-os/_meta/discovery-index.json

Retry once; if it still fails, stop and surface discovery-index stale.

On repeated failure, include:

• failing command,
• retry count,
• stderr summary,
• exact operator rerun command.

Do not emit a clean completion message while index state is stale.

Completion Messages (with Card-ID)

A) All eligible tasks complete:

"All eligible IMPLEMENT tasks are complete and validated. Plan updated with completion status and validation evidence. Card {CARD-ID} Last-Progress updated via API. Build stage doc updated via API. Deterministic lane transition applied: In progress -> Done."

B) Some tasks remain:

"Completed N/M IMPLEMENT tasks. Card {CARD-ID} Last-Progress updated to {DATE} via API. Build stage doc updated with progress. Lane remains In progress until completion gate is satisfied."

C) Stopped mid-task:

"Stopped during TASK-XX. Card {CARD-ID} Last-Progress remains at previous value. Build stage doc records the blocker."

Without Card-ID (or Integration Off)

Skip all Business OS integration steps and use standard completion messages.

Related Resources

• Card operations: .claude/skills/_shared/card-operations.md
• Stage doc operations: .claude/skills/_shared/stage-doc-operations.md
• Exception-only/manual lane proposals (non-mechanical transitions): .claude/skills/propose-lane-move/SKILL.md