@ivannikov-pro/ai-context-surgeon 1.0.0

package/strategy/file-navigation-header.md

@@ -0,0 +1,562 @@
+<!-- FNH: Strategy — File Navigation Header standard | SECTIONS: First Line Rule, Format by Type, Vocabulary, Freshness, Checklist | DEPS: none -->
+
+# 🧭 File Navigation Header (FNH)
+
+> Guide: A universal header format for EVERY file, allowing the AI agent to gain a complete map of the contents in just 3–5 lines. | SECTIONS: First Line Rule, Format by Type, Vocabulary, Freshness, Checklist | DEPS: none
+
+MANDATORY RULE: **FNH headers MUST be in English.** Non-Latin scripts (Cyrillic, CJK, Arabic) cost 1.5–2x more tokens. FNH is the most frequently read content by agents — even a 2x overhead here multiplies across every file in the repo.
+
+---
+
+## Philosophy
+
+```
+Without FNH:                        With FNH:
+view_file(1-800)  → 1600 tokens     view_file(1-5)   → 30 tokens
+  "Ah, I need line 340..."            "create() is at L45, going there"
+view_file(330-370) → 80 tokens      view_file(45-75)  → 60 tokens
+──────────────────────────────────────────────────────────────
+Total: ~1680 tokens                 Total: ~90 tokens (95% savings)
+```
+
+The agent ALWAYS calls `view_file(lines=1-5)` first. If these 5 lines contain a **map of the file** — the agent DOES NOT read the entire file. It jumps straight to the needed location.
+
+---
+
+## ⚡ The First Line Rule
+
+> [!IMPORTANT]
+> **Line 1 of every file MUST contain a machine-readable identity descriptor.**
+> An agent must be able to call `view_file(lines=1-1)` on ANY file and immediately know what it is.
+> This is the single most impactful rule in the entire FNH system.
+
+### Universal Lookup Table
+
+| File Type | Line 1 | FNH Location | Why |
+| --- | --- | --- | --- |
+| `.ts`, `.js`, `.mjs`, `.cjs` | `/** FNH comment */` | Line 1 | No obstacles — first line is free |
+| `.py` | `# FNH comment` | Line 1 | Or line 2 if `# -*- coding: utf-8 -*-` is used |
+| `.css`, `.scss`, `.less` | `/* FNH comment */` | Line 1 | CSS block comment |
+| `.sh`, `.bash` | `#!/bin/bash` (shebang) | **Line 2** | Shebang on L1; FNH on L2. Agent MUST scan `view_file(1-2)` |
+| `.md` | `<!-- FNH comment -->` | Line 1 | HTML comment — invisible in rendered markdown |
+| `.yaml`, `.yml` | `# FNH comment` | Line 1 | YAML native comment |
+| `.toml` | `# FNH comment` | Line 1 | TOML native comment |
+| `.sql` | `-- FNH comment` | Line 1 | SQL native comment |
+| `.sol` (Solidity) | `// SPDX-License...` | **Line 2** | SPDX requires Line 1, FNH is placed on Line 2 |
+| `.dockerfile`, `Dockerfile` | `# FNH comment` | Line 1 | Docker native comment |
+| `.env` | `# FNH comment` | Line 1 | Env file native comment |
+| `.json` | ⛔ No comments | **N/A** | Use companion file or `description` field |
+| `.html` | `<!-- FNH comment -->` | Line 1 | HTML comment — invisible in browser |
+
+### The Shebang Exception
+
+Executable scripts with a shebang (`#!/usr/bin/env node`, `#!/bin/bash`) are the **only** exception to the first-line rule for general files. The shebang MUST remain on line 1 for the OS to recognize the interpreter. In this case, the FNH goes on **line 2**.
+
+> [!IMPORTANT]
+> **Agent scan rule for shebang files:** Always use `view_file(lines=1-2)` instead of `view_file(lines=1-1)`.
+> Line 1 of a shebang file is ALWAYS the interpreter directive (`#!/...`) and carries zero project context.
+> The actual FNH identity is on **line 2**. Scanning only line 1 wastes a tool call.
+
+```bash
+#!/bin/bash
+# Tool: analyze-structure — structural metrics for monorepo analysis | MODE: read-only
+set -euo pipefail
+```
+
+### The SPDX Exception (Solidity)
+
+Solidity smart contracts (`.sol`) have a strict convention enforced by compilers and linters: Line 1 MUST be the `// SPDX-License-Identifier: ...` comment. Therefore, Solidity files share the same exception as Shebang scripts: the FNH goes on **line 2**.
+
+> [!TIP]
+> We use standard `//` for FNH in Solidity instead of NatSpec `///`. This is intentional: NatSpec creates public `userdoc`/`devdoc` JSON fields or Sphinx documentation on compilation, which is not the goal of an internal AI system header.
+
+```solidity
+// SPDX-License-Identifier: MIT
+// Contract: StakingRewardPool — user staking & dynamic reward emission | INHERITS: Ownable
+pragma solidity ^0.8.20;
+```
+
+```javascript
+#!/usr/bin/env node
+/** CLI: ai-context-surgeon — entry point for CLI commands | COMMANDS: analyze, restructure, validate */
+const { program } = require("commander");
+```
+
+### The JSON Exception
+
+JSON does not support comments. Use these strategies:
+
+| JSON File | Strategy |
+| --- | --- |
+| `package.json` | Use the `"description"` field as the FNH equivalent |
+| `tsconfig.json` | Actually JSONC — supports `//` comments on line 1 |
+| `turbo.json` / `nx.json` | JSONC — supports `//` comments on line 1 |
+| Other `.json` | Create a companion `<filename>.md` or use a `"//"` hack |
+
+Example — `tsconfig.json` (JSONC format):
+
+```jsonc
+// Config: TypeScript strict — project-level compiler settings | TARGET: ES2022 | MODULE: NodeNext
+{
+  "compilerOptions": {
+    "strict": true,
+  },
+}
+```
+
+Example — `package.json` (standard JSON):
+
+```json
+{
+  "name": "@project/api",
+  "description": "REST API server — Express + Zod + JWT auth | EXPORTS: routes, middleware",
+  "version": "1.0.0"
+}
+```
+
+### The Markdown First Line
+
+For `.md` files, use an **HTML comment on line 1** before the heading. This is invisible in all rendered Markdown viewers but immediately available to `view_file(1-1)`:
+
+```markdown
+<!-- FNH: Guide — API conventions for the project | SECTIONS: Response Format, Errors, Pagination, Auth -->
+
+# API Conventions
+
+> Guide: REST API standards for the entire project...
+```
+
+> [!TIP]
+> The HTML comment on line 1 + the blockquote FNH after H1 are **not redundant**. Line 1 serves the `view_file(1-1)` scan (machine identification). The blockquote serves the `view_file(1-5)` deeper read (detailed map). They work in tandem.
+
+---
+
+## FNH Format for Code (.ts / .js)
+
+### Compact (files under 100 lines)
+
+One line is sufficient:
+
+```typescript
+/** Service: UserService — CRUD + auth | exports: create, getById, update, delete | deps: prisma, bcrypt */
+```
+
+### Standard (files 100–300 lines)
+
+3–5 lines — a map with key functions and their characteristics:
+
+```typescript
+/**
+ * Service: UserService — CRUD + password hashing + email verification
+ * EXPORTS: create (@throws Conflict, sends email), getById (@throws NotFound, cached 60s),
+ *   update (partial merge), delete (soft: sets deletedAt), verifyPassword (bcrypt timing-safe)
+ * DEPS: prisma, bcrypt, @project/shared
+ */
+```
+
+### Extended (files 300+ lines — candidates for splitting)
+
+Full map with sections:
+
+```typescript
+/**
+ * Route: /api/v1/users — full user management endpoints
+ * IMPORTS: express, zod, UserService, AuthGuard
+ * ROUTES:
+ *   GET    /        → list (paginated, filterable)
+ *   GET    /:id     → getById (@throws NotFound)
+ *   POST   /        → create (@throws Conflict, validates body)
+ *   PATCH  /:id     → update (@throws NotFound, partial)
+ *   DELETE /:id     → delete (@throws NotFound, soft delete, admin only)
+ * MIDDLEWARE: authGuard (all routes), rateLimit (POST only)
+ * VALIDATION: createUserSchema, updateUserSchema (Zod)
+ */
+```
+
+---
+
+## FNH Format for Markdown (.md)
+
+Every `.md` file MUST start with an HTML comment on **line 1**. This is the machine-readable identity. The blockquote after H1 provides the detailed map.
+
+### Package README
+
+```markdown
+<!-- FNH: Package — @project/core domain logic | EXPORTS: User, Order, UserService | DEPS: @project/shared, prisma -->
+
+# @project/core
+
+> Package: domain logic — entities, services, repositories
+> SECTIONS: Source Structure, Dependencies, Public API, Environment, Scripts
+> KEY EXPORTS: User, Order, UserService, OrderService
+> DEPS: @project/shared, prisma
+```
+
+### Documentation / Guide
+
+```markdown
+<!-- FNH: Guide — REST API conventions | SECTIONS: Response Format, Errors, Pagination, Auth, Rate Limits -->
+
+# API Conventions
+
+> Guide: REST API standards for the entire project
+> SECTIONS: Response Format (#response), Error Codes (#errors), Pagination (#pagination),
+> Authentication (#auth), Rate Limiting (#rate-limits), Versioning (#versioning)
+```
+
+### Role Prompt
+
+```markdown
+<!-- FNH: Role — Scout read-only monorepo analysis | MODEL: Gemini 3 Flash | MODE: Fast -->
+
+# 🔍 Scout — Reconnaissance
+
+> Role: read-only monorepo analysis | Model: Gemini 3 Flash | Mode: Fast
+> INPUT: target repo path → OUTPUT: scout-report.md
+> SECTIONS: Prompt (#prompt), What to collect (#collection), Report format (#format), Limits (#limits)
+```
+
+### Checklist
+
+```markdown
+<!-- FNH: Checklist — Phase 3 Restructuring (15 steps) | ROLE: Surgeon | MODEL: Gemini 3.1 Pro -->
+
+# Phase 3: Restructuring
+
+> Checklist: 15 restructuring steps with build-checkpoint after each
+> ROLE: Surgeon | MODEL: Gemini 3.1 Pro | PHASES: Foundation, Core, Services, API, Apps
+> PRE-REQ: architecture-plan.md approved
+```
+
+---
+
+## FNH Format for Configs
+
+### YAML
+
+```yaml
+# Config: GitHub Actions CI — build + test + lint on push and PR
+# TRIGGERS: push (main), pull_request (all) | JOBS: lint, test, build | NODE: 18, 20
+name: CI
+on: [push, pull_request]
+```
+
+### Shell
+
+```bash
+#!/bin/bash
+# Tool: analyze-structure — structural metrics for monorepo analysis
+# USAGE: bash tools/analyze-structure.sh /path/to/repo
+# OUTPUT: stdout metrics (files, depth, god-files, packages)
+# MODE: read-only, no modifications
+```
+
+### Dockerfile
+
+```dockerfile
+# Config: production Node.js API — multi-stage build
+# STAGES: deps (install), build (tsc), run (distroless)
+# BASE: node:18-alpine → gcr.io/distroless/nodejs18
+# EXPOSES: 3000
+FROM node:18-alpine AS deps
+```
+
+### SQL
+
+```sql
+-- Migration: 003_add_phone_to_users — adds phone column, backfills from profiles
+-- TABLES: users (ALTER), profiles (SELECT for backfill)
+-- REVERSIBLE: yes (DROP COLUMN)
+ALTER TABLE users ADD COLUMN phone VARCHAR(20);
+```
+
+---
+
+## Anatomy of an FNH
+
+Every FNH consists of **layers**. All layers are MANDATORY — the only difference is the level of detail.
+
+MANDATORY RULE: A file gets an FNH **the moment it is created**, not when it "reaches a threshold." A single file in a folder without an FNH is a violation. No thresholds, no "we'll format it later."
+
+```
+LAYER 1 (MANDATORY): Category + Name + Purpose
+  → "Service: UserService — CRUD + auth for users"
+  → The agent knows in 10 tokens: IS THIS the file I need or not
+
+LAYER 2 (MANDATORY): Exports / Public API
+  → "EXPORTS: create, getById, update, delete"
+  → The agent knows WHAT can be taken from this file
+
+LAYER 3 (MANDATORY): Steps / Sections / Routes
+  → "ROUTES: GET /, POST /, GET /:id, PATCH /:id, DELETE /:id"
+  → The agent knows the STRUCTURE of the file without reading it
+
+LAYER 4 (MANDATORY): Dependencies
+  → "DEPS: prisma, bcrypt, @project/shared"
+  → The agent knows the CONTEXT
+
+LAYER 5 (MANDATORY): Gotchas / non-obvious behavior
+  → "@throws Conflict | sends email | cached 60s"
+  → The agent knows about SURPRISES before starting to edit
+```
+
+### Scaling Depth
+
+All 5 layers are MANDATORY for every file. The difference is the **detail within the layers**:
+
+| File Size | FNH Detail | FNH Lines |
+| --- | --- | --- |
+| Any size | All 5 layers | min 1 line |
+| < 50 lines | Compact: 5 layers in 1 line | 1 line |
+| 50–150 lines | Medium: 5 layers in 2–3 lines | 2–3 lines |
+| 150–300 lines | Detailed: 5 layers in 3–5 lines | 3–5 lines |
+| 300+ lines | Maximum + TIME TO SPLIT the file | 5–8 lines |
+
+> [!IMPORTANT]
+> A small file **does not** exempt you from an FNH. Even a single-line `index.ts` gets an FNH:
+>
+> ```typescript
+> /** Barrel: @project/core public API | EXPORTS: User, UserService, CreateUserInput */
+> export { User } from "./user";
+> ```
+
+---
+
+## Full Examples
+
+### TypeScript — Service
+
+```typescript
+/**
+ * Service: OrderService — order lifecycle from cart to delivery
+ * EXPORTS: createOrder (@throws OutOfStock, sends confirmation), getOrder (@throws NotFound),
+ *   cancelOrder (@throws AlreadyShipped, refunds payment), listOrders (paginated + filtered)
+ * DEPS: prisma, stripe, @project/shared, @project/notifications
+ */
+import { PrismaClient } from "@prisma/client";
+```
+
+### TypeScript — Route
+
+```typescript
+/**
+ * Route: /api/v1/products — product catalog CRUD + search
+ * ROUTES: GET / (search, paginated), GET /:id, POST / (admin), PATCH /:id (admin), DELETE /:id (admin)
+ * AUTH: GET public, POST/PATCH/DELETE require admin role
+ * VALIDATION: createProductSchema, updateProductSchema, searchQuerySchema (Zod)
+ */
+import { Router } from "express";
+```
+
+### TypeScript — Middleware
+
+```typescript
+/** Middleware: RateLimiter — sliding window 100req/min per IP | @mutates req.rateLimit | 429 on exceed */
+import { RateLimiterMemory } from "rate-limiter-flexible";
+```
+
+### TypeScript — Barrel / index.ts
+
+```typescript
+/**
+ * Barrel: @project/core public API
+ * ENTITIES: User, Order, Product
+ * SERVICES: UserService, OrderService, ProductService
+ * TYPES: CreateUserInput, OrderDTO, ProductFilter
+ */
+export { User } from "./entities/user";
+export { Order } from "./entities/order";
+```
+
+### TypeScript — Types
+
+```typescript
+/**
+ * Types: User domain contracts
+ * INPUTS: CreateUserInput, UpdateUserInput, UserFilter
+ * OUTPUTS: UserDTO, UserListResponse
+ * INTERNAL: UserEntity (not exported)
+ */
+export interface CreateUserInput {
+```
+
+### Markdown — Package README
+
+```markdown
+<!-- FNH: Package — @project/api REST API server | EXPORTS: routes, middleware | DEPS: @project/core -->
+
+# @project/api
+
+> Package: REST API server — Express + Zod validation + JWT auth
+> EXPORTS: routes (v1/users, v1/orders, v1/products), middleware (auth, rateLimit, errorHandler)
+> DEPS: @project/core, @project/shared, express, zod, jsonwebtoken
+> SCRIPTS: dev, build, test, lint
+
+## Source Structure
+
+...
+```
+
+### Markdown — Knowledge Item
+
+```markdown
+<!-- FNH: Knowledge — PostgreSQL schema (8 tables) | TABLES: users, orders, products -->
+
+# Database Schema
+
+> Knowledge: PostgreSQL schema — 8 tables, key relations, indexes, migration history
+> TABLES: users, orders, order_items, products, categories, sessions, audit_log, settings
+> RELATIONS: users 1→N orders, orders 1→N order_items, order_items N→1 products
+```
+
+---
+
+## Key FNH Vocabulary (Standard Dictionary)
+
+For predictability, use FIXED keywords:
+
+| Keyword | Description | Used in |
+| --- | --- | --- |
+| `EXPORTS` | Public API / what it exports | .ts, .js, index.ts |
+| `DEPS` | Key dependencies | all |
+| `SECTIONS` | Document sections | .md |
+| `IMPORTS` | Key imports | .ts, .js |
+| `USAGE` | How to run | scripts, CLI |
+| `OUTPUT` | What it produces | scripts, tools |
+| `MODE` | Operating mode (read-only, etc.) | scripts, roles |
+| `INPUT` | What it accepts | roles, scripts |
+| `PRE-REQ` | What is needed before using | checklists, skills |
+
+### Web & Backend (Node, Go, Python)
+
+| Keyword | Description | Used in |
+| --- | --- | --- |
+| `ROUTES` | HTTP endpoints | route files |
+| `MIDDLEWARE` | Used middleware | route files |
+| `VALIDATION` | Validation schemas | route, schema files |
+| `AUTH` | Authentication requirements | route files |
+
+### Data & Infrastructure
+
+| Keyword | Description | Used in |
+| --- | --- | --- |
+| `TYPES` | Exported types | types.ts |
+| `TABLES` | DB Tables | .sql, knowledge |
+| `RELATIONS` | Entity relationships | schema, knowledge |
+| `TRIGGERS` | Launch conditions | CI/CD configs |
+| `JOBS` | Pipeline jobs | CI/CD configs |
+| `STAGES` | Build stages | Dockerfile |
+
+### Web3 (Solidity, Fe, Vyper)
+
+| Keyword | Description | Used in |
+| --- | --- | --- |
+| `INHERITS` | Base contracts | .sol |
+| `STATE` | Key state variables | .sol |
+| `EVENTS` | Emitted events | .sol |
+
+---
+
+## MANDATORY RULE: FNH Freshness
+
+> [!CAUTION]
+> **A stale FNH is worse than no FNH at all.** If the FNH says `EXPORTS: create, getById, delete`, but `delete` was removed and `archive` was added — the agent will look for a non-existent function and miss the new one. This **actively causes harm**.
+
+### Rule for AGENTS.md
+
+This rule MUST be included in every AGENTS.md:
+
+```markdown
+## FNH Freshness Rule
+
+MANDATORY RULE: When you modify a file, you MUST update its File Navigation Header (FNH)
+to reflect your changes. Specifically:
+
+- If you ADD a new export/function/route — add it to the FNH
+- If you REMOVE an export/function/route — remove it from the FNH
+- If you RENAME anything — update it in the FNH
+- If you change @throws, side effects, or deps — update the FNH
+- If FNH does not exist — create one before starting your work
+  The FNH is the FIRST thing other agents read. A stale FNH misleads them. Keep it current.
+```
+
+### When to Update
+
+| Change | Update FNH? |
+| --- | :---------: |
+| Added a new function/export |   ✅ YES |
+| Removed a function/export |   ✅ YES |
+| Renamed a function |   ✅ YES |
+| Added/removed a dependency |   ✅ YES |
+| Changed @throws / side effects |   ✅ YES |
+| Fixed a bug inside a function (API unchanged) |    ❌ NO |
+| Minor refactoring (variables, formatting) |    ❌ NO |
+| Added tests |    ❌ NO |
+
+### How It Works in Practice
+
+```typescript
+// BEFORE:
+/**
+ * Service: UserService — CRUD + auth
+ * EXPORTS: create, getById, update, delete
+ * DEPS: prisma, bcrypt
+ */
+
+// Developer added archiveUser(), removed delete(), added redis for cache
+
+// AFTER (updated FNH):
+/**
+ * Service: UserService — CRUD + auth + archival
+ * EXPORTS: create, getById, update, archive (soft, sets archivedAt)
+ * DEPS: prisma, bcrypt, redis
+ */
+```
+
+### Automation: Validation Hook
+
+In CI/CD, you can add a check: if a file has changed, but its first 5 lines (FNH) have not, show a warning. Script:
+
+```bash
+#!/bin/bash
+# Tool: check-fnh-freshness — warns if file changed but FNH didn't
+# USAGE: bash tools/check-fnh-freshness.sh (run in git repo)
+for file in $(git diff --name-only HEAD~1 -- '*.ts' '*.js'); do
+  fnh_changed=$(git diff HEAD~1 -- "$file" | head -20 | grep -c '^[+-]\s*/\*\*\|^[+-]\s*\*')
+  if [ "$fnh_changed" -eq 0 ]; then
+    echo "⚠️  FNH may be stale: $file (content changed, header unchanged)"
+  fi
+done
+```
+
+---
+
+## Checklist: Add FNH to All Files
+
+### First Line Rule
+
+- [ ] Every `.ts`/`.js`/`.css` file has an FNH comment on **line 1**
+- [ ] Every `.md` file has `<!-- FNH: ... -->` on **line 1** (before H1)
+- [ ] Every `.md` file ALSO has a `>` blockquote FNH after H1 (detailed map)
+- [ ] Every `.sh`/`.bash` script has FNH on **line 2** (after shebang)
+- [ ] Every `.yml`/`.yaml` config has `# Config: ...` on **line 1**
+- [ ] Every `.sql` file has `-- Migration/Query: ...` on **line 1**
+- [ ] Every `Dockerfile` has `# Config: ...` on **line 1**
+- [ ] Every `.env` file has `# Env: ...` on **line 1**
+- [ ] Every `package.json` has a meaningful `"description"` field
+- [ ] Every `tsconfig.json` has `// Config: ...` on **line 1** (JSONC)
+
+### Content Quality
+
+- [ ] FNH contains at least Layer 1 (category + name + purpose)
+- [ ] Files > 100 lines have Layers 1–3 (exports + structure)
+- [ ] `index.ts` barrel-files list all re-exports
+- [ ] Route files list all endpoints with HTTP methods
+- [ ] Standard vocabulary keywords are used (EXPORTS, DEPS, ROUTES, ...)
+- [ ] No harmful tags present (@author, @since, @fileoverview)
+- [ ] **FNH Freshness**: AGENTS.md includes the mandatory FNH update rule
+- [ ] **CI hook**: `check-fnh-freshness.sh` is configured for warnings
+
+---
+
+_ai-context-surgeon / strategy | 2026-04-04_