@mmerterden/multi-agent-pipeline 10.0.6 → 10.2.0

package/pipeline/scripts/validate-state.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// validate-state.mjs  -  resume-safety check for agent-state.json.
+//
+// agent-state.json is the canonical per-run state read by every phase. A
+// half-written or corrupt state (crash mid-write, truncated JSON, missing
+// currentPhase) makes resume silently re-enter the wrong phase. Phase 0 and
+// resume run this before trusting the file.
+//
+// This is deliberately a RESUME-SAFETY check, not strict conformance to
+// pipeline/schemas/agent-state.schema.json. Real state files written by older
+// pipeline versions omit schemaVersion, use a string shortId ("#2"), and write
+// status "completed" - they are still perfectly resumable, so rejecting them
+// here would break every legacy resume. We fail only on the conditions that
+// actually make a resume unsafe:
+//   - the file does not parse (truncated / corrupt)
+//   - root is not an object
+//   - currentPhase is missing or out of the 0..7 range (resume keys on it)
+//   - phases is present but not an object, or an entry is not an object
+// Phase status strings are NOT enum-checked: real writers use "completed"
+// alongside the schema's "done", and an odd status does not make a resume
+// unsafe (resume keys on currentPhase, not phase status). Zero deps, same
+// style as the other validators.
+//
+// Usage:
+//   node validate-state.mjs path/to/agent-state.json
+//   cat agent-state.json | node validate-state.mjs -
+//
+// Exit codes:
+//   0  -  safe to resume
+//   1  -  unsafe: unparseable, or missing/invalid currentPhase, or malformed phases
+//  64  -  usage error
+
+import { readFileSync } from "node:fs";
+
+function readInput() {
+  const arg = process.argv[2];
+  if (!arg) {
+    console.error("usage: validate-state.mjs <path|->");
+    process.exit(64);
+  }
+  if (arg === "-") {
+    const chunks = [];
+    process.stdin.setEncoding("utf-8");
+    return new Promise((resolve) => {
+      process.stdin.on("data", (c) => chunks.push(c));
+      process.stdin.on("end", () => resolve(chunks.join("")));
+    });
+  }
+  return Promise.resolve(readFileSync(arg, "utf-8"));
+}
+
+async function main() {
+  const raw = await readInput();
+  let s;
+  try {
+    s = JSON.parse(raw);
+  } catch (err) {
+    emit({ ok: false, code: 1, errors: [`invalid JSON: ${err.message}`] });
+    process.exit(1);
+  }
+
+  const errors = [];
+
+  if (typeof s !== "object" || s === null || Array.isArray(s)) {
+    emit({ ok: false, code: 1, errors: ["root must be an object"] });
+    process.exit(1);
+  }
+
+  // currentPhase is the field resume keys on - it must be present and in range.
+  if (!Number.isInteger(s.currentPhase) || s.currentPhase < 0 || s.currentPhase > 7) {
+    errors.push(`currentPhase must be integer 0..7, got ${JSON.stringify(s.currentPhase)}`);
+  }
+
+  // phases is optional (some early/aborted states omit it), but if present it
+  // must be a well-formed map so sub-step resume can read it.
+  if (s.phases !== undefined) {
+    if (typeof s.phases !== "object" || s.phases === null || Array.isArray(s.phases)) {
+      errors.push("phases, when present, must be an object keyed by phase number");
+    } else {
+      for (const [k, v] of Object.entries(s.phases)) {
+        if (!/^[0-7]$/.test(k)) {
+          errors.push(`phases key invalid: "${k}" (expected "0".."7")`);
+          continue;
+        }
+        if (typeof v !== "object" || v === null) {
+          errors.push(`phases["${k}"] must be an object`);
+        }
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    emit({ ok: false, code: 1, errors });
+    process.exit(1);
+  }
+
+  emit({ ok: true, code: 0, errors: [] });
+  process.exit(0);
+}
+
+function emit(result) {
+  process.stdout.write(JSON.stringify(result) + "\n");
+}
+
+main().catch((err) => {
+  emit({ ok: false, code: 1, errors: [`unhandled: ${err.message}`] });
+  process.exit(1);
+});

package/pipeline/scripts/write-state.mjs

@@ -20,8 +20,13 @@
  * Exit codes:
  *   0  -  write succeeded
  *   1  -  invalid JSON on stdin
- *   2  -  lock timeout (another writer held the lock >5s)
+ *   2  -  lock timeout (another writer held the lock past the acquire window)
  *   3  -  I/O error (disk full, permission denied, parent dir missing)
+ *
+ * Tunables (env):
+ *   WRITE_STATE_LOCK_TIMEOUT_MS  acquire window before exit 2 (default 15000)
+ *   WRITE_STATE_LOCK_STALE_MS    age past which a lock is reclaimed (default 30000)
+ * A dead holder (PID no longer alive) is reclaimed immediately regardless of age.
  */
 
 import {
@@ -65,9 +70,9 @@ function parseArgs() {
  * @param {number} timeoutMs
  * @returns {Promise<void>}
  */
-async function acquireLock(path, timeoutMs = 5000) {
+async function acquireLock(path, timeoutMs = Number(process.env.WRITE_STATE_LOCK_TIMEOUT_MS) || 15_000) {
   const lockPath = `${path}.lock`;
-  const staleMs = 60_000;
+  const staleMs = Number(process.env.WRITE_STATE_LOCK_STALE_MS) || 30_000;
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     try {
@@ -89,7 +94,13 @@ async function acquireLock(path, timeoutMs = 5000) {
       await new Promise((r) => setTimeout(r, 50));
     }
   }
-  throw Object.assign(new Error(`lock timeout on ${lockPath}`), { code: "LOCK_TIMEOUT" });
+  throw Object.assign(
+    new Error(
+      `lock timeout on ${lockPath} after ${timeoutMs}ms. If no other writer is running, ` +
+        `the lock is stale  -  remove it (rm "${lockPath}") and retry, or raise WRITE_STATE_LOCK_TIMEOUT_MS.`,
+    ),
+    { code: "LOCK_TIMEOUT" },
+  );
 }
 
 /**

package/pipeline/skills/figma-common/README.md

@@ -2,7 +2,7 @@
 
 Shared skills that both `pipeline/skills/figma-ios/` (SwiftUI) and `pipeline/skills/figma-android/` (Jetpack Compose) dispatch. Moved here by WS-7b of the v5.0.0 rebuild so the platform trees stay lean and there's no duplication.
 
-## What lives here (27 skills)
+## What lives here (31 skills)
 
 **Workflow orchestration:**
 
@@ -28,6 +28,7 @@ Shared skills that both `pipeline/skills/figma-ios/` (SwiftUI) and `pipeline/ski
 - `figma-validate`  -  Pre-implementation validation
 - `figma-fix`  -  Targeted bug fix from review findings
 - `figma-mend`  -  Re-implement component from scratch
+- `figma-evolve-component`  -  Reconcile drift + additively extend an existing component (human-gated)
 
 **Setup + utility:**
 
@@ -38,6 +39,12 @@ Shared skills that both `pipeline/skills/figma-ios/` (SwiftUI) and `pipeline/ski
 - `figma-form-integration`  -  Form protocol adapter (shared UX)
 - `figma-price-integration`  -  Price protocol adapter (shared UX)
 
+**Cross-cutting interaction adapters (native-SwiftUI-first; project system via `figma-config` `ui.*`):**
+
+- `figma-navigation`  -  Navigation pattern: headless Output vs self-route; native `NavigationStack` or `ui.navigationSystem`
+- `figma-overlays`  -  Overlay pattern: toast/HUD/alert/data-modal; native `.alert`/`.sheet(item:)` or `ui.overlaySystem`
+- `figma-bottom-sheets`  -  Bottom-sheet/detent pattern: native `.presentationDetents` or `ui.sheetSystem`
+
 **Performance batch:**
 
 - `performance-start`, `performance-swiftui`, `performance-tour`, `performance-review-next`, `performance-iteration-commit-all`

package/pipeline/skills/figma-common/figma-bottom-sheets/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: figma-bottom-sheets
+description: "Bottom-sheet / detent pattern integration for Figma-to-SwiftUI components — half-sheets, drawers, pinned bottom CTAs, resizable pull-up panels, content-sized sheets, and multi-step in-sheet flows. Native SwiftUI (.sheet + presentationDetents/dragIndicator/backgroundInteraction) by default; an optional project-supplied detent-sheet system when figma-config declares one. Reach for this when a design shows a bottom sheet, half-sheet, bottom drawer, snap points, a sticky footer button, or a wizard-in-a-sheet."
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+status: wip-v5
+sourced-from: upstream/figma-bottom-sheets
+---
+
+# /figma-bottom-sheets  -  Bottom-Sheet / Detent Pattern Integration
+
+## Purpose
+
+Consumed by the figma-to-swiftui pipeline (Phase 3D detection, Phase 4B view) and available ad-hoc, this skill defines how **bottom-anchored, detent-based surfaces** are presented. Sibling of `/figma-overlays` (transient/blocking overlays) and `/figma-navigation` (routing): native-SwiftUI default + a config-driven hook for projects that ship a custom detent-sheet engine.
+
+**Generic by design.** Default is stock SwiftUI `.sheet` + `.presentationDetents`. If `figma-config.json` declares `ui.sheetSystem`, route through that engine by name  -  same rules, project vocabulary. (Some apps replace system sheets because iOS 26 forces a Liquid-Glass floating inset on partial detents with no removal API; that replacement is the custom-system case, not the default.)
+
+---
+
+## Strict Rules (non-negotiable)
+
+1. **The sheet surface is a caller concern; the component is the content.** A reusable component authored from Figma is the sheet's **content**, not the presenter. The caller owns the `isPresented`/`item` binding and the detents. A component that presents itself can't be reused elsewhere.
+2. **No magic numbers.** Detents, corner radius, grabber size, insets come from tokens / figma-config token patterns, never hard-coded literals.
+3. **Detents ascend, max 3.** Pass `[detent]` lowest→highest; the sheet opens at the lowest. Prefer semantic detents (`.medium`, `.large`, `.fraction`, content-height) over pixel heights where possible.
+4. **A bottom sheet is not a modal card and not a navigation push.** Data alert/modal card → `/figma-overlays`; screen routing → `/figma-navigation` (a routed modal may still *render* as a sheet, but navigation owns the routing).
+5. **Native SwiftUI is the default; a custom sheet engine is opt-in via config.** Only use a project detent-sheet system when `ui.sheetSystem.mode == "custom"`.
+
+---
+
+## When to Invoke This Skill
+
+1. **Phase 3D  -  sheet affordance/pattern:** the design is (or contains) a bottom sheet / half-sheet / drawer, a **pinned bottom CTA** bar, a resizable pull-up panel, a **content-sized** sheet, or a **multi-step** in-sheet flow (in-sheet back/next that resizes per step).
+2. **Phase 4B  -  View:** the view is authored as sheet content, or presents a child as a sheet.
+3. **Ad-hoc:** "half sheet", "bottom drawer", "pull-up panel", "snap points", "sticky footer button", "multi-step sheet", "sheet sized to its content".
+
+**Not a bottom sheet (guards):**
+- Toast / HUD / alert / data modal card → `/figma-overlays`.
+- Full screen navigation / tab / deep link → `/figma-navigation`.
+- An inline expandable section within the page flow (not an anchored surface) → plain component content.
+
+---
+
+## Native-first architecture (default)
+
+```
+Caller
+    |  owns isPresented / item + detents; presents the component as content
+    v
+.sheet(item:/isPresented:) {
+    ComponentContent()                    // the Figma-authored component
+      .presentationDetents([.medium, .large])
+      .presentationDragIndicator(.visible)
+      .presentationBackgroundInteraction(.enabled(upThrough: .medium))  // passthrough-ish
+      .presentationCornerRadius(<token>)
+}
+```
+
+- **Half / expandable:** `.presentationDetents([.medium, .large])` or `[.fraction(0.25), .fraction(0.6), .large]`.
+- **Content-sized:** `.presentationDetents([.height(measuredHeight)])` using a height read via a preference key (a `sizeThatFits`/`GeometryReader` measured content height), then scroll past the cap.
+- **Pinned bottom CTA (part of the screen, not a modal):** `.safeAreaInset(edge: .bottom) { CTA() }`  -  reserves space, screen stays interactive. This is NOT a presented sheet.
+- **Backdrop behavior:** dim+block is the `.sheet` default; passthrough/interactive-behind uses `.presentationBackgroundInteraction(.enabled(...))`.
+- **Multi-step in-sheet flow:** drive a `NavigationStack(path:)` *inside* the sheet content for push/pop, resizing detents per step; each step is a headless view emitting `Output` (see `/figma-navigation`). If the target project's custom engine forbids a nested `NavigationStack`, use its engine (config hook).
+- **Overlays over a sheet:** mount the toast/HUD host on the sheet content (`/figma-overlays`), not the root.
+
+Tokens per `reference/ui` + figma-config token patterns.
+
+## Config hook  -  project-supplied detent-sheet engine
+
+When `figma-config.json` declares:
+```jsonc
+"ui": { "sheetSystem": {
+  "mode": "custom",
+  "brandedModifier": "bottomSheet",       // .bottomSheet(isPresented:title:) branded entry
+  "headlessModifiers": ["modalSheet", "dockedSheet", "expandableSheet", "detentNavigationSheet"],
+  "detentType": "SheetDetentType",         // detent enum
+  "backdropType": "Backdrop",              // backdrop enum
+  "cornerRadiusToken": ".Radius.n12"       // branded top-corner token
+}}
+```
+apply the SAME rules via the project's engine (names from config, do NOT hardcode):
+- Use `.{brandedModifier}` for product sheets needing brand chrome; the headless modifiers for unbranded surfaces / CTAs / resizable panels / multi-step flows.
+- Detents/backdrops use `{detentType}`/`{backdropType}` values; corner radius from `{cornerRadiusToken}`.
+- Multi-step flows use the engine's navigation sheet (e.g. `detentNavigationSheet` with a `Navigator<Route>`) rather than a raw nested `NavigationStack`.
+- One container-owned grabber (pass custom headers grabberless if the engine draws the grabber).
+- Present only from the surface's own host  -  never walk the scene/window hierarchy for a "top" controller.
+
+If `mode` is absent or `native`, use the native-first section.
+
+---
+
+## Integration with Phase 3D
+
+Record in `04b_component_architecture.md`:
+
+```markdown
+## Bottom Sheet
+| Signal | Surface | Detents | Owner |
+|---|---|---|---|
+| Half-sheet picker | presented sheet | [.medium, .large] | caller owns isPresented |
+| Sticky "Devam Et" bar | pinned bottom CTA | n/a (safeAreaInset) | part of screen |
+| 3-step add flow | multi-step in-sheet | per-step (content height) | caller drives path |
+```
+
+Property classification addition:
+
+| Classification | When | Swift Pattern |
+|---|---|---|
+| Sheet content | Component is authored to live inside a sheet | plain component; caller adds `.presentationDetents(...)` |
+| Present-child-as-sheet | Component reveals a child surface | caller-owned `isPresented`/`item` + `.sheet` (component emits the trigger intent) |
+| Pinned CTA | Sticky bottom action bar | `.safeAreaInset(edge:.bottom)` at the screen, not a modal |
+
+## Integration with Phase 4B
+- Author the component as sheet **content**; let the caller own presentation + detents.
+- Prefer semantic detents; content-sized sheets measure height via a preference key.
+- Pinned CTA = `.safeAreaInset(edge:.bottom)`, not a presented sheet.
+- Multi-step flow = `NavigationStack` inside the sheet (native) or the engine's nav sheet (custom).
+- If `ui.sheetSystem.mode == custom`, use `{brandedModifier}`/headless modifiers + `{detentType}`/`{backdropType}` per config.
+- Verify on the simulator across detents, backdrop, and drag/dismiss on the project's min + current iOS.
+
+---
+
+## When NOT to Use Bottom-Sheet Integration
+- Toast/HUD/alert/data modal card → `/figma-overlays`.
+- Screen routing/tabs/deep links → `/figma-navigation`.
+- An inline expandable/disclosure within page flow → plain component content.
+
+## Checklist  -  Before Leaving the Skill
+```
+[ ] Component is sheet CONTENT; caller owns isPresented/item + detents
+[ ] Detents ascend, max 3; semantic detents preferred; no magic-number heights
+[ ] Pinned CTA uses safeAreaInset(edge:.bottom), not a presented sheet
+[ ] Content-sized sheet measures height via preference key, then scrolls
+[ ] Multi-step flow uses NavigationStack-in-sheet (native) or engine nav sheet (custom)
+[ ] Corner radius / grabber / insets from tokens, not literals
+[ ] Default native SwiftUI; custom engine only when figma-config ui.sheetSystem.mode == custom
+[ ] Overlays over the sheet mount on the sheet content surface
+```

package/pipeline/skills/figma-common/figma-evolve-component/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: figma-evolve-component
+description: "On-demand reconcile-and-extend for an ALREADY-implemented SwiftUI component. Heals drift from current Figma (stale variants/props/structure, design-token drift, a detached/overridden deviation) AND extends the component non-destructively to cover a need the design can't express — always behind a mandatory human gate. Reach for this when an existing component drifted from its current design or doesn't cover a need. Not for building from scratch (figma-to-swiftui / figma-mend) or fixing one review bug (figma-fix)."
+user-invocable: true
+argument-hint: <component | figma-url> [--report-only]
+allowed-tools: Task, Read, Glob, Grep, Bash, Edit, Write, AskUserQuestion
+status: wip-v5
+sourced-from: upstream/figma-evolve-component
+---
+
+# /figma-evolve-component  -  reconcile & extend an existing component
+
+> **Use when:** an existing UI component drifted from its current Figma design, OR it doesn't cover a need you now have.
+> **Don't use when:** building a brand-new component → `figma-to-swiftui`; re-implementing a discarded component from scratch → `figma-mend`; fixing a single bug filed in review → `figma-fix`.
+
+## Scope
+Reconcile **one** existing component against current Figma and extend it for a real need, then propagate the change to its Code Connect mapping + docs + wiki. **Out:** new components, networking, navigation graphs, batch/all-component sweeps.
+
+## Invariants
+- **Two truths.** Design is truth for **heal** (drift); **the user** is truth for **extend** (a need/divergence design can't supply). Design cannot tell us which gap to close  -  the user does.
+- **Human gate is mandatory.** Never write before the user's decisions (Procedure step 3). This is prompt-driven, not autonomous. `--report-only` stops after the diff.
+- **Additive / non-destructive.** Preserve the public API, init signatures, and variant cases. Never remove or rename them without explicit confirmation  -  it breaks callers.
+- **Detached / overridden node = suspect truth.** If the Figma node is a detached instance or has local overrides, surface it and reconcile against the **main** component  -  don't auto-heal toward a deviated instance.
+- **Recorded divergences are respected.** A `// evolve-keep: <reason>` marker in the code means the audit skips it and apply never reverts it.
+- **Not done until it builds + existing call sites still compile + tests/snapshots pass** (`figma-to-swiftui` Phase 5 / `reference/build-and-test`).
+
+## Conventions & golden paths (point, don't re-implement)
+- **Design truth** → `/figma-utility` (`properties`, `tokens`, `context`, `metadata`, `screenshot`, `code-connect`). Analysis phase only  -  same MCP/REST rules as the pipeline.
+- **Locate the component + its Figma node** → `FigmaRegistryUtility` lookup / repo grep for the `{ComponentName}` files and its `*.figma.swift`, or a URL the user gives. Paths resolve from `figma-config.json` (`repos.*`, component roots)  -  never hardcode.
+- **Component structure + tokens** → `reference/ui` (`figma-to-component/reference/`), `figma-to-swiftui-effects.md`, `macros.md`. Cross-cutting patterns → `/figma-ui-patterns`, `/figma-form-integration`, `/figma-price-integration`, `/figma-navigation`, `/figma-overlays`, `/figma-bottom-sheets`.
+- **After any prop/variant change, regenerate the derived artifacts  -  don't hand-roll:** Code Connect → `figma-to-component` Phase 6; local `.figma.md` doc → Phase 4C / `figma-component-docs`; public wiki → Phase 7 / `figma-component-wiki`.
+- Build/run/test gate → `reference/build-and-test`; ship → `figma-commit` / `figma-iteration-commit`.
+
+## Decision rules  -  classify each finding heal / extend / keep
+- **stale** — variant/prop/structure differs from current Figma → **heal** toward design.
+- **token drift** — hardcoded or old color/spacing/typography/radius vs the current token → **heal** to the current token (resolve the token name via the registry / `reference/ui`; don't guess).
+- **detached / override** — node deviates from its main → **stop, ask the user** which is truth.
+- **coverage gap** — design doesn't cover the need, or the impl is wrong → **extend**; the user says what to add.
+- Removing/renaming public API or a variant case is **never** automatic → explicit confirmation.
+
+## Procedure (the gate is non-negotiable)
+1. **Resolve & gather** — locate the component file(s) + its Figma node (registry / Code Connect map / user URL). Pull design truth via `/figma-utility`.
+   - If the node is unresolved, or **detached/overridden** → ask the user (which node is truth?).
+2. **Diff & present** — list findings per drift axis, each tagged **heal / extend / keep**. **No writes.** (`--report-only` stops here.)
+3. **GATE — user decides** (`AskUserQuestion`): which to heal, which to keep (→ add `// evolve-keep:` marker), what to extend (the need design can't supply). Do not proceed without this.
+4. **Apply** — only the approved changes, additively / non-destructively. When healing token drift, resolve the current token name via the registry / `reference/ui`  -  don't guess it.
+5. **Propagate** — regenerate Code Connect (Phase 6), the local `.figma.md` doc (Phase 4C), and the wiki page (Phase 7) for the changed props/variants. If keys changed (testing/loc/a11y/analytics), update them through the normal utility path.
+6. **Verify** — build + snapshot/preview; confirm existing call sites still compile (no API break); run affected tests.
+
+## Verification
+Build (project scheme from figma-config) + snapshot/preview render; callers compile; Code Connect + `.figma.md` + wiki reflect the new props/variants.
+
+## Pitfalls
+- Applying without the step-3 gate  -  this skill is human-gated by design.
+- Healing toward a detached/overridden node (deviated truth).
+- Removing/renaming a variant or init param → breaks callers; stay additive.
+- Skipping Propagate → Code Connect + docs silently go stale after a prop/variant change.
+
+## Escape hatches
+- Build new from scratch → `figma-to-swiftui`. Re-implement a discarded component → `figma-mend`. Fix one review bug → `figma-fix`.
+- Just fetch design data → `/figma-utility`. Build/test → `reference/build-and-test`. Commit/PR → `figma-commit`.

package/pipeline/skills/figma-common/figma-navigation/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: figma-navigation
+description: "Navigation pattern integration for Figma-to-SwiftUI components. Guides how a component reaches other screens, tabs, or deep links without coupling to a router — headless screens that emit a typed Output, native NavigationStack/navigationDestination by default, an optional project-supplied navigation system (router + route enum + scene container) when figma-config declares one. Reach for this when a design embeds a tab bar, nav bar / back button, a push/detail affordance, or a deep-link entry point."
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+status: wip-v5
+sourced-from: upstream/figma-navigation
+---
+
+# /figma-navigation  -  Navigation Pattern Integration
+
+## Purpose
+
+Consumed by the figma-to-swiftui pipeline (Phase 3D pattern detection, Phase 4B view implementation) and available for ad-hoc/vibe-coding, this skill defines how a component participates in navigation **without owning routing**. It is the navigation counterpart of `/figma-form-integration` and `/figma-price-integration`: a cross-cutting integration with a **native-SwiftUI default** and a **config-driven hook** for projects that ship their own navigation system.
+
+**Generic by design.** Nothing here assumes a specific app. The default is stock SwiftUI (`NavigationStack`, `navigationDestination`, `.toolbar`, `.sheet`). If the target project declares a custom navigation system in its `figma-config.json` (`ui.navigationSystem`), this skill routes to that system's types by name instead — same rules, project-specific vocabulary.
+
+---
+
+## Strict Rules (non-negotiable)
+
+1. **A component never names a route, a sibling screen, or a router.** A component/screen takes its arrival data as init params and emits intent through a typed **`Output`** closure (`onSelect`, `onSubmit`, `output:`). The *caller* (scene/coordinator/parent) maps each output to a navigation edge. This keeps the component reusable and testable in isolation.
+2. **No navigation side effects inside a component body.** No `NavigationLink(destination:)` hardcoding a concrete next screen, no router calls, no global singletons touched from `body`. Navigation is a caller concern expressed via the emitted output.
+3. **Selection/tab state is observable data, not an imperative bridge.** A selected tab/section is a bound value (`@Binding`/observable), written by the caller; the component reflects it. A selection set before the container mounts is simply rendered on appear  -  no cold-start race.
+4. **Deep links reduce to state and never crash.** A URL parses to a plan/value; malformed input is dropped (logged, no trap). The component is never the deep-link parser  -  it only exposes the entry state the parser can set.
+5. **Native SwiftUI is the default; a custom system is opt-in via config.** Do NOT invent a bespoke router for a project that hasn't asked for one. Only use custom navigation types when `ui.navigationSystem.mode == "custom"` is set in `figma-config.json`.
+
+---
+
+## When to Invoke This Skill
+
+Invoke when ANY of these are detected in the design or task:
+
+1. **Phase 3D  -  navigation sub-component / affordance:** a nested instance of a navigation-capable design element:
+   - Tab bar / segmented section switcher that changes the top-level view
+   - Navigation bar / header with a **back button** or close affordance
+   - A row/card whose variant implies a **push/detail** affordance (chevron, "Detaylar", disclosure)
+   - A link/button whose label implies leaving the screen ("Devam", "Tümünü gör")
+   - A deep-link entry point (the design is a landing surface reached by URL)
+2. **Phase 4B  -  View:** the view renders a back button, tab strip, or a control that should navigate.
+3. **Ad-hoc:** wiring a screen's push/pop/tab/deep-link flow outside the full pipeline.
+
+**Not navigation (false-positive guards):**
+- A segmented control that filters in-place (no screen change) → plain `Binding<Enum>`, not navigation.
+- A button that submits a form → that's `/figma-form-integration`; the *result* may navigate, but the control is a form action.
+- A modal card of data / a toast / a loading HUD → `/figma-overlays`. A bottom sheet surface → `/figma-bottom-sheets`.
+
+---
+
+## Native-first architecture (default)
+
+```
+Parent / Scene (caller)
+    |  owns NavigationStack(path:) or tab Binding, maps Output → edge
+    v
+ComponentView
+    |  init(arrivalData…, output: @escaping (Output) -> Void)
+    |  emits .selected(id) / .continue / .back  -  never routes
+    v
+(caller) path.append(route)  |  selectedTab = .x  |  present(.sheet)
+```
+
+- **Push/pop within a flow:** caller owns `NavigationStack(path:)`; component emits `Output`; caller appends a `Hashable` route; `navigationDestination(for:)` renders it.
+- **Back button:** prefer the system back button. A custom header back affordance emits `.back` (or calls `dismiss`); it renders only when there is something to pop (depth > 0 / `isPresented`).
+- **Tabs:** `TabView(selection:)` bound to an observable selection the caller owns; the component reads/writes the binding, never a global.
+- **Deep links:** caller parses URL → a `Hashable` route / tab selection and applies it to the same path/selection state the UI already uses. Component only exposes the entry state.
+- **Modal presentation of another screen:** `.sheet(item:)` / `.fullScreenCover(item:)` driven by caller state (data-driven, no `AnyView`). A *bottom sheet surface* is `/figma-bottom-sheets`; an *alert/data modal card* is `/figma-overlays`.
+
+Design tokens (spacing, colors, typography) follow `reference/ui` + the project's figma-config token patterns  -  never raw literals.
+
+## Config hook  -  project-supplied navigation system
+
+When `figma-config.json` declares:
+```jsonc
+"ui": { "navigationSystem": {
+  "mode": "custom",
+  "router": "AppRouter",            // type that dispatches routes
+  "routeEnum": "AppRoute",          // exhaustive cross-surface route enum
+  "sceneType": "SceneContent",      // headless screen container (optional)
+  "navigatorProtocol": "NavigatorProtocol"  // DI'd selection/present API (optional)
+}}
+```
+then apply the SAME rules, but express them in the project's vocabulary resolved from config (do NOT hardcode the names below  -  read them from `ui.navigationSystem`):
+
+- Wrap screen content in `{sceneType}` (headless container) instead of a bare `NavigationStack` child, when provided.
+- Screens still emit a typed `Output`; the domain coordinator maps outputs to the project's route type (`{routeEnum}`) and the `{router}` dispatches.
+- Cross-surface jumps go through the DI'd `{navigatorProtocol}` (`selectTab`, `present`), never by importing a sibling domain.
+- Deep links build the project's `{routeEnum}` case and hand it to the router's deep-link entry.
+
+If `mode` is absent or `native`, use the native-first section above. Resolve types via `tools/resource-utility` / repo grep only when the config points at real files.
+
+---
+
+## Integration with Phase 3D
+
+When Phase 3D detects a navigation affordance, record it in `04b_component_architecture.md` and classify it as an **Output**, not a route:
+
+```markdown
+## Navigation
+| Affordance | Emits | Caller maps to |
+|---|---|---|
+| Back button (header) | `.back` closure / dismiss | pop current stack |
+| Row chevron ("Detaylar") | `.selected(id)` | push detail route |
+| Tab strip | `selection: Binding<Tab>` | caller-owned tab state |
+| Deep-link landing | entry `route`/`tab` param | parser sets caller state |
+```
+
+Property classification addition:
+
+| Classification | When | Swift Pattern |
+|---|---|---|
+| Navigation output | Component has a push/select/back affordance | `output: (Output) -> Void` / `onSelect: (ID) -> Void` closure on the View |
+| Tab/selection binding | Component switches top-level content | `selection: Binding<SomeTab>` |
+| Deep-link entry | Component is a URL landing surface | plain entry `route`/`tab` param on the View/Configuration |
+
+The affordance's **label/icon copy is static Configuration content** (localized), exactly like other copy  -  only the *intent* is an Output closure.
+
+## Integration with Phase 4B
+
+- Never hardcode `NavigationLink(destination: ConcreteScreen())` inside a reusable component  -  emit the Output.
+- Prefer the system back button; a custom back affordance calls `@Environment(\.dismiss)` or emits `.back`.
+- Bind tab/selection via the caller-owned binding; never a global.
+- If `ui.navigationSystem.mode == custom`, wrap in `{sceneType}` and route via `{router}`/`{routeEnum}` per config.
+- Verify by building + running on the simulator (`reference/build-and-test` / `figma-to-component` Phase 5): the transition happens, the back button appears only after a push, deep links land on the right surface.
+
+---
+
+## When NOT to Use Navigation Integration
+- In-place filters/segmented state that never changes screen → `Binding<Enum>`.
+- Form submission → `/figma-form-integration` (the *result* may navigate; the control is a form action).
+- Toast / loading / alert / data modal → `/figma-overlays`. Bottom-sheet surface → `/figma-bottom-sheets`.
+
+## Checklist  -  Before Leaving the Skill
+```
+[ ] Component emits a typed Output for every navigation affordance  -  no hardcoded routes
+[ ] Back uses system back / dismiss / .back output; renders only when poppable
+[ ] Tab/selection is a caller-owned binding, not a global
+[ ] Deep-link entry is plain state the caller's parser can set (component never parses URLs)
+[ ] Default is native SwiftUI (NavigationStack/navigationDestination/TabView/.sheet(item:))
+[ ] Custom system used ONLY when figma-config ui.navigationSystem.mode == custom (names from config)
+[ ] Labels/icons are localized Configuration copy; only intent is a closure
+```