cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/regex-patterns/references/javascript.md

@@ -0,0 +1,63 @@
+# JavaScript Regex Patterns
+
+Language-specific API for the `regex-patterns` skill. Read `SKILL.md` first for universal syntax.
+
+---
+
+## Syntax
+
+```javascript
+// Literal
+const re = /^hello\s+(\w+)$/i;
+
+// Constructor (dynamic patterns)
+const pattern = 'hello';
+const re2 = new RegExp(`^${escapeRegExp(pattern)}$`, 'i');
+
+// Escape special characters
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+```
+
+## Methods
+
+```javascript
+str.match(re)                    // Match array or null
+[...str.matchAll(/\d+/g)]       // Iterator of all matches
+str.replace(/foo/g, 'bar')      // Replace
+str.split(/[,;\s]+/)            // Split
+re.test(str)                    // Boolean
+```
+
+## Named Groups
+
+```javascript
+const { groups } = /(?<year>\d{4})-(?<month>\d{2})/.exec('2025-06');
+// groups.year === '2025'
+```
+
+## Unicode
+
+```javascript
+// Requires /u or /v flag
+/\p{L}+/u                  // Any letter (any script)
+/\p{Nd}+/u                 // Decimal digit (any script)
+/[\p{L}\p{M}]+/u           // Unicode-aware word matching
+/\p{Script=Greek}+/u       // Script-specific
+```
+
+## Number Formatting with Lookaround
+
+```javascript
+'1234567'.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+// "1,234,567"
+```
+
+## ReDoS Prevention
+
+```javascript
+// No built-in timeout — use re2 package for linear-time engine
+const RE2 = require('re2');
+const re = new RE2(/pattern/);
+```

package/template/.codex/skills/regex-patterns/references/python.md

@@ -0,0 +1,77 @@
+# Python Regex Patterns
+
+Language-specific API for the `regex-patterns` skill. Read `SKILL.md` first for universal syntax.
+
+---
+
+## Core API
+
+```python
+import re
+
+# Compile for reuse
+pattern = re.compile(r'^hello\s+(\w+)$', re.IGNORECASE)
+
+# Methods
+match = pattern.match(string)          # Match at start
+match = pattern.search(string)         # Search anywhere
+matches = pattern.findall(string)      # All matches (list)
+matches = pattern.finditer(string)     # Iterator of Match objects
+result = pattern.sub(r'bar', string)   # Replace
+parts = pattern.split(string)          # Split
+
+# Match object
+if match:
+    match.group(0)           # Full match
+    match.group(1)           # First capture group
+    match.group('name')      # Named group
+    match.start()            # Start position
+    match.end()              # End position
+
+# Raw strings: ALWAYS use r'...' for regex
+# r'\n' is literal backslash-n, not a newline
+```
+
+## Named Groups
+
+```python
+pattern = r'(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})'
+match = re.match(pattern, '2025-06-15')
+match.group('year')   # '2025'
+```
+
+## Verbose Mode
+
+```python
+pattern = re.compile(r"""
+    ^                       # Start of string
+    (?P<protocol>https?)    # Protocol
+    ://                     # Separator
+    (?P<domain>             # Domain group
+        [a-zA-Z0-9.-]+     #   Domain name
+        \.[a-zA-Z]{2,}     #   TLD
+    )
+    (?P<path>/\S*)?         # Optional path
+    $                       # End of string
+""", re.VERBOSE)
+```
+
+## ReDoS Prevention
+
+```python
+# Use the 'regex' package with timeout
+import regex
+try:
+    regex.match(r'(a+)+$', input_string, timeout=1.0)
+except regex.error:
+    pass  # Timed out
+```
+
+## Unicode
+
+```python
+# Python re does NOT support \p{} syntax
+# Use the 'regex' package for Unicode property support:
+import regex
+regex.findall(r'\p{L}+', text)  # All letters (any script)
+```

package/template/.codex/skills/regex-patterns/references/rust.md

@@ -0,0 +1,43 @@
+# Rust Regex Patterns
+
+Language-specific API for the `regex-patterns` skill. Read `SKILL.md` first for universal syntax.
+
+---
+
+## Core API
+
+```rust
+use regex::Regex;
+
+fn main() {
+    // Compile
+    let re = Regex::new(r"^hello\s+(\w+)$").unwrap();
+
+    // Methods
+    let is_match = re.is_match("hello world");               // bool
+    let caps = re.captures("hello world").unwrap();
+    let name = &caps[1];                                      // "world"
+
+    // Named captures
+    let re = Regex::new(r"(?P<year>\d{4})-(?P<month>\d{2})").unwrap();
+    let caps = re.captures("2025-06").unwrap();
+    let year = &caps["year"];   // "2025"
+
+    // Find all matches
+    let re = Regex::new(r"\d+").unwrap();
+    let matches: Vec<&str> = re.find_iter("a1 b2 c3").map(|m| m.as_str()).collect();
+    // ["1", "2", "3"]
+
+    // Replace
+    let result = re.replace_all("foo 123 bar 456", "NUM");
+    // "foo NUM bar NUM"
+}
+```
+
+## Important: Engine Limitations
+
+The `regex` crate uses finite automata (like RE2):
+- ✅ Guaranteed linear-time — immune to ReDoS
+- ❌ No backreferences by default
+- ❌ No lookahead/lookbehind by default
+- Use the **`fancy-regex`** crate for those features (trades ReDoS safety for feature completeness)

package/template/.codex/skills/remediate-pipeline/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: remediate-pipeline
+description: Layer-by-layer remediation loop using adversarial audits, targeted fixes, and fresh-run verification enforcement
+parameters:
+  - name: layer
+    type: string
+    required: false
+    description: Optional starting layer override
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Run `remediate-pipeline-assess`.
+2. Run `remediate-pipeline-execute`.
+3. Enforce fresh-run confirmation rule before layer advancement.

package/template/.codex/skills/remediate-pipeline-assess/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: remediate-pipeline-assess
+description: Assess pipeline layer state, detect prerequisite blockers, classify audit status, and persist remediation plan
+parameters:
+  - name: layer
+    type: string
+    required: false
+    description: Optional preferred start layer
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Run instruction placeholder pre-check and propagation/evolution prerequisite checks.
+2. Scan layers for content and document counts.
+3. Classify each layer status (confirmed-clean / unverified-clean / needs-audit / no-content).
+4. Determine starting layer (respecting upstream-clean requirement).
+5. Present remediation plan and require user approval.
+6. Persist `.memory/wiki/specs/audits/remediation-state.md`.

package/template/.codex/skills/remediate-pipeline-execute/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: remediate-pipeline-execute
+description: Execute per-layer adversarial audit/remediation loop, persist fixes metadata, and manage fresh-run advancement
+parameters:
+  - name: layer
+    type: string
+    required: false
+    description: Optional explicit current layer override
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Read remediation state and detect re-invocation/fresh-run status.
+2. Audit current layer inline document-by-document with implementer simulation + rubric scoring + devil's advocate pass.
+3. Run cross-layer consistency checks when applicable.
+4. Classify and remediate gaps (judgment calls first, mechanical fixes second).
+5. Persist `## Gaps Fixed` metadata.
+6. Call `memory_compile` so fixed/removed relationships are reconciled in the graph before the fresh rerun.
+7. Stop and instruct fresh `/audit-ambiguity [layer]` run.
+8. On confirmed-clean re-invocation, advance to next layer or complete.

package/template/.codex/skills/remediate-shard-split/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: remediate-shard-split
+description: Context-aware remapping of stale parent shard references to new sub-shard targets after shard split operations
+parameters:
+  - name: parent_shard
+    type: string
+    required: false
+    description: Optional explicit parent shard identifier
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Build/confirm sub-shard mapping table with keywords.
+2. Scan docs/plans for stale parent references across all patterns.
+3. Classify each hit by context and propose target replacement.
+4. Apply fixes one-by-one with user confirmation controls.
+5. Run verification grep hard gate until zero stale references remain.
+6. Write remediation record and return summary.

package/template/.codex/skills/resolve-ambiguity/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: resolve-ambiguity
+description: "Systematic ambiguity resolution through tiered information gathering. Use when facing unclear requirements, unknown context, uncertain implementation choices, or any situation where guessing would be risky."
+version: 1.0.0
+---
+
+# Resolve Ambiguity
+
+Resolve ambiguity through a systematic process that prioritizes accurate information over guessing. This skill determines the best source for missing information and retrieves it efficiently.
+
+**Core principle**: Rather ask than guess. Wrong assumptions waste more time than clarifying questions.
+
+**Usage**: Invoke this skill reactively — whenever an agent encounters something it doesn't know during any pipeline step.
+
+---
+
+## Quick Start
+
+When you encounter ambiguity, classify it:
+
+1. **Technical/Factual** — "How does X work?" "What is the correct syntax?" "What did the architecture doc decide?"
+   - Likely found in project or online sources
+   - Follow the tiered lookup process
+
+2. **Intent/Choice** — "Which approach should I use?" "What does the user want?" "Should we prioritize X or Y?"
+   - Requires user input
+   - Go directly to User Clarification (skip lookup)
+
+---
+
+## Tiered Lookup (for Technical/Factual ambiguity)
+
+Check sources in this order. **Stop as soon as you find authoritative information.**
+
+### Tier 1: Project Context Files
+
+**Check first — fastest and most relevant**
+
+Look for project-specific context that may already answer the question:
+- `AGENTS.md` or `GEMINI.md` — Agent instructions, tech stack, validation commands
+- `.codex/instructions/tech-stack.md` — Technology decisions
+- `.codex/instructions/patterns.md` — Code conventions
+- `.codex/instructions/structure.md` — Directory layout
+- `.codex/instructions/commands.md` — Dev, test, lint, build
+
+If these files contain `{{PLACEHOLDER}}` values, the information hasn't been decided yet — move to the next tier.
+
+### Tier 2: Upstream Spec Documents
+
+**Check second — the pipeline's own output**
+
+The answer may already exist in a document written by an earlier pipeline stage:
+- `.memory/wiki/specs/ideation/ideation-index.md` + fractal domain tree (folder `*-index.md`, `*-cx.md`, and feature files) — Problem, personas, features, constraints, domain map
+- `.memory/wiki/specs/*-architecture-design.md` — Tech stack, system design, security model
+- `.memory/wiki/specs/ENGINEERING-STANDARDS.md` — Quality thresholds, performance budgets
+- `.memory/wiki/specs/ia/*.md` — IA shards (features, data models, access control, edge cases)
+- `.memory/wiki/specs/ia/deep-dives/*.md` — Detailed architectural decisions
+- `.memory/wiki/specs/be/*.md` — BE specs (endpoints, contracts, schemas)
+- `.memory/wiki/specs/fe/*.md` — FE specs (components, routing, state, a11y)
+
+**Read the specific section, not the entire document.** Use the IA/BE/FE index files to locate the relevant shard or spec.
+
+### Tier 3: Architectural & Config Files
+
+**Check third — project-specific patterns**
+
+Look within the codebase for answers embedded in configuration or existing code:
+- `package.json`, `tsconfig.json` — Dependencies, TypeScript config
+- `pyproject.toml`, `setup.py` — Python config
+- `Cargo.toml` — Rust config
+- `.env.example` — Environment variables
+- `README.md` — Project overview and setup
+- `ARCHITECTURE.md` or `docs/architecture.md` — Design decisions
+
+Also check existing code for established patterns:
+- Search for files matching the pattern you're trying to follow
+- Search for similar implementations in the codebase
+
+### Tier 4: MCP Documentation Tools
+
+**Check fourth — if MCP documentation tools are available**
+
+If MCP tools are available for documentation lookup, use them:
+- Context7, Firecrawl, or other documentation-specific MCP tools
+- These provide structured access to official library and framework documentation
+
+### Tier 5: Web Search Official Sources
+
+**Check fifth — for external APIs, libraries, standards**
+
+Search the web for:
+- Official documentation sites
+- GitHub repositories of libraries
+- API reference documentation
+- RFC or specification documents
+
+**Search strategy**:
+1. Search with specific query: `"{library/API name} documentation {specific topic}"`
+2. Fetch the most authoritative result (official docs preferred)
+3. Extract only the relevant information
+
+Prefer sources in this order:
+1. Official documentation (*.dev, *.io, readthedocs)
+2. GitHub repository README/docs
+3. Stack Overflow with high votes (for edge cases)
+
+### When to Stop
+
+Stop the tiered lookup when:
+- You find authoritative information that resolves the ambiguity
+- You've checked all relevant tiers without finding information
+- The information found indicates this is actually a choice/intent question
+
+If all tiers exhausted without answer, proceed to User Clarification.
+
+---
+
+## User Clarification (for Intent/Choice ambiguity)
+
+For intent/choice questions, or when tiered lookup fails, ask the user directly. **Never guess when user input is available.**
+
+### Principles
+
+1. **Explain what you need** — Tell the user what information is missing
+2. **Explain why you need it** — Describe how the answer affects the outcome
+3. **Offer smart choices** — If you can infer likely options, present them
+4. **Best practice first** — Order choices with recommended approach at top
+5. **Bad ideas last** — If including risky options, put them at the bottom
+6. **Always allow custom input** — User can always provide their own answer
+7. **When uncertain, don't guess choices** — Better to ask open-ended than offer wrong options
+
+### With Known Choices
+
+When you can confidently identify the options, present them to the user:
+- Question: Clear, specific question explaining context
+- Options ordered by preference (2-4 max):
+  1. Best practice / Most common / Recommended
+  2. Good alternative
+  3. Another valid option
+  4. Least recommended / Has drawbacks
+- Each option includes description explaining implications
+- User can always provide custom input
+
+### Without Known Choices
+
+When you cannot confidently identify the options:
+
+**DO NOT GUESS.** Ask an open-ended question instead:
+- Explain what you need to know and why
+- Keep options minimal or omit entirely
+- Allow free-form input as primary response method
+
+### Formatting Rules
+
+1. **Single question at a time** — Don't overwhelm with multiple questions
+2. **2-4 options maximum** — More becomes confusing
+3. **Descriptions are required** — Every option needs context
+4. **No yes/no when options exist** — Offer the actual choices instead
+5. **Acknowledge uncertainty** — "I'm not sure which applies, so..."
+
+---
+
+## Ambiguity Categories
+
+### Technical Implementation
+**Examples**: "How do I call this API?" "What's the correct syntax?"
+
+**Resolution path**:
+1. Check project context files → upstream specs
+2. Check architectural docs and existing code
+3. Search official documentation
+4. If still unclear → ask user for clarification
+
+### Project Conventions
+**Examples**: "What naming convention?" "Where should this file go?"
+
+**Resolution path**:
+1. Check agent instructions and patterns for explicit conventions
+2. Check existing code for patterns
+3. Check README/contributing guide
+4. If no clear pattern → ask user preference
+
+### Spec Interpretation
+**Examples**: "Does the IA shard mean X or Y?" "Is this edge case in scope?"
+
+**Resolution path**:
+1. Re-read the specific section of the upstream spec
+2. Check cross-shard references for clarification
+3. Check deep dives for architectural decisions
+4. If genuinely ambiguous → ask user (this is a spec gap that should be fixed)
+
+### User Intent
+**Examples**: "Which feature first?" "Should I also refactor X?"
+
+**Resolution path**:
+1. Skip lookup — this requires user input
+2. Ask user immediately
+3. Present inferred options if confident
+4. Allow open-ended response if uncertain
+
+### External Dependencies
+**Examples**: "Which version of X?" "What's the API for Y?"
+
+**Resolution path**:
+1. Check package.json/pyproject.toml for versions
+2. Search for current documentation
+3. Fetch official docs
+4. If version-specific behavior → confirm with user
+
+### Architectural Decisions
+**Examples**: "Monolith or microservices?" "Which pattern to use?"
+
+**Resolution path**:
+1. Check architecture-design.md for prior decisions
+2. Check ENGINEERING-STANDARDS.md for constraints
+3. This is usually a choice → ask user
+4. Present trade-offs clearly in options
+
+---
+
+## Relationship to `/audit-ambiguity`
+
+This skill and the audit workflow are complementary:
+
+| Aspect | `resolve-ambiguity` | `/audit-ambiguity` |
+|--------|---------------------|---------------------|
+| **When** | During any step, at any time | Between pipeline stages |
+| **Trigger** | Agent encounters something it doesn't know | User invokes as a gate |
+| **Scope** | Single question or decision | Entire spec layer |
+| **Output** | Answer or user decision | Scored report with punch list |
+| **Purpose** | Prevent guessing during execution | Verify completeness after writing |
+
+**Composition**: After `/audit-ambiguity` produces a punch list, it invokes this skill on each gap:
+- **Technical gaps** → tiered lookup finds the answer → **mechanical fix** with source citation
+- **Intent gaps** → no source has the answer → **judgment call** presented to user
+- This powers the audit's remediation phase with structured, source-backed resolution
+
+---
+
+## Anti-Patterns
+
+### Guessing and Hoping
+**Wrong**: Making assumptions and proceeding without verification
+**Instead**: Take 30 seconds to check or ask
+
+### Too Many Questions
+**Wrong**: Asking 5 questions before doing anything
+**Instead**: Ask only what's blocking immediate progress
+
+### Vague Questions
+**Wrong**: "How should I proceed?"
+**Instead**: "Should I use approach A (benefit) or B (benefit)?"
+
+### Assuming User Expertise
+**Wrong**: "Should I use the factory pattern or strategy pattern?"
+**Instead**: Explain the options in plain terms with trade-offs
+
+### Hiding Behind Defaults
+**Wrong**: Silently using a default without mentioning alternatives
+**Instead**: "I'll use X (the standard approach). Let me know if you'd prefer Y."
+
+### Skipping Upstream Specs
+**Wrong**: Searching the web for an answer that's already in the architecture doc
+**Instead**: Check Tier 1 and 2 (project docs and upstream specs) before going external
+
+### Not Recording the Resolution
+**Wrong**: Resolving ambiguity verbally but not updating the spec
+**Instead**: When a gap is resolved, update the relevant spec document so future readers don't hit the same ambiguity
+
+---
+
+## Process Summary
+
+1. **Detect**: Identify what information is missing
+2. **Classify**: Technical/Factual → Tiered lookup | Intent/Choice → User clarification
+3. **Resolve**: Execute the appropriate resolution path
+4. **Apply**: Use the information to proceed with the task
+5. **Record**: Update relevant documents so the resolution persists