cfsa-antigravity 6.0.0 → 6.2.0

package/template/.pi/skills/session-continuity/protocols/01-session-resumption.md

@@ -0,0 +1,63 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.agents/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Protocol 1: Session Resumption
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: Any workflow start, or `instructions/workflow.md` step 1
+
+**Purpose**: Load cross-session context so the agent knows where to resume.
+
+## Steps
+
+1. **Check if `.memory/pipeline/progress/index.md` exists**
+   - If no: this is a fresh project with no tracked progress. Skip resumption.
+   - If yes: continue.
+
+2. **Read `index.md`** — get overall status, phase progress percentages.
+
+3. **Find in-progress items** — scan for `[/]` markers (in-progress) in phase files.
+   - If found: this is the resumption point.
+   - If none: find the next unchecked `[ ]` item.
+
+4. **Read the latest session log** — `sessions/` directory, most recent file.
+   - What was accomplished last session?
+   - What was deferred and why?
+   - What's the recommended starting point?
+
+5. **Read `.memory/wiki/blockers.md`** — are there unresolved blockers?
+
+6. **Read `.memory/wiki/decisions.md`** — load key decisions for context.
+
+7. **Drift scan (mandatory — runtime-agnostic)**
+
+   Before trusting the resumption point, run the cross-file consistency verifier:
+
+   ```
+   node scripts/check-progress-consistency.mjs
+   ```
+
+   - Exit 0 → progress files agree across slice/phase/index. Trust the resume point and continue to step 8.
+   - Exit 1 → drift. A previous session (possibly in a different runtime — Claude, Antigravity, Codex, Factory) committed work but did not finish updating all four progress targets. **DO NOT silently re-do or skip past the affected slice.** Surface the verifier's full output to the user with this exact framing:
+
+     ```
+     Progress drift detected from a previous session. Before resuming, the following must be reconciled:
+     <verifier output>
+
+     Likely cause: another runtime completed work but did not finish updating all progress files (Protocol 3 steps 8–10 were skipped or interrupted).
+
+     Recommended action: hand-edit the offending files to match the actual completion state on disk (check `git status`, slice's Completion Signature block, and test pass/fail), then re-run this check. I will not advance until the verifier returns 0.
+     ```
+
+   - Exit 2 → malformed progress files. **STOP**: report and ask the user before attempting repair.
+
+   If `scripts/check-progress-consistency.mjs` does not exist in the project (older installation), note this and recommend `/sync-kit`, then fall back to manually opening `index.md` + the latest in-progress phase file + that phase's slice files and confirming the fractions and checkboxes match before resuming.
+
+8. **Summarize for the current task**:
+   ```
+   Status: Phase 2 in progress — 3/7 slices complete (43%)
+   Last session: Completed auth middleware slice, deferred rate limiting (blocked on Redis)
+   Blockers: 1 active — Redis connection config needed
+   Drift scan: clean (verifier exit 0)
+   Resume at: Phase 2, Slice 4 — Rate limiting middleware
+   ```

package/template/.pi/skills/session-continuity/protocols/02-progress-generation.md

@@ -0,0 +1,85 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.agents/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Protocol 2: Progress Generation
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: `/plan-phase` step 7
+
+**Purpose**: Create progress tracking files from a newly planned phase.
+
+## Steps
+
+1. **Read the phase plan** that was just created (the output of `/plan-phase`).
+
+2. **Create or update `.memory/pipeline/progress/index.md`**:
+   ```markdown
+   # Implementation Progress
+
+   **Project**: {{PROJECT_NAME}}
+   **Last updated**: {{DATE}}
+   **Overall**: 0/{{TOTAL}} slices (0%)
+
+   ## Phases
+
+   | Phase | Status | Progress | Link |
+   |-------|--------|----------|------|
+   | Phase 1: {{NAME}} | not-started | 0/{{N}} | [→](phases/phase-01.md) |
+   ```
+
+3. **Create `.memory/pipeline/progress/phases/phase-NN.md`**:
+   ```markdown
+   # Phase {{N}}: {{NAME}}
+
+   **Status**: not-started
+   **Progress**: 0/{{TOTAL}} slices
+
+   ## Slices
+
+   - [ ] **Slice 1**: {{DESCRIPTION}} ({{S|M|L}})
+     - [ ] Contract: {{CONTRACT_LIBRARY}} schema for {{entity}}
+     - [ ] `BE` API endpoints for {{entity}}
+       - [ ] Subtask 1
+       - [ ] Subtask 2
+     - [ ] `FE` {{entity}} page and components
+       - [ ] Subtask 1
+       - [ ] Subtask 2
+     - [ ] `QA` Integration tests for {{entity}}
+       - [ ] Subtask 1
+     → [log](../slices/phase-01-slice-01.md)
+   ```
+
+   **Surface tag rules for Progress Generation:**
+   - Tag tasks (Level 3) with `BE`, `FE`, or `QA` as a backtick-wrapped prefix
+   - Untagged tasks are sequential (handled by orchestrator before parallel dispatch)
+   - `files:` blocks are NOT written during generation — only during claim (Protocol 9)
+   - Subtasks under tagged tasks inherit the parent's surface ownership
+
+4. **Create `.memory/pipeline/progress/slices/phase-NN-slice-NN.md`** for each slice with ≥3 criteria:
+   ```markdown
+   # Phase {{P}} / Slice {{S}}: {{NAME}}
+
+   **Status**: not-started
+   **Complexity**: {{S|M|L}}
+
+   ## Tasks
+   - [ ] Contract: {{CONTRACT_LIBRARY}} schema for [entity]
+   - [ ] `FE` [entity] page and components
+   - [ ] `BE` API endpoints for [entity]
+
+   ## Acceptance Criteria
+   - [ ] Criterion 1
+   - [ ] Criterion 2
+   - [ ] Criterion 3
+
+   ## Implementation Notes
+   <!-- Filled during /implement-slice -->
+
+   ## Files Changed
+   <!-- List of files created/modified -->
+   ```
+
+5. **Initialize memory files** (only if they don't already exist):
+   - `.memory/wiki/patterns.md` — empty with header
+   - `.memory/wiki/blockers.md` — empty with header
+   - `.memory/wiki/decisions.md` — empty with header

package/template/.pi/skills/session-continuity/protocols/03-progress-update.md

@@ -0,0 +1,116 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.agents/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Protocol 3: Progress Update
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: `/implement-slice` step 7
+
+**Purpose**: Mark completed work, release claims, and propagate status changes upward.
+
+## Steps
+
+1. **Mark tasks and acceptance criteria `[x]`** in the slice's tracking location (use the exact files in the `.memory/pipeline/progress/` directory, NEVER guess the path):
+   - If slice has its own file: update `.memory/pipeline/progress/slices/phase-NN-slice-NN.md`
+   - If inline: update `.memory/pipeline/progress/phases/phase-NN.md`
+
+2. **Release any claimed tasks** — if the completed task had `[!]`:
+   - Change status from `[/]` to `[x]`
+   - Remove the `[!]` flag from the task line
+   - Remove the `files:` block under the task (lock released)
+   ```markdown
+   # Before (during parallel work)
+   - [/] `BE` API endpoints for user profile [!]
+     - files: src/api/users/[id].ts, src/db/queries/user.ts
+     - [x] GET endpoint
+     - [x] PUT endpoint
+
+   # After (task complete)
+   - [x] `BE` API endpoints for user profile
+     - [x] GET endpoint
+     - [x] PUT endpoint
+   ```
+
+3. **Mark the slice itself `[x]`** in the phase file (only when ALL tasks are `[x]`):
+   ```markdown
+   - [x] **Slice 3**: Auth middleware (M) ✅ 2026-02-15
+   ```
+
+4. **Update phase progress** in the phase file header:
+   ```markdown
+   **Status**: in-progress
+   **Progress**: 4/7 slices
+   ```
+
+5. **Update `.memory/pipeline/progress/index.md`** — recalculate overall progress:
+   ```markdown
+   **Overall**: 12/20 slices (60%)
+   ```
+   Update the phase row's status and progress count.
+
+6. **Log implementation notes** (if slice file exists):
+   - What approach was taken
+   - Key files changed
+   - Any deviations from the plan
+
+7. **Log blockers** encountered during implementation to `.memory/wiki/blockers.md`:
+   ```markdown
+   ## Active Blockers
+
+   ### BLK-003: Redis config missing (2026-02-15)
+   - **Slice**: Phase 2, Slice 4 — Rate limiting
+   - **Impact**: Cannot implement rate limiter without Redis connection
+   - **Needs**: VPS Redis setup or config from user
+
+   ## Resolved Blockers
+
+   ### BLK-002: Firebase admin SDK version conflict (2026-02-14)
+   - **Resolution**: Pinned to v12.0.0, added to package.json overrides
+   - **Resolved**: 2026-02-14
+   ```
+
+8. **Read-back verification (mandatory — runtime-agnostic)**
+
+   After every write in steps 1–6, immediately read each file back and confirm the change landed. This mirrors Protocol 8 step 6 and is required because different agent runtimes (Claude, Antigravity, Codex, Factory) all write to the same `.memory/pipeline/progress/` tree — a silent partial write here means the next session in any runtime will resume from stale state.
+
+   For each of the four targets you wrote (slice file, phase file, index.md, plus blockers/decisions/patterns if touched):
+
+   (a) Re-read the file with a fresh read.
+   (b) Confirm the specific bytes you intended to write are present:
+       - Slice file: `**Status**: complete` line is present.
+       - Phase file: the `**Slice N**` row checkbox is `[x]`, and the `**Progress**: X/Y` header reflects the new count.
+       - `index.md`: the phase row's status and `X/Y` cell match the phase file, and `**Overall**: X/Y` is recalculated.
+   (c) If any check fails:
+       - Log: `"Progress write-back failed for [file]: expected [value], saw [actual]"`
+       - Retry the write **once**.
+       - Re-read and re-verify.
+       - If second attempt fails → **STOP**: `"Unable to update [file] after 2 attempts. Do not call notify_user. Do not advance the slice. Investigate before continuing."`
+   (d) On success, log: `"Progress write-back verified: slice/phase/index all consistent."`
+
+9. **Cross-file consistency check (mandatory — runtime-agnostic)**
+
+   Run the verifier:
+
+   ```
+   node scripts/check-progress-consistency.mjs
+   ```
+
+   (If `scripts/check-progress-consistency.mjs` does not exist in the project — for example, an older installation that has not been synced — fall back to manual cross-checking: open all three files (slice, phase, index) side-by-side and verify the slice's status, the phase's `X/Y`, and the index's overall `X/Y` are all internally consistent. Then `/sync-kit` to pull the verifier in.)
+
+   - Exit code 0 → consistent. Proceed.
+   - Exit code 1 → drift. Read the script's output, fix every reported drift item by editing the affected file(s), and re-run the script until it returns 0. **STOP and do not call `notify_user` until the script returns 0.**
+   - Exit code 2 → malformed file. The progress files are unreadable or missing required headers. **STOP**: report the malformed file and the reason; do not attempt repair without user confirmation, since malformed progress files usually indicate a deeper schema mismatch.
+
+   This check exists because checkbox edits and fraction edits are easy to forget independently. The script catches the four most common drift patterns: phase fraction ≠ checkbox count, slice file status ≠ phase row checkbox, index overall ≠ sum of phases, index per-phase row ≠ phase file. It runs in any runtime with Node available.
+
+10. **Stamp the slice with a completion signature** — append (or update) at the bottom of `slices/phase-NN-slice-NN.md`:
+
+    ```markdown
+    ## Completion Signature
+    - Completed: <ISO date>
+    - Runtime: <claude | antigravity | codex | factory | other>
+    - Verifier: check-progress-consistency.mjs exit 0
+    - Depth ratio: <ratio> (>= 1.0 required)
+    ```
+
+    The signature is what lets a different runtime opening the project later trust that the slice is genuinely done — not just that someone ticked a box.

package/template/.pi/skills/session-continuity/protocols/04-pattern-extraction.md

@@ -0,0 +1,60 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.agents/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Protocol 4: Pattern Extraction
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: End of any workflow (replaces `self-improving-agent` step)
+
+**Purpose**: Extract reusable patterns from what just happened.
+
+## Steps
+
+1. **Reflect on the task**:
+   - What happened? (summary)
+   - What worked well? (repeat this)
+   - What didn't work? (avoid this)
+   - Was there a surprise or insight?
+
+2. **Classify the pattern**:
+
+   | Classification | Criteria | Action |
+   |---------------|----------|--------|
+   | Best practice | Worked well, likely reusable | Add to patterns.md |
+   | Anti-pattern | Caused problems, should avoid | Add to patterns.md as "avoid" |
+   | Context-specific | Only applies to this situation | Log in session but don't generalize |
+   | Not significant | Routine, nothing new learned | Skip |
+
+3. **Write to `.memory/wiki/patterns.md`** (only for best-practice or anti-pattern):
+   ```markdown
+   ### PAT-007: Schema coercion for URL params (2026-02-15)
+   - **Type**: best-practice
+   - **Confidence**: 0.7 (applied 1 time)
+   - **Context**: Astro API routes receive all params as strings
+   - **Pattern**: Use `z.coerce.number()` instead of `z.number()` for URL params
+   - **Source**: Phase 2, Slice 3 implementation
+   ```
+
+4. **Update confidence on existing patterns** if reapplied:
+   - Increment `applied` count
+   - Increase confidence: `new_confidence = min(0.95, old + 0.1)`
+
+5. **Post-decision pushback** — for each decision made during this workflow
+   (logged via Protocol 6 or made implicitly), challenge it with hindsight:
+
+   - **Did it hold up?** — Did implementation confirm or undermine the reasoning?
+   - **Surprises?** — Did anything unexpected happen because of this choice?
+   - **Would you choose differently now?** — With what you learned during impl, same call?
+   - **Scope creep?** — Did the decision force unplanned work or workarounds?
+
+   If the answer to "would you choose differently" is **yes**, log it as a
+   revision candidate in `.memory/wiki/decisions.md` with the original decision ID:
+   ```markdown
+   ### DEC-004-REVIEW: Middleware decision revisited (2026-02-16)
+   - **Original**: DEC-004 — middleware over per-route auth
+   - **What changed**: Discovered 3 public routes need explicit exclusions, increasing complexity
+   - **Verdict**: Still correct, but add route-level override capability
+   - **Action**: Create follow-up slice for route exclusion config
+   ```
+
+   If no significant decisions were made during this workflow, skip this step.

package/template/.pi/skills/session-continuity/protocols/05-session-close.md

@@ -0,0 +1,37 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.agents/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Protocol 5: Session Close
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: End of session (agent should do this before signing off)
+
+**Purpose**: Write a session log so the next session can resume cleanly.
+
+## Steps
+
+1. **Create `sessions/YYYY-MM-DD.md`**:
+   ```markdown
+   # Session: 2026-02-15
+
+   ## Context
+   - Resumed from: Phase 2, Slice 3
+   - Goal for session: Implement auth middleware + rate limiting
+
+   ## Accomplished
+   - [x] Phase 2, Slice 3 — Auth middleware (complete)
+   - [x] Phase 2, Slice 3a — Token refresh logic (complete)
+
+   ## Deferred
+   - [ ] Phase 2, Slice 4 — Rate limiting (blocked on Redis config)
+
+   ## Patterns Learned
+   - PAT-007: Schema coercion for URL params
+
+   ## Next Session
+   - Resolve BLK-003 (Redis config)
+   - Start Phase 2, Slice 4 if unblocked
+   - Otherwise skip to Phase 2, Slice 5
+   ```
+
+2. **If a session log for today already exists**, append to it (don't overwrite).

package/template/.pi/skills/session-continuity/protocols/06-decision-analysis.md

@@ -0,0 +1,84 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.agents/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Protocol 6: Decision Effect Analysis
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: Any moment a non-trivial decision needs to be made
+
+**Purpose**: Two-pass deliberation — the Philosopher explores, the Analyst
+stress-tests. Same questions, different lenses. They loop until they agree.
+No code is written until convergence.
+
+## Triage: Should This Protocol Be Invoked?
+
+**Does this decision have upstream or downstream effects?**
+
+- **Isolated** (UI element shape, variable name, test structure) → **Skip**. Just decide.
+- **Has ripple effects** (touches other components, changes contracts, affects data
+  flow, sets precedent) → **Invoke**.
+
+Rule of thumb: if changing this later requires editing more than the current file,
+it has ripple effects.
+
+## Pass 1: The Philosopher
+
+1. **What are the project's established guidelines and protocols for this?**
+   Read the relevant rules, instructions, specs, and existing patterns.
+
+2. **What are the different ways to accomplish this within those guidelines?**
+   List at least 3 viable approaches (forcing function against first-idea bias).
+
+3. **What are the pros and cons of each?**
+   Be specific — name concrete trade-offs, not vague qualities.
+
+4. **Which one is the clear winner and why?**
+   State the recommendation with reasoning.
+
+## Pass 2: The Devil's Advocate
+
+Take the Philosopher's recommendation and **try to find flaws in it**:
+
+1. **What are the project's established guidelines and protocols for this?**
+   Did the Philosopher miss any? Misinterpret any?
+
+2. **What are the different ways to accomplish this within those guidelines?**
+   Review the options the Philosopher considered. Did they overlook any?
+
+3. **What are the pros and cons of each?**
+   Did the Philosopher underweight a con or overweight a pro?
+   Are there hidden costs they didn't surface?
+
+4. **Do I agree with the Philosopher's recommendation, or is there a better way?**
+   - **If agree** → proceed to Record step
+   - **If disagree** → state what's better and why, then **push findings back
+     to the Philosopher** for another pass
+
+## Convergence Loop
+
+If the Devil's Advocate disagrees, the Philosopher reviews those findings and
+re-evaluates. The Devil's Advocate then scrutinizes again. **Repeat until both
+agree.**
+
+They are twins with different jobs — the Philosopher explores and proposes,
+the Devil's Advocate stress-tests and finds flaws. Together they catch blind spots.
+
+## Record
+
+Once converged, write to `.memory/wiki/decisions.md`:
+```markdown
+### DEC-004: Use middleware over per-route auth (2026-02-15)
+- **Problem**: 12+ routes need identical auth enforcement
+- **Guidelines checked**: security-first rule, extensibility rule, DRY principle
+- **Options considered**: Per-route checks, middleware, decorator pattern
+- **Decision**: Middleware — single enforcement point
+- **Philosopher reasoning**: DRY, single place to enforce and audit
+- **Devil's Advocate concurrence**: Agreed — per-route is a security risk (forgotten routes)
+- **Upstream**: Depends on Firebase Admin SDK token verification
+- **Downstream**: All future routes auto-protected; public routes need opt-out
+- **Reversibility**: Medium — mechanical but touches every route file
+```
+
+## Proceed
+
+The decision is justified, stress-tested, and recorded. Implement it.

package/template/.pi/skills/session-continuity/protocols/07-spec-pipeline-generation.md

@@ -0,0 +1,48 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.agents/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Protocol 7: Spec Pipeline Generation
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: `/decompose-architecture` (after creating indexes)
+
+**Purpose**: Create a spec pipeline tracker so you always know which shards
+have IA specs, BE specs, and FE specs completed.
+
+## Steps
+
+1. **Read the IA index** — `.memory/wiki/specs/ia/index.md` — to get the list of shards.
+
+2. **Create `.memory/pipeline/progress/spec-pipeline.md`**:
+   ```markdown
+   # Spec Pipeline Progress
+
+   **Project**: {{PROJECT_NAME}}
+   **Last updated**: {{DATE}}
+   **Overall**: 0/{{N×3}} specs (0%)
+
+   ## Legend
+
+   | Symbol | Meaning |
+   |--------|---------|
+   | `not-started` | No spec file exists yet |
+   | `skeleton` | Skeleton file exists but sections are placeholder only |
+   | `complete` | Spec file exists with all sections filled and approved |
+
+   ## Shard Spec Status
+
+   | # | Shard | File | IA Spec | BE Spec | FE Spec |
+   |---|-------|------|---------|---------|---------|
+   | 00 | {{shard-name}} | `.memory/wiki/specs/ia/00-{{shard-name}}.md` | skeleton | not-started | not-started |
+   | 01 | {{shard-name}} | `.memory/wiki/specs/ia/01-{{shard-name}}.md` | skeleton | not-started | not-started |
+   | ... | ... | ... | ... | ... | ... |
+
+   ## Spec Completion Tracking
+
+   Shards with all three specs complete (tracking only — /plan-phase requires ALL shards to be complete, not just individual ones):
+   - (none yet)
+   ```
+
+   > The `File` column is populated with the expected file path at generation time (derived from the shard number and domain name). Downstream protocols use this path to verify file existence before marking a spec as `complete`.
+
+3. **Initialize memory files** if they don't exist (same as Protocol 2, step 5).

package/template/.pi/skills/session-continuity/protocols/08-spec-pipeline-update.md

@@ -0,0 +1,65 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.agents/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Protocol 8: Spec Pipeline Update
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: `/write-architecture-spec`, `/write-be-spec`, `/write-fe-spec`
+(after updating the layer index)
+
+**Purpose**: Mark a spec column done and report pipeline progress.
+
+## Steps
+
+1. **Identify the shard and layer** — which shard just got its spec completed,
+   and which layer (IA, BE, or FE)?
+
+2. **Update `.memory/pipeline/progress/spec-pipeline.md`** — before updating any cell, perform these validation checks:
+
+   (a) Read the `File` column for the shard from the tracker to get the expected file path.
+   (b) Confirm the file exists at that path. If not → **skip the update** and report: `"Cannot mark [shard] [layer] as complete — file not found at [path]"`
+   (c) Read the file and confirm it contains no skeleton placeholder markers (`[To be filled`, `<!-- TODO -->`, `Status: Skeleton`). If any are present → **skip the update** and report: `"Cannot mark [shard] [layer] as complete — skeleton placeholders remain in [path]: [list of markers found]"`
+   (d) Only on all-pass: update the column to `complete`:
+   ```markdown
+   | 03 | user-profiles | `.memory/wiki/specs/ia/03-user-profiles.md` | complete | complete | not-started |
+   ```
+   (e) On any failure: skip the update and report the exact path and failure reason.
+
+3. **Recalculate overall progress**:
+   ```markdown
+   **Overall**: 8/45 specs (18%)
+   ```
+
+4. **Update "Spec Completion Tracking"** — if a shard now has all three specs
+   complete (IA ✅ + BE ✅ + FE ✅), add it to the completion tracking list. Note: /plan-phase requires ALL shards to be complete, not just this one.
+   ```markdown
+   ## Spec Completion Tracking
+
+   Shards with all three specs complete (tracking only — /plan-phase requires ALL shards to be complete, not just individual ones):
+   - ✅ Shard 00: API conventions
+   - ✅ Shard 01: Authentication
+   ```
+
+5. **Report status** — log what was completed and what's next.
+
+6. **Read-back verification** — immediately after updating the tracker:
+
+   (a) Read `.memory/pipeline/progress/spec-pipeline.md` back.
+   (b) Locate the row for the shard that was just updated.
+   (c) Verify the column that was just marked shows `complete` (not `not-started`, not unchanged, not any other value).
+   (d) If the cell does NOT show `complete`:
+       - Log: `"Pipeline tracker write-back failed for shard [NN] [layer] column — cell still shows [current value]"`
+       - Retry the write once.
+       - Read back and re-verify.
+       - If second attempt fails → **STOP**: `"Unable to update spec-pipeline.md for shard [NN] [layer] after 2 attempts. Do not proceed — investigate before continuing."`
+   (e) On success: log `"Pipeline tracker verified: shard [NN] [layer] = complete"`
+
+7. **Refresh the spec graph** — after tracker verification succeeds:
+
+   (a) Call the `memory_compile` MCP tool to rebuild derived memory artifacts from current spec truth.
+   (b) Confirm the compile succeeded and reported graph outputs (`specGraphNodes`, `specGraphEdges`).
+   (c) Treat this compile as mandatory before reporting the workflow complete.
+   (d) This is the primary graph-freshness path for spec-writing workflows; the Stop hook remains the session-end backstop.
+   (e) Because the graph is rebuilt from source specs, corrections/removals must be allowed to delete stale edges on this compile pass.
+
+8. **Report status** — log what was completed and what's next.