ace-swarm 2.1.0 → 2.1.2

package/assets/.agents/skills/codemunch/SKILL.md

@@ -1,543 +1,65 @@
 ---
 name: codemunch
-description: 
-  Holistic AST-driven codebase comprehension. Uses ast-grep to surgically extract structural knowledge into lightweight artifacts, enabling deep understanding of any foreign codebase without reading raw files. Operates as a capability-research module inside the ACE Framework.
+description:
+  Map an unfamiliar codebase into durable structural artifacts with ast-grep. Use when you need to understand, debug, contribute to, or borrow patterns from a codebase without broad raw-file reading.
 ---
 
-# CodeMunch — AST-Driven Codebase Intelligence
+# CodeMunch
 
-**IMPORTANT**: NEVER read raw source files to understand a codebase. Every structural fact MUST
-be extracted via an `ast-grep` query. Raw file reads burn 10–100× more tokens than equivalent
-AST queries. The only exception is a single-file glance at an entry point to confirm language
-and project purpose. The goal is to **produce artifacts, not chat**. If a CodeMunch session
-ends without writing at least `CODEBASE_MAP.md`, it has failed.
+Use this skill to turn an unfamiliar codebase into a compact set of structural artifacts that downstream agents can trust.
 
----
-
-## 0. ACE Role Declaration
-
-CodeMunch is a `capability-research` module. In every session it:
-
-- **Emits** a `SOURCE_VALIDATED` event when a structural claim is confirmed by ast-grep output.
-- **Writes** findings to `./agent-state/` as append-only artifacts.
-- **Blocks** downstream modules (`capability-spec`, `capability-build`) from acting on unverifiable structural assumptions.
-- **Hands off** via `HANDOFF.json` once `CODEBASE_MAP.md` and `PATTERNS.md` are locked.
-
-ACE Clarity Protocol headers (`[STATE_ANALYSIS]`, `[STRATEGY_SELECTOR]`, `[EXECUTION_LOG]`,
-`[ARTIFACT_UPDATE]`, `[VERIFICATION]`) must be used at each phase boundary in your response.
-
----
-
-## 0.1 MICE Boundaries
-
-| Rule | Enforcement |
-|---|---|
-| **Modular** | Extracts structural knowledge only; does NOT modify code, write specs, or make build decisions. |
-| **Interoperable** | All findings written as standardized artifacts (`CODEBASE_MAP.md`, `PATTERNS.md`, `EVIDENCE_LOG.md`). |
-| **Customizable** | Goal parameter (`understand/debug/contribute/inspire`) controls depth and focus of analysis. |
-| **Extensible** | New language patterns added via ast-grep pattern sets, not prose guessing. |
-
-## 0.2 Goal Orientation
-
-- `DELETE_PROTOCOL`: Skip Socratic questions already answered by prior runs. No redundant queries.
-- `ARTIFACT_PROTOCOL`: Session MUST produce `CODEBASE_MAP.md` minimum. No artifact = failed session.
-- `AGENCY_PROTOCOL`: Infer next ast-grep target from unanswered Socratic questions. Never ask "what should I query?"
-
-
----
-
-## 1. Socratic Question Stack
-
-Before running a single command, answer these questions in order. Stop at the first one you cannot answer — that is your first ast-grep target.
-
-**Tier 0 — Orientation (answer from README or a 30-second scan)**
-1. What is the primary language and build system?
-2. What is the stated purpose of this codebase in one sentence?
-3. Where is the entry point (`main`, `__init__`, `index`, `lib.rs`, etc.)?
-
-**Tier 1 — Skeleton (answer via ast-grep)**
-4. What are the top-level public types / classes / structs / enums?
-5. What are the primary exported functions or public API symbols?
-6. How many modules/crates/packages exist, and how are they named?
-7. What external dependencies are imported at the top level?
-
-**Tier 2 — Relationships (answer via ast-grep)**
-8. Which modules call which other modules? (call-site mapping)
-9. Where does data enter the system and where does it leave?
-10. What trait / interface / protocol implementations exist?
-11. Where is error handling centralised? What error types exist?
-
-**Tier 3 — Patterns (answer via ast-grep)**
-12. What repeated structural idioms appear 3+ times? (factory, builder, strategy, etc.)
-13. What test coverage patterns exist? (unit, integration, property-based?)
-14. Are there any TODO/FIXME/HACK/unsafe markers that signal risk areas?
-15. What configuration / deserialisation surface exists?
-
-**Tier 4 — Goal Alignment (answer from the task)**
-16. What is the specific goal? (understand / debug / add feature / contribute / get inspired)
-17. Which modules are in the critical path for this goal?
-18. What is the simplest change that would advance this goal?
-
-> **Rule**: Each unanswered question maps to exactly one ast-grep command in Phase 2.
-> Write the question → answer pairs into `SOCRATIC_LOG.md` as you go.
-
----
-
-## 2. Execution Protocol
-
-### Phase 0 — Bootstrap `[STATE_ANALYSIS]`
-
-Detect the language, structure, and project skeleton without reading any source files.
-
-**Step 1 — Language detection**
-```bash
-# Count files by extension to confirm language mix
-find . -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
-
-# Confirm primary language for ast-grep --lang flag
-# Common values: rust, python, js, ts, tsx, go, java, cpp, c, cs, ruby
-```
-
-**Step 2 — Entry point identification**
-```bash
-# Rust
-ast-grep --pattern 'fn main() { $$$ }' --lang rust --json
+## Purpose
 
-# Python
-ast-grep --pattern 'if __name__ == "__main__": $$$' --lang python --json
+Extract architecture, public surface, relationships, and recurring patterns through AST-backed evidence so future work starts from a written map instead of ad-hoc memory.
 
-# JS/TS
-ast-grep --pattern 'export default $EXPR' --lang ts --json
-ast-grep --pattern 'module.exports = $EXPR' --lang js --json
-```
+## Canonical Use Cases
 
-**Step 3 — Top-level module map**
-```bash
-# Count lines and files per directory (structural overview, no source reading)
-find . -name "*.rs" | head -60
-find . -name "*.py" | head -60
-```
+1. A team needs a codebase map before debugging, feature work, or onboarding into an unfamiliar repository.
+2. A contributor wants to identify the minimum insertion point for a change without reading large amounts of raw code first.
+3. An engineer wants reusable patterns, conventions, and hotspots distilled into durable artifacts for later handoff.
 
-**Output**: Write `CODEBASE_MAP.md` stub:
-```markdown
-# CODEBASE_MAP.md
-Language: <lang>
-Entry Point: <path>
-Build System: <cargo/pip/npm/make>
-Module Count: <n>
-Purpose: <one sentence from README>
-```
+## Inputs
 
----
-
-### Phase 1 — Skeleton Extraction `[STRATEGY_SELECTOR]`
-
-Extract the full public API surface using targeted ast-grep patterns. Do NOT read
-implementations — extract signatures only.
-
-**Step 4 — Public types**
-```bash
-# Rust: structs, enums, traits
-ast-grep --pattern 'pub struct $NAME { $$$ }' --lang rust
-ast-grep --pattern 'pub enum $NAME { $$$ }' --lang rust
-ast-grep --pattern 'pub trait $NAME { $$$ }' --lang rust
-
-# Python: classes
-ast-grep --pattern 'class $NAME: $$$' --lang python
-
-# TypeScript: interfaces, types, classes
-ast-grep --pattern 'export interface $NAME { $$$ }' --lang ts
-ast-grep --pattern 'export type $NAME = $TYPE' --lang ts
-ast-grep --pattern 'export class $NAME { $$$ }' --lang ts
-```
-
-**Step 5 — Public functions / methods**
-```bash
-# Rust: public fns (with --json for machine-parseable output)
-ast-grep --pattern 'pub fn $NAME($$$) -> $RET { $$$ }' --lang rust --json
-
-# Rust: public fns (no return type)
-ast-grep --pattern 'pub fn $NAME($$$) { $$$ }' --lang rust
-
-# Python: top-level defs
-ast-grep --pattern 'def $NAME($$$): $$$' --lang python
-
-# TypeScript: exported functions
-ast-grep --pattern 'export function $NAME($$$): $RET { $$$ }' --lang ts
-ast-grep --pattern 'export const $NAME = ($$$) => $BODY' --lang ts
-```
-
-**Step 6 — External dependencies**
-```bash
-# Rust: use statements (top-level imports)
-ast-grep --pattern 'use $PATH' --lang rust
-
-# Python: imports
-ast-grep --pattern 'import $MODULE' --lang python
-ast-grep --pattern 'from $MODULE import $NAME' --lang python
-
-# JS/TS: imports
-ast-grep --pattern 'import $NAME from "$PATH"' --lang ts
-ast-grep --pattern 'import { $$$ } from "$PATH"' --lang ts
-```
-
-**Output**: Append to `CODEBASE_MAP.md`:
-```markdown
-## Public API Surface
-### Types
-- `TypeName` — <kind: struct/enum/class> — <file:line>
-
-### Functions
-- `fn_name(args) -> ret` — <file:line>
+- Target codebase path or repository checkout
+- Goal or intent such as `understand`, `debug`, `contribute`, or `inspire`
+- Project orientation artifacts like README, manifests, and existing `agent-state/` outputs when available
+- ast-grep plus any language-specific patterns needed for the active language mix
 
-### Key Dependencies
-- <dep_name>: <apparent purpose>
-```
+## Workflow
 
----
-
-### Phase 2 — Relationship Mapping `[EXECUTION_LOG]`
-
-Find how components connect. This answers Socratic questions 8–11.
-
-**Step 7 — Trait/interface implementations**
-```bash
-# Rust: impl blocks (what implements what)
-ast-grep --pattern 'impl $TRAIT for $TYPE { $$$ }' --lang rust
-
-# Rust: plain impl blocks
-ast-grep --pattern 'impl $TYPE { $$$ }' --lang rust
-```
-
-**Step 8 — Call-site mapping (who calls what)**
-```bash
-# Find all calls to a specific function (replace TARGET with function name)
-ast-grep --pattern '$OBJ.TARGET($$$)' --lang rust
-ast-grep --pattern 'TARGET($$$)' --lang rust
-
-# Find all method calls on a type
-ast-grep --pattern '$VAR: $TYPE' --lang rust   # find variable declarations of a type
-```
-
-**Step 9 — Error handling topology**
-```bash
-# Rust: Result types and ? operator usage
-ast-grep --pattern 'Result<$T, $E>' --lang rust
-ast-grep --pattern '$EXPR?' --lang rust
+1. Bootstrap language, build-system, and entry-point understanding with minimal orientation reads.
+2. Answer the Socratic question stack with ast-grep-backed evidence.
+3. Write the core structural artifacts: `CODEBASE_MAP.md`, `DEPENDENCY_GRAPH.md`, `PATTERNS.md`, `SOCRATIC_LOG.md`, and `EVIDENCE_LOG.md`.
+4. Produce a goal-specific synthesis artifact such as a contribution guide or bug hypothesis.
+5. Hand off from the written artifacts rather than from unwritten session memory.
 
-# Rust: custom error enums
-ast-grep --pattern 'pub enum $NAME { $$$ }' --lang rust  # filter for Error suffix
+## Outputs
 
-# Python: exception definitions
-ast-grep --pattern 'class $NAME(Exception): $$$' --lang python
-ast-grep --pattern 'except $EXC: $$$' --lang python
-```
+- `agent-state/CODEBASE_MAP.md`
+- `agent-state/DEPENDENCY_GRAPH.md`
+- `agent-state/PATTERNS.md`
+- `agent-state/SOCRATIC_LOG.md`
+- `agent-state/EVIDENCE_LOG.md`
+- Optional goal-specific artifacts such as `CONTRIBUTION_GUIDE.md` or `BUG_HYPOTHESIS.md`
 
-**Step 10 — Configuration and deserialization surface**
-```bash
-# Rust: serde derives (anything Deserialize is config/data entry)
-ast-grep --pattern '#[derive($$$Deserialize$$$)] $STRUCT' --lang rust
+## Validation
 
-# Python: dataclasses, pydantic models
-ast-grep --pattern '@dataclass' --lang python
-ast-grep --pattern 'class $NAME(BaseModel): $$$' --lang python
-
-# TypeScript: zod schemas, JSON parse points
-ast-grep --pattern 'z.object({ $$$ })' --lang ts
-```
-
-**Output**: Write `DEPENDENCY_GRAPH.md`:
-```markdown
-# DEPENDENCY_GRAPH.md
-## Module Relationships
-- `module_a` → calls → `module_b` (via fn_name)
-
-## Trait Implementations
-- `TypeX` implements `TraitY`
-
-## Error Taxonomy
-- `ErrorVariant`: exits at <file:line>
-
-## Config / Data Entry Points
-- `StructName` (Deserialize): loaded at <file>
-```
-
----
+- Verify the core artifact set is written before any final synthesis or handoff occurs.
+- Verify every structural claim in the synthesis can be traced back to an ast-grep-backed entry in `EVIDENCE_LOG.md`.
+- Verify unanswered questions are recorded explicitly as known unknowns rather than guessed.
 
-### Phase 3 — Pattern & Idiom Mining `[EXECUTION_LOG]`
+## References
 
-Identify recurring structural decisions. These reveal the codebase's philosophy.
-
-**Step 11 — Test patterns**
-```bash
-# Rust: test functions
-ast-grep --pattern '#[test] fn $NAME() { $$$ }' --lang rust
-ast-grep --pattern '#[tokio::test] async fn $NAME() { $$$ }' --lang rust
-
-# Python: pytest / unittest
-ast-grep --pattern 'def test_$NAME($$$): $$$' --lang python
-ast-grep --pattern 'class $NAME(TestCase): $$$' --lang python
-
-# JS/TS: jest / vitest
-ast-grep --pattern 'it("$DESC", $$$)' --lang ts
-ast-grep --pattern 'describe("$DESC", $$$)' --lang ts
-```
-
-**Step 12 — Unsafe / risk markers**
-```bash
-# Rust: unsafe blocks (security/correctness hotspots)
-ast-grep --pattern 'unsafe { $$$ }' --lang rust
-ast-grep --pattern 'unsafe fn $NAME($$$)' --lang rust
-
-# TODO/FIXME markers (language-agnostic comment scan)
-grep -rn "TODO\|FIXME\|HACK\|SAFETY\|PANIC\|unwrap()" --include="*.rs" | head -40
-grep -rn "TODO\|FIXME\|HACK\|BUG" --include="*.py" | head -40
-```
-
-**Step 13 — Builder / factory / newtype patterns**
-```bash
-# Rust: builder pattern (fn new / fn build)
-ast-grep --pattern 'fn new($$$) -> Self { $$$ }' --lang rust
-ast-grep --pattern 'fn build(self) -> $TYPE { $$$ }' --lang rust
-
-# Rust: newtype wrappers
-ast-grep --pattern 'pub struct $NAME($INNER);' --lang rust
-
-# Python: class methods / factories
-ast-grep --pattern '@classmethod' --lang python
-```
-
-**Step 14 — Async / concurrency patterns**
-```bash
-# Rust: async functions
-ast-grep --pattern 'async fn $NAME($$$)' --lang rust
-ast-grep --pattern 'tokio::spawn($$$)' --lang rust
-
-# Python: async
-ast-grep --pattern 'async def $NAME($$$): $$$' --lang python
-
-# JS/TS
-ast-grep --pattern 'await $EXPR' --lang ts
-```
-
-**Output**: Append to `PATTERNS.md`:
-```markdown
-# PATTERNS.md
-## Design Patterns Detected
-- Builder: <count> usages, primary in <module>
-- Newtype: <count> usages
-
-## Test Coverage Profile
-- Unit tests: <count>
-- Integration tests: <count>
-- Async tests: <count>
-
-## Risk Markers
-- unsafe blocks: <count> in <files>
-- TODOs: <list of top ones>
-
-## Concurrency Model
-- <async/sync/threaded/actor> — evidence: <fn names>
-```
-
----
-
-### Phase 4 — Artifact Generation `[ARTIFACT_UPDATE]`
-
-All findings are now crystallised into locked artifacts. No reasoning from memory — only
-from the written artifacts below.
-
-**Required artifacts** (write all before Phase 5):
-
-| Artifact | Purpose |
-|---|---|
-| `CODEBASE_MAP.md` | Language, entry points, module list, public API surface |
-| `DEPENDENCY_GRAPH.md` | Module relationships, trait impls, error taxonomy |
-| `PATTERNS.md` | Design patterns, test profile, risk markers, concurrency model |
-| `SOCRATIC_LOG.md` | Every question + its ast-grep-verified answer |
-| `EVIDENCE_LOG.md` | Raw ast-grep output snippets used as evidence (append-only) |
-
-**Artifact write protocol:**
-```bash
-# Each ast-grep query output MUST be appended to EVIDENCE_LOG.md immediately
-echo "## Query: pub fn signatures (rust)" >> ./agent-state/EVIDENCE_LOG.md
-ast-grep --pattern 'pub fn $NAME($$$) -> $RET { $$$ }' --lang rust --json   >> ./agent-state/EVIDENCE_LOG.md
-```
-
-**Optional artifacts** (generate when goal demands it):
-
-| Artifact | When to generate |
-|---|---|
-| `CALL_GRAPH.md` | Goal = debug / trace data flow |
-| `CONTRIBUTION_GUIDE.md` | Goal = contribute / extend |
-| `INSPIRATION_NOTES.md` | Goal = extract ideas for new project |
-| `BUG_HYPOTHESIS.md` | Goal = debug specific issue |
-
----
-
-### Phase 5 — Synthesis Pass `[VERIFICATION]`
-
-**ONLY after all Phase 4 artifacts are written**, perform a final reasoning pass.
-Read ONLY the artifacts — not any source files.
-
-**Step 15 — Self-verification checklist**
-- [ ] Can I describe the codebase architecture in 3 sentences from `CODEBASE_MAP.md` alone?
-- [ ] Can I name the 5 most important types/functions without looking at source?
-- [ ] Can I explain the data flow from entry to exit from `DEPENDENCY_GRAPH.md`?
-- [ ] Have all Tier 2 Socratic questions been answered in `SOCRATIC_LOG.md`?
-- [ ] Does `EVIDENCE_LOG.md` have at least one ast-grep snippet per structural claim?
-
-**Step 16 — Goal-aligned synthesis**
-
-*Mode: UNDERSTAND*
-> Synthesise `CODEBASE_MAP.md` + `PATTERNS.md` into a plain-English architecture document.
-
-*Mode: DEBUG*
-> Trace the bug-relevant call path using `CALL_GRAPH.md`. Write `BUG_HYPOTHESIS.md`
-> with: symptom → suspected module → ast-grep evidence → falsification criteria.
-
-*Mode: CONTRIBUTE / ADD FEATURE*
-> From `DEPENDENCY_GRAPH.md`, identify the minimum insertion point. Write
-> `CONTRIBUTION_GUIDE.md` with: interface contract, which existing tests to extend,
-> which patterns to follow (from `PATTERNS.md`).
-
-*Mode: INSPIRE*
-> Extract architectural decisions, naming conventions, idioms from `PATTERNS.md` into
-> `INSPIRATION_NOTES.md` with annotations on what can be adapted.
-
-**Step 17 — HANDOFF**
-
-Emit `HANDOFF.json` when synthesis is complete:
-```json
-{
-  "meta": { "timestamp": "<ISO8601>", "skill": "codemunch", "session_id": "<uuid>" },
-  "transition": {
-    "from": "capability-research",
-    "to": "capability-spec",
-    "status": "READY_FOR_HANDOFF",
-    "reason": "Codebase map and pattern artifacts are locked."
-  },
-  "payload": {
-    "primary_artifact": "./agent-state/CODEBASE_MAP.md",
-    "supporting_artifacts": [
-      "./agent-state/DEPENDENCY_GRAPH.md",
-      "./agent-state/PATTERNS.md",
-      "./agent-state/SOCRATIC_LOG.md"
-    ],
-    "evidence_pointer": "./agent-state/EVIDENCE_LOG.md",
-    "known_unknowns": ["<list any unanswered Tier 3/4 questions>"]
-  }
-}
-```
-
----
-
-## 3. ast-grep Quick Reference
-
-### Universal Flags
-```bash
---lang <lang>         # rust | python | js | ts | tsx | go | java | cpp | c | html | css
---pattern / -p        # inline pattern
---rule <file.yml>     # YAML rule file for complex patterns
---json / -j           # machine-readable JSON output (use for artifact writing)
---no-ignore           # scan files ignored by .gitignore
---color never         # disable ANSI in output (use when piping to artifact files)
-```
-
-### Meta-variable Syntax
-```
-$NAME     — single AST node (identifier, expression, etc.)
-$$$       — zero or more AST nodes (variadic / body capture)
-$$ARGS    — named multi-match capture
-$_        — anonymous wildcard (matches anything, not captured)
-```
-
-### YAML Rule Template (complex structural queries)
-```yaml
-# Save as ./codemunch-rules/<rule-name>.yml
-id: find-pattern-name
-language: rust
-rule:
-  pattern: pub fn $NAME($$$) -> Result<$T, $E> { $$$ }
-  # Optional filters:
-  inside:
-    pattern: impl $TRAIT for $TYPE { $$$ }
-  has:
-    pattern: $EXPR?      # contains at least one ? operator
-  not:
-    pattern: todo!()     # exclude unimplemented stubs
-```
-Run: `ast-grep scan --rule ./codemunch-rules/<rule-name>.yml`
-
-### Language Cheat Sheet
-
-**Rust**
-```bash
-ast-grep -p 'pub fn $N($$$)' -l rust                         # public functions
-ast-grep -p 'impl $T for $U { $$$ }' -l rust                 # trait impls
-ast-grep -p '#[derive($$$)]' -l rust                          # all derives
-ast-grep -p 'Err($E)' -l rust                                 # error emission sites
-ast-grep -p '$V.unwrap()' -l rust                             # panic hotspots
-```
-
-**Python**
-```bash
-ast-grep -p 'def $N($$$) -> $R: $$$' -l python               # typed functions
-ast-grep -p '@$DECORATOR' -l python                           # all decorators
-ast-grep -p 'raise $E' -l python                              # exception sites
-ast-grep -p '__all__ = [$$$]' -l python                       # public exports
-```
-
-**TypeScript / JavaScript**
-```bash
-ast-grep -p 'export { $$$ }' -l ts                            # barrel exports
-ast-grep -p 'const $N = useCallback($$$)' -l tsx              # React hooks
-ast-grep -p 'throw new $E($$$)' -l ts                         # throw sites
-ast-grep -p 'satisfies $TYPE' -l ts                           # type constraints
-```
-
----
-
-## 3.1 Wrong-Stuff Protocol
-
-When ast-grep analysis reveals structural issues:
-
-| Finding | Classification | Route To |
-|---|---|---|
-| Code contradicts spec claims | `spec_violation` | `agent-spec` |
-| Unsafe/risky patterns detected | `implementation_bug` | `agent-builder` |
-| Evidence source unreliable | `invalid_source` | `agent-research` (self-correct) |
-| Codebase documentation stale | `documentation_drift` | `agent-docs` |
-
-## 3.2 Anti-Patterns
-
-| Anti-Pattern | Correct Behavior |
-|---|---|
-| Reading raw source files | Use ast-grep queries exclusively |
-| Guessing structure without AST evidence | Every claim backed by ast-grep output |
-| Session ends without artifacts | Minimum output: `CODEBASE_MAP.md` |
-| Querying all languages blindly | Detect primary language first (Phase 0), then query |
-| Capturing > 500 lines of raw output | Summarize into bullet points; keep exemplars only |
-
----
-
-## 4. Failure Modes & Circuit Breakers
-
-| Failure | Signal | Recovery |
-|---|---|---|
-| `ast-grep` returns no matches | Pattern may be wrong for this dialect | Use `--json` + inspect one sample node kind first |
-| Artifact file > 500 lines | Too much raw output captured | Summarise into bullet points; keep only exemplars in EVIDENCE_LOG |
-| Socratic question unresolvable via AST | Deep runtime behaviour | Mark as `KNOWN_UNKNOWN` in SOCRATIC_LOG; do NOT guess |
-| Goal changes mid-session | New task injected | Emit `GATE_FAILED`, re-enter Phase 0 with updated goal |
-
----
+- `references/ast-driven-protocol.md` preserves the detailed Socratic stack, phase-by-phase command recipes, and advanced ast-grep cookbook.
 
-## 5. Activation
+## Compatibility
 
-When you receive a codebase (path, repo, or CXML dump) with a goal, type:
+- `SKILL.md` is the canonical portable contract for this skill.
+- The long-form playbook lives under `references/` for progressive disclosure and must not redefine the top-level contract.
+- The workflow should remain useful in any environment that can run ast-grep and basic shell discovery commands.
 
-**`munch <path> --goal <understand|debug|contribute|inspire> [--lang <lang>]`**
+## Failure Policy
 
-CodeMunch will automatically enter Phase 0, execute the Socratic Question Stack, run
-ast-grep queries in order, and produce the Phase 4 artifacts before delivering the
-Phase 5 synthesis. No raw file reading. No token waste. Only structure.
+- If ast-grep is unavailable or the language cannot be queried safely, stop and surface the limitation instead of pretending the structure is understood.
+- If required artifacts were not written, treat the session as incomplete rather than summarizing from memory.
+- Do not read large swaths of raw source just to compensate for missing structural evidence; mark the unknown and route accordingly.