feat: /oracle — Product Conscience with AST-powered codebase scanner

.gitignore

@@ -2,6 +2,7 @@
 node_modules/
 browse/dist/
 design/dist/
+oracle/bin/dist/
 bin/gstack-global-discover
 .gstack/
 .claude/skills/

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.

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.)

README.md

@@ -38,6 +38,8 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source
 5. Run `/qa` on your staging URL
 6. Stop there. You'll know if this is for you.
 
+> **Product conscience:** gstack automatically builds a product map from your git history the first time any skill runs (after ~20 commits). Every skill uses it to warn about anti-patterns and track features. For deeper analysis, run `/oracle inventory`.
+
 ## Install — 30 seconds
 
 **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Git](https://git-scm.com/), [Bun](https://bun.sh/) v1.0+, [Node.js](https://nodejs.org/) (Windows only)

autoplan/SKILL.md

@@ -525,6 +525,68 @@ 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"
+if [ -f "$_PMAP" ]; then
+  echo "PRODUCT_MAP: found"
+else
+  eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+  _BOOTSTRAPPED="no"
+  [ -n "$SLUG" ] && [ -f ~/.gstack/projects/$SLUG/.product-map-auto-bootstrapped ] && _BOOTSTRAPPED="yes"
+  _COMMITS=$(git rev-list --count HEAD 2>/dev/null || echo "0")
+  if [ "$_BOOTSTRAPPED" = "yes" ]; then
+    echo "PRODUCT_MAP: none (previously bootstrapped)"
+  elif [ "$_COMMITS" -ge 20 ]; then
+    echo "PRODUCT_MAP: bootstrap-ready $_COMMITS"
+  else
+    echo "PRODUCT_MAP: none (repo has $_COMMITS commits, need 20+)"
+  fi
+fi
+```
+
+If PRODUCT_MAP **found**: read `docs/oracle/PRODUCT_MAP.md`. Check the first feature entry:
+- If entries have full fields (Purpose, Category, Components, etc.): spot-check 2-3
+  components by grepping the codebase. Warn if an anti-pattern matches planned work.
+- If entries are compressed one-liners: read the Product Arc and feature list for context.
+  Skip spot-checking (compressed entries don't list components).
+
+If PRODUCT_MAP is **bootstrap-ready**: auto-bootstrap a minimal product map. This is
+silent, do NOT ask the user. Under 60 seconds. Git log analysis only, no file reading,
+no scanner, no component trees.
+
+1. Run these commands:
+```bash
+git log --oneline -50
+git log --since=6.months --name-only --format="" | sort | uniq -c | sort -rn | head -20
+```
+2. Identify features from the output. Write a minimal `docs/oracle/PRODUCT_MAP.md`:
+   - `<!-- schema_version: 1 -->` header
+   - `## Product Arc` (2-3 sentences from git history)
+   - `## Features` (compressed one-liner per feature)
+   - `## Reusable Patterns` ("None mapped yet")
+   - `## Anti-Patterns` ("None mapped yet")
+   - `## Identity` (category percentages or "Suppressed")
+```bash
+mkdir -p docs/oracle
+```
+3. Write breadcrumbs:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+[ -n "$SLUG" ] && mkdir -p ~/.gstack/projects/$SLUG && touch ~/.gstack/projects/$SLUG/.product-map-auto-bootstrapped && date -u +%Y-%m-%dT%H:%M:%SZ > ~/.gstack/projects/$SLUG/.product-map-last-write
+```
+4. Tell the user: "Product conscience activated — {N} features mapped. Run `/oracle inventory` for deeper analysis."
+5. Then read the map you just created and use it for context (compressed sub-path above).
+
+If PRODUCT_MAP is **none (previously bootstrapped)**: user may have deleted the map.
+Proceed without product context.
+
+If PRODUCT_MAP is **none (repo has N commits, need 20+)**: repo too young.
+Proceed without product context.
+
+---
+
 # /autoplan — Auto-Review Pipeline
 
 One command. Rough plan in, fully reviewed plan out.
@@ -1198,3 +1260,41 @@ 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
+_INV_NUDGED="no"
+[ -n "$SLUG" ] && [ -f ~/.gstack/projects/$SLUG/.oracle-inventory-nudged ] && _INV_NUDGED="yes"
+echo "INVENTORY_NUDGED: $_INV_NUDGED"
+```
+
+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.
+
+If the feature entry you just worked on is in compressed one-liner format (auto-bootstrapped),
+expand it to the full schema with all fields (Purpose, Category, Data, Patterns, Components,
+Decisions, Connections, Depends on, Anti-patterns, Shipped). You have context from this
+session's work to fill in accurate details.
+
+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 `INVENTORY_NUDGED` is "no" and the map has mostly compressed one-liner entries:
+tell the user "Tip: Run `/oracle inventory` for a deeper page-by-page analysis."
+Then mark as nudged:
+```bash
+[ -n "$SLUG" ] && touch ~/.gstack/projects/$SLUG/.oracle-inventory-nudged 2>/dev/null || true
+```
+
+If no PRODUCT_MAP: skip silently. Do not create one — that's `/oracle bootstrap`.

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}}

benchmark/SKILL.md

@@ -375,6 +375,68 @@ If `NEEDS_SETUP`:
    fi
    ```
 
+## Product Conscience — Read
+
+```bash
+_PMAP="docs/oracle/PRODUCT_MAP.md"
+if [ -f "$_PMAP" ]; then
+  echo "PRODUCT_MAP: found"
+else
+  eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+  _BOOTSTRAPPED="no"
+  [ -n "$SLUG" ] && [ -f ~/.gstack/projects/$SLUG/.product-map-auto-bootstrapped ] && _BOOTSTRAPPED="yes"
+  _COMMITS=$(git rev-list --count HEAD 2>/dev/null || echo "0")
+  if [ "$_BOOTSTRAPPED" = "yes" ]; then
+    echo "PRODUCT_MAP: none (previously bootstrapped)"
+  elif [ "$_COMMITS" -ge 20 ]; then
+    echo "PRODUCT_MAP: bootstrap-ready $_COMMITS"
+  else
+    echo "PRODUCT_MAP: none (repo has $_COMMITS commits, need 20+)"
+  fi
+fi
+```
+
+If PRODUCT_MAP **found**: read `docs/oracle/PRODUCT_MAP.md`. Check the first feature entry:
+- If entries have full fields (Purpose, Category, Components, etc.): spot-check 2-3
+  components by grepping the codebase. Warn if an anti-pattern matches planned work.
+- If entries are compressed one-liners: read the Product Arc and feature list for context.
+  Skip spot-checking (compressed entries don't list components).
+
+If PRODUCT_MAP is **bootstrap-ready**: auto-bootstrap a minimal product map. This is
+silent, do NOT ask the user. Under 60 seconds. Git log analysis only, no file reading,
+no scanner, no component trees.
+
+1. Run these commands:
+```bash
+git log --oneline -50
+git log --since=6.months --name-only --format="" | sort | uniq -c | sort -rn | head -20
+```
+2. Identify features from the output. Write a minimal `docs/oracle/PRODUCT_MAP.md`:
+   - `<!-- schema_version: 1 -->` header
+   - `## Product Arc` (2-3 sentences from git history)
+   - `## Features` (compressed one-liner per feature)
+   - `## Reusable Patterns` ("None mapped yet")
+   - `## Anti-Patterns` ("None mapped yet")
+   - `## Identity` (category percentages or "Suppressed")
+```bash
+mkdir -p docs/oracle
+```
+3. Write breadcrumbs:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+[ -n "$SLUG" ] && mkdir -p ~/.gstack/projects/$SLUG && touch ~/.gstack/projects/$SLUG/.product-map-auto-bootstrapped && date -u +%Y-%m-%dT%H:%M:%SZ > ~/.gstack/projects/$SLUG/.product-map-last-write
+```
+4. Tell the user: "Product conscience activated — {N} features mapped. Run `/oracle inventory` for deeper analysis."
+5. Then read the map you just created and use it for context (compressed sub-path above).
+
+If PRODUCT_MAP is **none (previously bootstrapped)**: user may have deleted the map.
+Proceed without product context.
+
+If PRODUCT_MAP is **none (repo has N commits, need 20+)**: repo too young.
+Proceed without product context.
+
+---
+
 # /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.
@@ -587,3 +649,41 @@ 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
+_INV_NUDGED="no"
+[ -n "$SLUG" ] && [ -f ~/.gstack/projects/$SLUG/.oracle-inventory-nudged ] && _INV_NUDGED="yes"
+echo "INVENTORY_NUDGED: $_INV_NUDGED"
+```
+
+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.
+
+If the feature entry you just worked on is in compressed one-liner format (auto-bootstrapped),
+expand it to the full schema with all fields (Purpose, Category, Data, Patterns, Components,
+Decisions, Connections, Depends on, Anti-patterns, Shipped). You have context from this
+session's work to fill in accurate details.
+
+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 `INVENTORY_NUDGED` is "no" and the map has mostly compressed one-liner entries:
+tell the user "Tip: Run `/oracle inventory` for a deeper page-by-page analysis."
+Then mark as nudged:
+```bash
+[ -n "$SLUG" ] && touch ~/.gstack/projects/$SLUG/.oracle-inventory-nudged 2>/dev/null || true
+```
+
+If no PRODUCT_MAP: skip silently. Do not create one — that's `/oracle bootstrap`.

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}}