Skip to content

v1.4.0 - Elephant-Goldfish context contracts, drift auditing, and Paraphrase-First review gates

Latest

Choose a tag to compare

@rumotion rumotion released this 10 Nov 01:54

v1.4.0 - Elephant-Goldfish context contracts, drift auditing, and Paraphrase-First review gates

This release integrates core mechanisms from Google's Elephant-Goldfish Model (EGM) natively into the template across Claude Code, OpenAI Codex, Google Gemini / Antigravity, and Cline, while keeping zero external plugin dependencies and preserving the sub-9,500-character FAST_INIT startup ceiling.

Highlights

  • Bottom-up module context contracts (docs/peanuts-and-hay.md, workflows/bootstrap-context.md):
    • Generate leaf component contracts (Peanuts: Overview, Interface, Invariants, Side Effects, Verification) and subsystem blueprints (Hay) under the Re-Implementation Standard so fresh sessions can navigate module boundaries in 1-2 file reads without loading raw source code into startup context.
    • Supports both README.md (default) and CONTEXT.md mode (when existing human-facing README.md files must remain untouched), with incremental BFS discovery and a mandatory > 15 directory confirmation gate.
  • Spec & contract drift auditing (workflows/drift-report.md):
    • Read-only, sequential document-to-code audit that compares specs, Peanuts & Hay contracts, and Memory Bank architecture docs against the working tree across four categories: Missing Features, Incomplete Models, Logic Shortcuts, and Architectural Divergence.
    • Verified in a two-model blind simulation (Claude Stage 1 + Codex Stage 2) that caught 100% of seeded discrepancies across all four categories with zero false positives.
  • Paraphrase-First, Zoom-Out, Zero-Decision, and Contradiction gates:
    • docs/reviewer-role.md and workflows/critic-review.md require a paraphrase: comprehension summary before emitting findings and enforce a Zoom-Out codebase reuse check.
    • workflows/spec-driven-development.md and workflows/plan-task.md enforce the Zero-Decision Rule so specifications and plans resolve file paths, interfaces, defaults, and failure behavior up front.
    • .agents/rules/30-cognitive-harness.md adds a Contradiction Gate that halts before file edits when user instructions conflict with checked-in specs or module contracts.
  • 24,000-byte skill load ceiling & full scripts/README.md Peanuts contract:
    • scripts/check-template.py enforces SKILL_MAX_BYTES = 24_000 across all 24 canonical and mirrored skills and validates the paraphrase: reviewer contract marker.
    • scripts/README.md is now a verified Peanuts module contract covering every script's argparse interface, exit codes, hook denial payloads, state paths, invariants, and side effects.

How to start a new project

python scripts/new-project.py ../my-project --name "My Project"
cd ../my-project
python scripts/init-fast.py

Open ../my-project in your coding agent and start with:
FAST_INIT (default mode per AGENTS.md).

How to quickly upgrade an existing project from GitHub

1. First-time upgrade (or installing into an existing repo)

Open your existing project in Claude Code, Codex, or Antigravity and paste:

Upgrade this project's AI framework from
https://github.com/rumotion/ai-agent-project-template using its latest upgrade
workflow. Preserve application code, tests, settings, custom rules, skills and
project memory. Preview changes, resolve conflicts and run the project's checks.
Do not push or deploy.

2. Subsequent upgrades (one sentence)

After the first remote upgrade, the project remembers the template source and
file hashes in .template-upstream.json. Next time, simply ask your agent:

Update this project from its saved AI template source and verify the result locally.

3. Direct CLI preview and apply (local or directly from GitHub)

# From a local checkout of this template:
python scripts/upgrade-target.py --target ../existing-project --dry-run
python scripts/upgrade-target.py --target ../existing-project --apply-safe

# Or directly from GitHub pinned to v1.4.0:
python scripts/upgrade-target.py --target ../existing-project \
  --source https://github.com/rumotion/ai-agent-project-template \
  --ref v1.4.0 --dry-run

Verification and limits

Full validation (python scripts/check-template.py) covers 206 required files,
10 instruction adapters, 17 context budgets, 24 skills across 3 discovery trees,
and 15 hardening/recovery suites (23 upgrade preservation tests in scripts/verify-upgrade.py).

Upgrade guide
| Peanuts & Hay guide
| Changes since v1.3.1.