cfsa-antigravity 2.3.0 → 2.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Constraint-First Specification Architecture — production-grade from line one
 
-A pipeline that turns a raw idea into exhaustively specified, test-driven, production-quality code through progressive gates. Stack-agnostic. Agent-agnostic. Cross-platform. Every line of code is production-grade from the moment it's written.
+A pipeline that turns a raw idea into exhaustively specified, test-driven, production-quality code through progressive gates. Stack-agnostic. Built for Antigravity on Linux/WSL. Every line of code is production-grade from the moment it's written.
 
 ## Quick Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfsa-antigravity",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "CFSA Pipeline — Constraint-First Specification Architecture for AI agents. Production-grade from line one.",
   "scripts": {
     "changeset": "changeset",

package/template/.agent/kit-sync.md

@@ -1,15 +1,6 @@
-<!-- This file is created and updated automatically by /sync-kit.
-     Commit it to your project repo — it records which kit version
-     the project is on and serves as the baseline for the next sync. -->
-
-> [!NOTE]
-> **`FIRST_SYNC_PENDING` values are placeholders.** They are populated automatically
-> when you run `/sync-kit` for the first time. Do not manually edit them — let the
-> sync command fill them in.
-
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: FIRST_SYNC_PENDING
-last_synced_at: FIRST_SYNC_PENDING
-kit_version: main
+last_synced_commit: d5fb37b9e886719e436a6ca52bb9c94ab839acb6
+last_synced_at: 2026-03-16T23:22:30Z
+kit_version: 2.4.0

package/template/.agent/workflows/sync-kit.md

@@ -18,37 +18,37 @@ Pull improvements from the upstream [cfsa-antigravity](https://github.com/Repair
 
 Read `.agent/kit-sync.md` in the project root.
 
-- **File exists** → extract `last_synced_commit` and `upstream` values. Use **incremental mode** (Step 1a).
-- **File missing** → this is a **first sync**. Use **full diff mode** (Step 1b). The tracking file will be created in Step 9.
+- **File exists** → extract `last_synced_commit`, `upstream`, and `kit_version` values. Proceed to Step 1.
+- **File missing** → **HARD STOP**: "No sync tracking file found. This file is auto-generated during kit installation. To fix: run `npx cfsa-antigravity init --force` to reinstall the kit with sync tracking, or manually create `.agent/kit-sync.md` with the upstream URL and the commit hash of your last known kit version."
 
 ---
 
-## 1. Identify what changed
+## 1. Fetch upstream and identify changes
 
 // turbo
 
-### 1a. Incremental sync (commit-scoped)
+### 1a. Clone or fetch the upstream repo
 
-Run `git log <last_synced_commit>..HEAD --name-only` on the upstream to get only the changed files. Work only with those files in Steps 2–7.
+To compare against the upstream, you MUST fetch the actual upstream repository. Use one of these approaches:
 
-If the command returns no files: report "No changes since last sync (commit `<hash>`)" and skip to Step 8.5.
+1. **Preferred — shallow clone to /tmp** (fastest):
+   ```bash
+   git clone --depth=50 <upstream_url> /tmp/cfsa-upstream
+   cd /tmp/cfsa-upstream
+   ```
+2. **Alternative — GitHub MCP**: Use `list_commits` and `get_file_contents` from the `github-mcp-server` to compare files.
 
-### 1b. First sync (full comparison)
+### 1b. Diff from last synced commit
 
-Compare the **entire upstream repo** against the project. Scan at minimum:
+Using the cloned repo (or GitHub API), get the list of changed files since the last sync:
 
-| Upstream Path | What to Compare |
-|--------------|-----------------|
-| Root files | `AGENTS.md`, `GEMINI.md` |
-| `.agent/instructions/` | All 5 markdown files |
-| `.agent/rules/` | All 9 markdown files |
-| `.agent/workflows/` | All workflow files |
-| `.agent/skills/` | All skill directories (SKILL.md + sub-files) |
-| `.agent/skill-library/` | MANIFEST.md, README.md, subdirectories |
-| `.agent/progress/` | Directory structure |
-| `docs/` | README.md, kit-architecture.md, audits/, plans/ scaffolding (including `ideation/` folder structure) |
+```bash
+git log <last_synced_commit>..HEAD --name-only --pretty=format:""
+```
+
+If the command returns no files (or the API shows no commits after `last_synced_commit`): report "No changes since last sync (commit `<hash>`, version `<kit_version>`)" and skip to Step 8.5.
 
-Compare using SHA hashes or byte-level diff. Classify each file per Step 2.
+Work only with the changed files in Steps 2–7.
 
 ---
 
@@ -228,15 +228,15 @@ Scan these files for any literal `{{` characters:
 
 ## 9. Update sync state
 
-Write or update `.agent/kit-sync.md`:
+Read the upstream's `package.json` to get the current kit version. Write or update `.agent/kit-sync.md`:
 
 ```markdown
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: <current HEAD commit hash>
+last_synced_commit: <current upstream HEAD commit hash>
 last_synced_at: <ISO 8601 timestamp>
-kit_version: main
+kit_version: <version from upstream package.json, e.g. 2.3.1>
 ```
 
 This file is committed to the project repo — it records which kit version the project is on and serves as the baseline for the next sync.

package/template/.agent/workflows/write-architecture-spec-deepen.md

@@ -122,18 +122,24 @@ Read `.agent/skills/session-continuity/protocols/ambiguity-gates.md` and run the
 
 ## 14. Request review and propose next steps
 
+> [!CAUTION]
+> **FORBIDDEN next steps from this workflow**: You may ONLY propose `/write-architecture-spec` (next shard) or `/write-be-spec` as the next step. Proposing `/plan-phase`, `/implement-slice`, or any workflow that comes after BE/FE specs is **strictly forbidden** from this point in the pipeline. The IA layer feeds into the BE and FE spec layers — those layers MUST be completed before planning or implementation can begin, regardless of project type (web app, CLI tool, bash script, API-only, etc.). Every project has backend contracts and interface specifications, even if the "frontend" is a terminal or a CLI `--help` output.
+
 You may only notify the user of completion if you have completed the Cross-Reference check, the Dependency Graph validation, and the Ambiguity gate.
 
 Use `notify_user` to present the completed IA shard for review. Your message MUST include:
 1. **The shard created** (link to the file)
 2. **Cross-reference verification** (confirmation that links are bidirectional)
 3. **Ambiguity Gate confirmation** (confirmation that no implementer would need to guess)
-4. **The Pipeline State** (propose the next task from the options below)
+4. **The Pipeline State** (propose the next task from the **ONLY** permitted options below)
 
 Do NOT proceed to the next step until the user sends a message explicitly approving this output. Proposing next steps is not the same as receiving approval. Wait for explicit approval before continuing.
 
 Read `.agent/progress/spec-pipeline.md` to determine the pipeline state, then propose the appropriate next step:
 
 - **More skeleton shards remain** → "Next: Run `/write-architecture-spec` for shard [next-shard-number]"
-- **All IA shards complete** → "All IA shards complete and /audit-ambiguity ia has already run (mandatory Step 13 above). If it scored 0%, proceed to /write-be-spec. If it found gaps, resolve them and re-run /audit-ambiguity ia as a fresh invocation before proceeding."
+- **All IA shards complete** → "All IA shards complete and /audit-ambiguity ia has already run (mandatory Step 13 above). If it scored 0%, proceed to `/write-be-spec`. If it found gaps, resolve them and re-run /audit-ambiguity ia as a fresh invocation before proceeding."
 - **Self-audit found unresolvable issues** → Present the issues for discussion before proposing next step
+
+> [!IMPORTANT]
+> **No other next steps are valid.** If you believe this project does not need BE or FE specs, you are wrong. Every project type maps to the pipeline's spec layers — CLI tools have command contracts (BE) and terminal output specs (FE), bash scripts have function contracts (BE) and usage/help specs (FE), API-only services have endpoint contracts (BE) and client SDK/docs specs (FE). The pipeline does not skip layers.

package/template/.agent/workflows/write-architecture-spec.md

@@ -61,3 +61,10 @@ Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review dis
 - [ ] Access control covers all roles and all interaction types
 - [ ] Edge cases cover concurrent access, deletion cascades, and state conflicts
 - [ ] Cross-shard dependencies are bidirectional
+
+---
+
+## Post-Completion: Mandatory Next Step
+
+> [!CAUTION]
+> After completing all IA shards, the **only** valid next step is `/write-be-spec`. Do NOT propose `/plan-phase` or `/implement-slice` — those require completed BE and FE specs. This applies to ALL project types: web apps, CLI tools, bash scripts, APIs, desktop apps. No project skips the BE/FE spec layers.

package/template/.agent/workflows/write-be-spec-write.md

@@ -90,10 +90,20 @@ If this BE spec introduces a technology not already in the project's tech stack:
 
 ## 14. Request review and propose next steps
 
+> [!CAUTION]
+> **FORBIDDEN next steps from this workflow**: You may ONLY propose `/write-be-spec` (next shard) or `/write-fe-spec` as the next step. Proposing `/plan-phase` or `/implement-slice` from this workflow is **strictly forbidden** — those require completed FE specs. This applies to ALL project types including CLI tools, bash scripts, and API-only services.
+
 Read .agent/skills/verification-before-completion/SKILL.md and follow its methodology.
 
 Use `notify_user` presenting:
 1. **Spec created** (link)
 2. **Cross-reference verification**
 3. **Ambiguity Gate confirmation**
-4. **Pipeline State** — read `.agent/progress/spec-pipeline.md` and propose next step
+4. **Pipeline State** — read `.agent/progress/spec-pipeline.md` and propose the next step from the **ONLY** permitted options below:
+
+- **More BE specs remain** → "Next: Run `/write-be-spec` for shard [next-shard-number]"
+- **All BE specs complete** → "All BE specs complete and `/audit-ambiguity be` has already run (mandatory Step 12 above). If it scored 0%, proceed to `/write-fe-spec`. If it found gaps, resolve them and re-run `/audit-ambiguity be` before proceeding."
+- **Self-audit found unresolvable issues** → Present the issues for discussion before proposing next step
+
+> [!IMPORTANT]
+> **No other next steps are valid.** `/plan-phase` requires both BE AND FE specs to be complete. After all BE specs pass audit, the mandatory next workflow is `/write-fe-spec`.

package/template/.agent/workflows/write-fe-spec-write.md

@@ -83,7 +83,14 @@ Use `notify_user` presenting:
 1. **Spec created** (link)
 2. **Cross-reference verification**
 3. **Ambiguity Gate confirmation**
-4. **Pipeline State** — read `.agent/progress/spec-pipeline.md` and propose next step
+4. **Pipeline State** — read `.agent/progress/spec-pipeline.md` and propose the next step from the **ONLY** permitted options below:
+
+- **More FE specs remain** → "Next: Run `/write-fe-spec` for shard [next-shard-number]"
+- **All FE specs complete** → "All FE specs complete and `/audit-ambiguity fe` has already run (mandatory Step 11 above). If it scored 0% and the Navigation Completeness Check passes (Step 14 below), proceed to `/plan-phase`. If gaps remain, resolve them first."
+- **Self-audit found unresolvable issues** → Present the issues for discussion before proposing next step
+
+> [!IMPORTANT]
+> `/plan-phase` is valid ONLY from this workflow, and ONLY when all FE specs show ✅, `/audit-ambiguity fe` scores 0%, and the Navigation Completeness Check (Step 14) passes.
 
 ## 14. Navigation Completeness Check