Nav Spec

v3 adds two structural enforcements:

1. Citation-anchored pattern disqualifiers (R25). references/pattern-disqualifiers.md enumerates disqualifier conditions per catalog pattern, each cited to NN/g / Material 3 / Apple HIG (or tagged HEURISTIC: UNTESTED). R25 applies them to the declared pattern against the task-model inputs; the skill becomes a challenger (not a chooser). Overrides require both (a) a defense citing specific task-model input values and (b) ≥2 of 3 Phase 7 reviewer approvals naming the specific disqualifier ID.
2. Authoring-direction lint (R26). Sections 1–4 of NAVIGATION.md must not cite src/components/** or *.astro paths. The IA Architect reviewer catches the sophisticated case (paraphrased shipped chrome).

Additional v3 tightenings:

• Task table requires new columns: evidence_source (non-UI artifact) and return_locus (task terminus).
• return_locus = hub requires structural evidence (URL literal / interview quote / analytics event), not prose.
• "Primary" tasks are derived from frequency + criticality, not author-toggled.
• Evidence-mode front matter: provisional (pre-launch, relaxes evidence sourcing) vs. validated (production, requires real artifacts). R25 is structural in both modes.
• Time-bounded provisional-override artifacts: .stitch/provisional-override-<date>.md requires named deferred_validation.event and date ≤90 days. Expired overrides re-fire R25.

Core responsibilities

1. Spec authoring (/nav-spec) — produce .stitch/NAVIGATION.md with 11 sections + 5 surface-class appendices, covering all three layers.
2. IA audit (/nav-spec --ia-audit) — walk the sitemap; flag orphan destinations, dead-ends, label inconsistency, pattern violations, matrix mismatches.
3. Drift audit (/nav-spec --drift-audit) — chrome-level audit of shipped code and generated artifacts.
4. Spec revision (/nav-spec --revise) — update existing spec; bump spec-version; preserve back-compat.
5. Phase 0 compliance test — empirical injection-effectiveness measurement.
6. Validation (validate.py) — post-generation enforcement of all 24 rules (R1–R15 chrome, R16–R24 IA + pattern + a11y) on Stitch output and shipped HTML.

The three layers

┌─────────────────────────────────────────────────────────────────┐
│ Layer 1 — Information Architecture                              │
│   Task model → Sitemap → Reachability matrix                    │
│   Entry/exit catalogue → State machine                          │
│   Cross-surface context → URL contract → Content taxonomy       │
├─────────────────────────────────────────────────────────────────┤
│ Layer 2 — Patterns                                              │
│   Named patterns from NN/g + Material + HIG                     │
│   Per {surface × archetype}: which pattern, why, what variants  │
├─────────────────────────────────────────────────────────────────┤
│ Layer 3 — Chrome                                                │
│   Header, back, breadcrumbs, footer, skip-link                  │
│   States, tap targets, mobile↔desktop transforms                │
│   Per-surface a11y                                              │
└─────────────────────────────────────────────────────────────────┘

Cross-cutting: search strategy, recovery paths, IA-level a11y, analytics hooks.

Anchoring principle

The skill does not invent patterns. Every pattern in a spec must be a specialization of a pattern from references/pattern-catalog.md, which catalogs:

• NN/g navigation patterns — hub-and-spoke, nested-doll, sequential, pyramid, faceted, tag
• Material Design 3 navigation components — top app bar, bottom nav, navigation rail, drawer, tabs, segmented button (with destination-count rules)
• Apple HIG patterns — tab bar, split view, navigation stack, modal
• Industry composite patterns — master-detail, index+preview, modal-on-list, persistent-context workspace, progressive disclosure, command palette

Reviewing the spec against references/ia-principles.md (Dan Brown's 8 principles of IA) is a required Phase 7 deliverable.

Workflows

Fail-fast preconditions

Before any workflow except the audits:

1. Resolve the venture's Stitch project ID via crane_ventures MCP. Match the current repo to a venture code; read stitchProjectId. If null: stop. Tell the user: "No Stitch project configured. Add stitchProjectId for this venture in crane-console/config/ventures.json first." No fallback discovery.
2. Check for .stitch/DESIGN.md. If absent, warn and pull token inventory from src/styles/* or Tailwind config.
3. Check for .stitch/NAVIGATION.md. If present, route to revise.md. If absent, route to author.md.

Surface-class taxonomy (authoritative)

Surface classes are modeled by auth model, not by subdomain.

The subdomain is a secondary attribute. A public page on portal.* is still public chrome-wise.

Archetype taxonomy (authoritative)

Ten archetypes: dashboard, list, detail, form, wizard, empty, error, modal, drawer, transient.

Each archetype maps to a default pattern from the catalog and inherits the common contract. Full table in references/archetype-catalog.md.

Classification (deterministic, required, 5 tags)

Every stitch-design or stitch-ux-brief invocation targeting a specific screen must carry five explicit classification tags:

surface=<public|auth-gate|token-auth|session-auth-client|session-auth-admin>
archetype=<dashboard|list|detail|form|wizard|empty|error|modal|drawer|transient>
viewport=<mobile|desktop>
task=<short-name from venture's task model>
pattern=<name from pattern-catalog.md>

The pipeline fails fast if any tag is missing or unrecognized. Natural-language inference is explicitly disabled.

The two new tags (task=, pattern=) are required because chrome alone never determined a pattern — the same chrome can implement different patterns. Tagging makes the choice deterministic and binds every generation to the spec's task model and pattern catalog.

Manual lookup aid: references/classification-rubric.md.

Injection mechanism

At prompt-enhancement time, stitch-design reads .stitch/NAVIGATION.md, looks up the matching {surface, archetype, viewport, task, pattern} block, assembles an essential NAV CONTRACT block (always injected) and an extended block (loaded conditionally based on archetype/pattern), and injects them between DESIGN SYSTEM and PAGE STRUCTURE.

Token budget: ≤500 essential, ≤800 essential+extended combined. Canonical format: references/injection-snippet-template.md.

Post-generation, validate.py parses the returned HTML and runs all 24 rules. Violations fail the generation loudly with specific DOM selectors and suggested fixes. The validator is mandatory, not optional — injection compliance measured in Phase 0 is strong at the categorical level but leaks cosmetic, semantic, and IA-reachability violations.

Validator coverage (R1–R26)

Severity tiers: structural always fails; semantic retries once; cosmetic warns but passes (configurable per venture).

R25 runs in a spec-only mode via python3 validate.py --check-pattern-fitness --spec .stitch/NAVIGATION.md (no HTML file required). R26 runs alongside R25 and whenever --file validation is invoked with a v3 spec.

References

• pattern-catalog.md — NN/g + Material + HIG + composite patterns
• pattern-disqualifiers.md — v3 citation-anchored disqualifier conditions (powers R25)
• ia-principles.md — Dan Brown's 8 principles
• task-model-template.md — task elicitation and structure (v3: evidence_source + return_locus)
• reachability-matrix-template.md — central IA artifact
• state-machine-template.md — auth/data/task states
• content-taxonomy-template.md — labels, verbs, statuses
• archetype-catalog.md — 10 archetypes × default patterns
• chrome-component-contracts.md — DOM + Tailwind
• classification-rubric.md — 5-tag decision rules
• injection-snippet-template.md — NAV CONTRACT block (essential + extended)
• anti-patterns.md — chrome anti-patterns 1–15 + IA anti-patterns 16–24

Examples

• examples/NAVIGATION.md — gold-standard v3 spec (migrated from ss-console v2)
• examples/ia-audit-report.md — IA audit format
• examples/drift-audit-report.md — chrome drift audit format
• examples/phase-0-compliance-report.md — empirical compliance measurement
• examples/pattern-disqualifier-tests/ — v3 synthetic regression tests (admin-heavy-switching, mandatory-wizard, deep-content-library)
• examples/v3-regression-test.md — expected outputs for the v3 regression suite

Best practices

• Author in direction: tasks → golden paths → IA → pattern → spec → COMPARE to code. Sections 1–4 must be authorable as if shipped code did not exist. Phase 5 (chrome contracts) is the first authorized read of shipped components. R26 enforces this at the lint level; the IA Architect reviewer catches paraphrased shipped-chrome claims in §1–4.
• Anchor every pattern. Every pattern in a spec is a specialization of a catalog entry. Every disqualifier in pattern-disqualifiers.md cites NN/g / Material 3 / HIG, or carries a HEURISTIC: UNTESTED tag. Never invent.
• Skill is a challenger, not a chooser. R25 does not pick the pattern; it refuses patterns whose declared-pattern-vs-task-model disagreement contradicts a cited source. Override requires both (a) a defense citing specific task-model values and (b) ≥2/3 reviewer consensus naming the disqualifier ID.
• "Primary" is structural, not declarative. A task is primary iff frequency ∈ {high, medium} OR criticality = blocking. The author cannot dodge R25 disqualifiers by relabeling tasks.
• return_locus = hub requires structural evidence. Literal URL in a file or SOW, interview quote, or analytics event. Prose intent is insufficient.
• Provisional mode relaxes evidence, not R25. Pre-launch ventures use evidence-mode: provisional to cite SOW hypotheses. R25 remains structural. Dismissal requires a time-bounded .stitch/provisional-override-<date>.md with a named validation event and date ≤90 days.
• Five surface classes, not three or four. v1 forgot auth-gate; v2+ include it explicitly.
• The reachability matrix is validator-checkable. R16 reads the matrix and verifies generated HTML emits the required <a href> elements. The matrix is not decorative — it is the contract.
• The validator is the enforcement layer. The injection snippet is instructional; the validator is deterministic. When in conflict, trust the validator.
• Spec-version bumps reflect breaking changes. Additive (new archetype, new pattern, new anti-pattern) lands without bump. Structural (taxonomy redefinition, rule inversion, new required section) bumps.
• A11y is woven, not bolted. It lives in chrome (per-surface) AND IA (cross-surface heading hierarchy, landmark consistency). The Implementation reviewer covers per-surface; the IA architect reviewer covers cross-surface.
• Backwards compatibility. v1 specs validate against R1–R15 only. v2 specs (task/pattern tags, reachability matrix) add R16–R24. v3 specs (evidence-mode, return_locus column, decision log) add R25 and R26. Soft-skip warnings are emitted on stderr when a rule's inputs are missing; the pipeline never fails unexpectedly on a v1 or v2 spec due to a v3 rule.