garrytan · rafiulnakib · Mar 28, 2026 · Mar 28, 2026 · Mar 28, 2026 · Mar 28, 2026
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,7 @@
 node_modules/
 browse/dist/
 design/dist/
+oracle/bin/dist/
 bin/gstack-global-discover
 .gstack/
 .claude/skills/

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -353,6 +353,25 @@ The `EvalCollector` accumulates test results and writes them in two ways:
 
 Tier 1 runs on every `bun test`. Tiers 2+3 are gated behind `EVALS=1`. The idea: catch 95% of issues for free, use LLMs only for judgment calls and integration testing.
 
+## Oracle, the product memory layer
+
+Oracle gives every gstack skill product-level context (not just code context).
+
+**Storage:** `docs/oracle/PRODUCT_MAP.md` in the project repo. In-repo, git-tracked, human-verifiable. The map is self-describing: its header contains the schema and instructions. Skills that read it follow the header, not hardcoded format knowledge.
+
+**Integration:** Two resolvers (`PRODUCT_CONSCIENCE_READ`, `PRODUCT_CONSCIENCE_WRITE`) inject ~10 lines each into 19 skill templates via the gen-skill-docs pipeline. Planning skills read the map for context. Post-work skills silently update it. Zero manual interaction.
+
+**Scanner:** `oracle/bin/scan-imports.ts` is an AST-powered codebase analyzer using TypeScript's compiler API. It produces a scan manifest (JSON) with routes, import graph, circular deps, dead files, and complexity classification. The scanner runs from gstack's own install directory using gstack's `node_modules/typescript`, not the user's project. Compiled to a standalone binary as a performance optimization, falls back to `bun run` from source.
+
+**Staleness:** Scan manifest stores `head_sha` from `git rev-parse HEAD`. Comparing against current HEAD catches branch switches, rebases, and amends. No timestamp-based checks.
+
+```
+docs/oracle/
+├── PRODUCT_MAP.md          # Tier 1: concise feature registry (~12 lines/feature)
+└── inventory/              # Tier 2: detailed per-feature docs
+    └── F001-feature-name.md
+```
+
 ## What's intentionally not here
 
 - **No WebSocket streaming.** HTTP request/response is simpler, debuggable with curl, and fast enough. Streaming would add complexity for marginal benefit.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.13.4.0] - 2026-03-28 — The Product Conscience
+
+Every gstack skill now has product memory. `/oracle` bootstraps a product map from your codebase, then every planning skill reads it for context and every post-work skill silently writes back. The map lives in your repo at `docs/oracle/` so you can verify every claim.
+
+### Added
+
+- **Product Conscience across 19 skills.** Planning skills (`/office-hours`, `/plan-ceo-review`, `/plan-eng-review`, etc.) automatically read your product map for feature connections, patterns, and anti-patterns. Post-work skills (`/ship`, `/review`, `/qa`) silently update it after completing work. The map gets better with every session.
+- **`/oracle` skill with 6 modes.** Bootstrap (generate product map from codebase), inventory (budgeted deep page-by-page scan), refresh (full re-analysis), update (lightweight git sync), stats (product + codebase health dashboard), query (answer product questions with context).
+- **AST-powered codebase scanner.** Uses TypeScript's compiler API for 100% static import resolution. Detects 10 frameworks (React Router, Next.js, SvelteKit, Nuxt, Remix, Astro, TanStack Router, Vue Router, Wouter, plus file-based routing). Git co-change analysis for complexity classification (EASY/MEDIUM/HARD/MEGA). Tarjan's SCC for circular dependencies. Dead code detection with `.oracleignore` support and multi-level confidence.
+- **HTML import graph visualizer.** Run `/oracle scan --visualize` to generate a self-contained HTML file showing your entire import tree, color-coded by complexity, with collapsible subtrees and circular dependency highlighting.
+- **Terminal ASCII graph.** ANSI-colored tree output with `--max-depth`, `--no-color`, and `--compact` flags.
+- **Scanner CLI flags.** `--diff` (compare against previous scan), `--dry-run` (preview without writing), `--git-frequency` (sort routes by recent commit activity).
+- **Self-describing product map.** The map header contains its own schema, so skills don't need hardcoded format knowledge. Schema changes update the map, not 19 templates.
+
+### For contributors
+
+- New resolver system: `scripts/resolvers/oracle.ts` with `PRODUCT_CONSCIENCE_READ` and `PRODUCT_CONSCIENCE_WRITE` registered in both `index.ts` and `gen-skill-docs.ts`.
+- Shared scanner utilities extracted to `oracle/bin/scanner/utils.ts`.
+- 186 tests across 5 test files (scanner: 114, visualizer: 15, terminal graph: 15, utils: 16, resolvers: 26).
+- 14 fixture directories covering all 10 supported frameworks.
+- E2E test scaffolding in `test/skill-e2e-oracle.test.ts` with touchfile declarations.
+
 ## [0.13.3.0] - 2026-03-28 — Lock It Down
 
 Six fixes from community PRs and bug reports. The big one: your dependency tree is now pinned. Every `bun install` resolves the exact same versions, every time. No more floating ranges pulling fresh packages from npm on every setup.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -88,6 +88,7 @@ gstack/
 ├── codex/           # /codex skill (multi-AI second opinion via OpenAI Codex CLI)
 ├── land-and-deploy/ # /land-and-deploy skill (merge → deploy → canary verify)
 ├── office-hours/    # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm)
+├── oracle/          # /oracle skill (product memory — bootstraps product map, tracks features, surfaces connections)
 ├── investigate/     # /investigate skill (systematic root-cause debugging)
 ├── retro/           # Retrospective skill (includes /retro global cross-project mode)
 ├── bin/             # CLI utilities (gstack-repo-mode, gstack-slug, gstack-config, etc.)

diff --git a/README.md b/README.md
@@ -46,11 +46,11 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source
 
 Open Claude Code and paste this. Claude does the rest.
 
-> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade. Then ask the user if they also want to add gstack to the current project so teammates get it.
+> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /oracle, /autoplan, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade. Then ask the user if they also want to add gstack to the current project so teammates get it.
 
 ### Step 2: Add to your repo so teammates get it (optional)
 
-> Add gstack to this project: run **`cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup`** then add a "gstack" section to this project's CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, and tells Claude that if gstack skills aren't working, run `cd .claude/skills/gstack && ./setup` to build the binary and register skills.
+> Add gstack to this project: run **`cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup`** then add a "gstack" section to this project's CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /oracle, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, and tells Claude that if gstack skills aren't working, run `cd .claude/skills/gstack && ./setup` to build the binary and register skills.
 
 Real files get committed to your repo (not a submodule), so `git clone` just works. Everything lives inside `.claude/`. Nothing touches your PATH or runs in the background.
 
@@ -163,6 +163,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
 | `/benchmark` | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. |
 | `/document-release` | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. |
 | `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. `/retro global` runs across all your projects and AI tools (Claude Code, Codex, Gemini). |
+| `/oracle` | **Product Memory** | Product intelligence layer. Bootstraps a product map from your codebase, tracks features across sessions, surfaces connections during planning, warns about anti-patterns. Runs silently through every other skill. |
 | `/browse` | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. `$B connect` launches your real Chrome as a headed window — watch every action live. |
 | `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
 | `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → eng review automatically with encoded decision principles. Surfaces only taste decisions for your approval. |
@@ -277,7 +278,7 @@ Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__*
 Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review,
 /design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse,
 /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro,
-/investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard,
+/investigate, /document-release, /codex, /cso, /oracle, /autoplan, /careful, /freeze, /guard,
 /unfreeze, /gstack-upgrade.
 ```
 

diff --git a/TODOS.md b/TODOS.md
@@ -1,5 +1,19 @@
 # TODOS
 
+## Oracle
+
+### Quality benchmark — measure product conscience impact
+
+**What:** Compare skill output with and without product map context. Run the same planning skill (e.g., /office-hours) on the same codebase with and without a PRODUCT_MAP.md present. Measure whether connections, anti-pattern warnings, and pattern reuse suggestions actually improve.
+
+**Why:** Oracle's core hypothesis is that product context makes every skill smarter. Without measurement, we're flying blind. The outside voice in the eng review flagged this: "build a 2-hour experiment before a multi-week build." We built it anyway — now validate.
+
+**Context:** Run on iskool-prod (the first real target). Bootstrap a product map, then run /office-hours twice: once with the map, once without. LLM-judge eval comparing output quality. This also stress-tests the self-describing map format.
+
+**Effort:** S (human: ~2 hours / CC: ~30 min)
+**Priority:** P1
+**Depends on:** Oracle shipped to main
+
 ## Builder Ethos
 
 ### First-time Search Before Building intro

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.13.3.0
+0.13.4.0
diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md
@@ -441,6 +441,24 @@ DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head
 If a design doc is now found, read it and continue the review.
 If none was produced (user may have cancelled), proceed with standard review.
 
+## Product Conscience — Read
+
+```bash
+_PMAP="docs/oracle/PRODUCT_MAP.md"
+[ -f "$_PMAP" ] && echo "PRODUCT_MAP: found" || echo "PRODUCT_MAP: none"
+```
+
+If PRODUCT_MAP found: read `docs/oracle/PRODUCT_MAP.md`. The map is self-documenting —
+its header explains the schema. Use the Product Arc, Features, Patterns, and Anti-Patterns
+to inform your work. Spot-check 2-3 components mentioned in the map by grepping the
+codebase to verify accuracy. If an anti-pattern matches what you're about to do, warn
+the user.
+
+If no PRODUCT_MAP: note that `/oracle` can bootstrap one from the codebase. Do not block
+on this — proceed with the skill's normal workflow.
+
+---
+
 # /autoplan — Auto-Review Pipeline
 
 One command. Rough plan in, fully reviewed plan out.
@@ -1114,3 +1132,26 @@ Suggest next step: `/ship` when ready to create the PR.
 - **Full depth means full depth.** Do not compress or skip sections from the loaded skill files (except the skip list in Phase 0). "Full depth" means: read the code the section asks you to read, produce the outputs the section requires, identify every issue, and decide each one. A one-sentence summary of a section is not "full depth" — it is a skip. If you catch yourself writing fewer than 3 sentences for any review section, you are likely compressing.
 - **Artifacts are deliverables.** Test plan artifact, failure modes registry, error/rescue table, ASCII diagrams — these must exist on disk or in the plan file when the review completes. If they don't exist, the review is incomplete.
 - **Sequential order.** CEO → Design → Eng. Each phase builds on the last.
+
+## Product Conscience — Write
+
+After completing the skill's main work, silently update the product map if it exists.
+
+```bash
+_PMAP="docs/oracle/PRODUCT_MAP.md"
+[ -f "$_PMAP" ] && echo "PRODUCT_MAP_WRITE: updating" || echo "PRODUCT_MAP_WRITE: skipped (no map)"
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+```
+
+If PRODUCT_MAP exists: update `docs/oracle/PRODUCT_MAP.md` following the schema in its
+header. Update the feature entry for what changed in this session — adjust lifecycle status
+(PLANNED → BUILDING → SHIPPED), add discovered patterns or anti-patterns, update connections.
+Compress features shipped >3 months ago with no `depends_on` references to one-liners.
+Do NOT ask the user — this is a silent write.
+
+Then write the breadcrumb:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null && mkdir -p ~/.gstack/projects/$SLUG && date -u +%Y-%m-%dT%H:%M:%SZ > ~/.gstack/projects/$SLUG/.product-map-last-write 2>/dev/null || true
+```
+
+If no PRODUCT_MAP: skip silently. Do not create one — that's `/oracle bootstrap`.
diff --git a/autoplan/SKILL.md.tmpl b/autoplan/SKILL.md.tmpl
@@ -29,6 +29,8 @@ allowed-tools:
 
 {{BENEFITS_FROM}}
 
+{{PRODUCT_CONSCIENCE_READ}}
+
 # /autoplan — Auto-Review Pipeline
 
 One command. Rough plan in, fully reviewed plan out.
@@ -702,3 +704,5 @@ Suggest next step: `/ship` when ready to create the PR.
 - **Full depth means full depth.** Do not compress or skip sections from the loaded skill files (except the skip list in Phase 0). "Full depth" means: read the code the section asks you to read, produce the outputs the section requires, identify every issue, and decide each one. A one-sentence summary of a section is not "full depth" — it is a skip. If you catch yourself writing fewer than 3 sentences for any review section, you are likely compressing.
 - **Artifacts are deliverables.** Test plan artifact, failure modes registry, error/rescue table, ASCII diagrams — these must exist on disk or in the plan file when the review completes. If they don't exist, the review is incomplete.
 - **Sequential order.** CEO → Design → Eng. Each phase builds on the last.
+
+{{PRODUCT_CONSCIENCE_WRITE}}
diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md
@@ -284,6 +284,24 @@ If `NEEDS_SETUP`:
    fi
    ```
 
+## Product Conscience — Read
+
+```bash
+_PMAP="docs/oracle/PRODUCT_MAP.md"
+[ -f "$_PMAP" ] && echo "PRODUCT_MAP: found" || echo "PRODUCT_MAP: none"
+```
+
+If PRODUCT_MAP found: read `docs/oracle/PRODUCT_MAP.md`. The map is self-documenting —
+its header explains the schema. Use the Product Arc, Features, Patterns, and Anti-Patterns
+to inform your work. Spot-check 2-3 components mentioned in the map by grepping the
+codebase to verify accuracy. If an anti-pattern matches what you're about to do, warn
+the user.
+
+If no PRODUCT_MAP: note that `/oracle` can bootstrap one from the codebase. Do not block
+on this — proceed with the skill's normal workflow.
+
+---
+
 # /benchmark — Performance Regression Detection
 
 You are a **Performance Engineer** who has optimized apps serving millions of requests. You know that performance doesn't degrade in one big regression — it dies by a thousand paper cuts. Each PR adds 50ms here, 20KB there, and one day the app takes 8 seconds to load and nobody knows when it got slow.
@@ -496,3 +514,26 @@ Write to `.gstack/benchmark-reports/{date}-benchmark.md` and `.gstack/benchmark-
 - **Third-party scripts are context.** Flag them, but the user can't fix Google Analytics being slow. Focus recommendations on first-party resources.
 - **Bundle size is the leading indicator.** Load time varies with network. Bundle size is deterministic. Track it religiously.
 - **Read-only.** Produce the report. Don't modify code unless explicitly asked.
+
+## Product Conscience — Write
+
+After completing the skill's main work, silently update the product map if it exists.
+
+```bash
+_PMAP="docs/oracle/PRODUCT_MAP.md"
+[ -f "$_PMAP" ] && echo "PRODUCT_MAP_WRITE: updating" || echo "PRODUCT_MAP_WRITE: skipped (no map)"
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+```
+
+If PRODUCT_MAP exists: update `docs/oracle/PRODUCT_MAP.md` following the schema in its
+header. Update the feature entry for what changed in this session — adjust lifecycle status
+(PLANNED → BUILDING → SHIPPED), add discovered patterns or anti-patterns, update connections.
+Compress features shipped >3 months ago with no `depends_on` references to one-liners.
+Do NOT ask the user — this is a silent write.
+
+Then write the breadcrumb:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null && mkdir -p ~/.gstack/projects/$SLUG && date -u +%Y-%m-%dT%H:%M:%SZ > ~/.gstack/projects/$SLUG/.product-map-last-write 2>/dev/null || true
+```
+
+If no PRODUCT_MAP: skip silently. Do not create one — that's `/oracle bootstrap`.
diff --git a/benchmark/SKILL.md.tmpl b/benchmark/SKILL.md.tmpl
@@ -20,6 +20,8 @@ allowed-tools:
 
 {{BROWSE_SETUP}}
 
+{{PRODUCT_CONSCIENCE_READ}}
+
 # /benchmark — Performance Regression Detection
 
 You are a **Performance Engineer** who has optimized apps serving millions of requests. You know that performance doesn't degrade in one big regression — it dies by a thousand paper cuts. Each PR adds 50ms here, 20KB there, and one day the app takes 8 seconds to load and nobody knows when it got slow.
@@ -232,3 +234,5 @@ Write to `.gstack/benchmark-reports/{date}-benchmark.md` and `.gstack/benchmark-
 - **Third-party scripts are context.** Flag them, but the user can't fix Google Analytics being slow. Focus recommendations on first-party resources.
 - **Bundle size is the leading indicator.** Load time varies with network. Bundle size is deterministic. Track it religiously.
 - **Read-only.** Produce the report. Don't modify code unless explicitly asked.
+
+{{PRODUCT_CONSCIENCE_WRITE}}