Skip to content

About

[Succeeded by mtwuser/zero-cloud-gravity] Historical v5.0.0 archive — Declarative Ubuntu 26.04 LTS system engine, Google Antigravity 2.0 Human-AI governance suite (4 bases + 3 stacks), and zero-dependency Contextual MCP Server (rcap1 capsules, ephemeral forks & Docker).

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

dotfiles-ubuntu

CI Version Coverage Python Ubuntu Antigravity License: MIT

Important

🚀 Architectural Succession & Permanent Historical Freeze (dotfiles-ubuntu v5.0.0 $\rightarrow$ ZeroCloudGravity v1.0.0) With the v5.0.0 milestone, dotfiles-ubuntu reaches its permanent historical freeze. Active development has been succeeded by ZeroCloudGravity (zero-cloud-gravity v1.0.0+) (zcg CLI + zcg-mcp), which cleanly decouples the agnostic Open-Source Zero-Cloud Node & Contextual MCP Engine (~/zero-cloud-gravity) from each operator's sovereign personal Root 0 workstation repository (~/<user-pc>). New installations and multi-layer organizations should adopt zero-cloud-gravity.

Declarative system manager, dotfile engine, and Distributed Human-AI Governance ("pAIr programming") Platform for Ubuntu 26.04 LTS ("Resolute Raccoon") and Google Antigravity 2.0 / Gemini (directly extrapolable to VS Code & GitHub Copilot, Cursor, and Claude Code).

This repository is modular and grounded in one unified fractal pattern (every governed directory combines a manifest, Markdown rules/skills, and task ledgers across Root 0 -> Department (1..N) -> Project using 4 Universal Human-AI Bases (human-stack) $\times$ 3 Specialization Stack Rings ({context,framework,plugin}-stack), executed deterministically via plain files, Git, and zero-dependency Python 3.14):

  1. Ubuntu System Backup, Audit & Restore (backup.sh, audit.sh, bootstrap.sh) — snapshot installed APT packages, Snaps, NPM globals, external recipes, and GNOME desktop settings into plain-text system/* manifests, audit system drift, or rebuild a machine from scratch.
  2. Dotfile Symlink Management (bash/, git/) — manage ~/.bashrc, ~/.profile, and ~/.gitconfig via GNU Stow while keeping personal identity and secrets in untracked local overrides (~/.bashrc.local, ~/.gitconfig.local).
  3. Local Antigravity 2.0 Governance (antigravity/, templates/) — composable AGENTS.md baselines (human-stack: universal-base, academic-base, science-base, business-base), 4 deterministic Python 3.14 lifecycle hooks (PreToolUse, PostToolUse, PostInvocation, Stop), 26 reusable skills (8 global human-stack + 7 context-stack + 7 framework-stack + 4 plugin-stack across /sopen, /sclose, /continue, /release, /enrich, /review, /audit, oss-contribute, academic-tutor, ledger-surface-audit, fastapi-testing, angular-testing, django-testing, nist-csf-audit, corporate-web-ops, corporate-backend-ops, layer-hub-ops, secops-mcp-orchestration, etc.), and 3 specialization stack rings completing the 4 × 4 = 16 Template Stack Matrix: context-stack (academic-curriculum, scientific-methodology, software-engineering, corporate-operations), framework-stack (fastapi-hexagonal, angular-frontend, django-fullstack, nist-csf-security), and plugin-stack (corporate-web-portal, corporate-admin-api, layer-hub-portal, secops-mcp-guardian).
  4. Multi-Layer Orchestrator & Contextual MCP Server (scripts/layer-config.sh, scripts/layer-subtree.sh, scripts/dotfiles_mcp_server.py) — deterministic file/Git/SHA-256 orchestrator (bootstrap-workspace, apply-project, make sync, make delegate, make task, make complete, make promote) plus a zero-dependency stdio JSON-RPC MCP server indexing layer Markdown into signed rcap1 (zlib + HMAC-SHA256) capsules (make consult).
Progressive Adoption Mode Who It Is For What Executes on Disk (0 External Servers Required)
Mode 1 — Individual Workstation Solo developer or manager on Ubuntu ./bootstrap.sh --workstation + set-global-profile symlinks ~/.gemini/config/ and keeps $HOME synced via dotfiles-sync.
Mode 2 — Standalone Project + Stack Any single software, ops, or research repo ./scripts/layer-config.sh apply-project <dir> --template <stack> projects .agents/rules/ and .agents/skills/ with SHA-256 drift tracking.
Mode 3 — Multi-Layer Organization Root 0 -> Department (1..N) -> Project bootstrap-workspace + layers/<child>/ (git subtree) + make delegate / make complete / make consult (rcap1 capsules).
Mode 4 — Engine Contributor (oss-dev) Maintaining or extending dotfiles-ubuntu make setup-dev + make verify runs the 8-stage deterministic verification gate (100% isolated 1:1 branch coverage).

Objective Engineering Virtues & Live Empirical Benchmarks (100% Python 3.14 Stdlib · 0 External Dependencies):

  • Deterministic $O(N)$ Structural Compaction (rcap1 L0/L1 + 2D Geometry): Enforcing < 465 lines/file, H1..H4 hierarchy, 1-line lead sentences, and > *"...*" mandate quotes turns Markdown specs into pre-indexed ASTs — achieving 88.7% (L0, 522 vs. 4,622 tok) and 67.0% (L1, 1,523 vs. 4,622 tok) compaction across 130k+ tokens in ~16 ms (0 LLM summarization calls, 0 vector DBs, and -76.3% single-envelope zlib-first capsule size at 518–577 chars/capsule). See Architecture 04 §2.9.
  • Content-Addressable Merkle Provenance (citation_receipt): Every section is pinned by <layer>::<file>#<slug>@<sha256_16>:<E3..E0>, enabling $O(1)$ cryptographic drift detection (CITATION_DRIFT_DETECTED), E3 > E2 > E1 > E0 monotonicity proofs (verify_epistemic_context_claims), and Q1..Q4 lifecycle telemetry.
  • Zero-Checkout C-Backed Git Plumbing (DMCP & GRCC): Multi-branch context projection reads git ls-tree / git cat-file directly from .git/objects (zero_checkout: true, 0 working-tree mutations) and chains encrypted capsules under refs/capsules/* without polluting refs/heads/*.
  • Mathematically Verified 1:1:1 Architecture: 37 production modules (25 executable in scripts/dotfiles_mcp/) $\leftrightarrow$ 37 1:1:1 test suites (100.00% isolated unit line and branch coverage, < 2s) $\leftrightarrow$ 6 normative architecture specifications (< 465 lines/file).

1. Navigation & Progressive Disclosure (docs/)

The documentation hub is organized into 3 progressive-disclosure tiers so humans and AI agents locate exact specifications in $O(1)$:

Tier What You Will Find Guide / Specification
Tier 1 (Gateway) Quick-Start paths, repository tree, CLI cheat-sheet, and subsystem lookup map. README.md (this file) · docs/README.md
Tier 2 (Human Guides) GNU Stow tree unfolding, system/* manifests & external recipes, daily usage, all bootstrap.sh & audit.sh modes, multi-machine setup/migration, Phase 0 Linear $HOME Control Tower Onboarding (Case 1), portability matrix, and uninstallation. docs/guides/01_ubuntu_system_and_multi_machine_guide.md
Tier 2 (Hierarchical Workflows) 4 Universal Human-AI Bases (human-stack: universal-base, academic-base, science-base, business-base), 26-skill matrix across 4 Universal Bases + 3 Specialization Stack Rings (context-stack, framework-stack, plugin-stack), scoped antigravity-agents workspaces, Root 0 -> Department -> Case/Unit/Squad -> Project setup blueprints, M1 -> M4 Personal Tutor Showcase & 4-Phase Customizable Kickoff Prompts (Cases 1–5), Git email authority gates, 1-hop horizon radar, and upward PR promotion. docs/guides/02_hierarchical_layers_and_team_workflows.md
Tier 3A (Normative Specs) 1:1:1 source-test-spec contracts (Specification:) for the Ubuntu engine, lifecycle hooks, MCP server, rcap1 compaction, surface weaver, ephemeral Department Bots, and layer governance/promotion engines. 01: System & Stow · 02: Governance & Hooks · 03: Contextual MCP · 04: Compaction & Weaver · 05: Ephemeral Bots · 06: Layer Governance
Tier 3B (Reference) Enterprise "pAIr programming" playbook, Cross-Departmental (0..80) & Human-Stack (85..95) Matrix, Docker/SSH MCP orchestration, and maintainer extension workflows. Enterprise Governance · Cross-Dept & Human-Stack · Contextual MCP Mesh · Maintainer Guide

2. Quick Start: 3 Main Ways to Use This Repository

Choose one of the three adoption paths below depending on whether you need standalone Antigravity governance, full Ubuntu workstation management, or multi-layer enterprise orchestration.

2.1. Path 1: Google Antigravity 2.0 Setup & Usage (Standalone)

Install global rules (~/.gemini/config/AGENTS.md), deterministic lifecycle hooks (hooks.json + scripts/), 8 universal global skills (~/.gemini/config/skills/), and desktop launchers without changing your shell, Git config, or Ubuntu packages:

git clone https://github.com/mtwuser/dotfiles-ubuntu.git ~/dotfiles-ubuntu
cd ~/dotfiles-ubuntu
./bootstrap.sh --workstation   # Sets up read-only runtime, boot auto-sync & dotfiles-sync command
                               # (or ./bootstrap.sh --antigravity for standalone Antigravity links only)

# Install/upgrade Antigravity Agents + agy CLI (Recommended; --ide is optional):
./scripts/antigravity-install.sh --agents   # or --cli (CLI only) / --ide (optional IDE) / --all

# Any time in terminal: pull latest release, re-apply global profile & re-stow
dotfiles-sync                               # or ./scripts/workstation-sync.sh --status

2.2. Path 2: Fork & Manage YOUR Own Ubuntu 26.04 System

Turn a fork of this repository into your personal Ubuntu 26.04 backup, audit, and recovery engine — ./backup.sh overwrites system/* with your machine's packages and GNOME settings:

# Phase A — Initialize your fork from your current Ubuntu 26.04 workstation
git clone https://github.com/<your-user>/dotfiles-ubuntu.git ~/dotfiles-ubuntu
cd ~/dotfiles-ubuntu
./backup.sh                # Captures YOUR APT, Snap, NPM, external recipes & GNOME settings
./audit.sh                 # Verifies 0 drift between your workstation and system/* manifests
./bootstrap.sh --stow      # Symlinks bash/, git/, and antigravity/ (preserves ~/.gitconfig.local)

# Phase B — Restore or provision a fresh Ubuntu 26.04 PC from your fork
./bootstrap.sh             # Interactive mode (or ./bootstrap.sh --all for unattended restore)
                           # Granular flags: --antigravity, --stow, --packages, --external, --nvm, --gnome

📖 Full details on GNU Stow tree unfolding, .audit-ignore, multi-machine migration, and uninstallation: docs/guides/01_ubuntu_system_and_multi_machine_guide.md.

2.3. Path 3: Enterprise & Multi-Tier Human-AI Governance (With or Without MCP)

Orchestrate Human-AI governance across Open Source (oss-dev / oss-readonly-appliance) $\leftrightarrow$ Root 0 (corporate-root: Public Administration 1..2 | Company 10) $\leftrightarrow$ Department (3..60, recursive 1..N: Statutory/Policy 3..9, Functional 15..40, Sub-Department / Unit / Squad 40..60) $\leftrightarrow$ Project / Case (project 80) (Mode A — Without MCP via pure Git + Stow + layer-config.sh static projection, or Mode B — With MCP via scripts/dotfiles_mcp_server.py and layers/* git subtree mounts):

flowchart TD
    SUB["Intrinsic Runtime Substrate\n(C-Backed Python Stdlib · PEP 7 · Ubuntu 26.04 Core)"]
    OSS["Open Source Upstream & Contributor Clone\n(operating_state: oss-dev · DOTFILES_DEV_REPO_DIR)"]
    APP["Local Workstation Appliance\n(operating_state: oss-readonly-appliance · ~/dotfiles-ubuntu)"]
    CORP["Level 1: Root 0 (Public Admin 1..2 | Enterprise Company 10 | Individual 90)\n(operating_state: corporate-root | individual-root · role: corporate · business-base)"]
    DEPT["Level 2: Statutory & Functional Departments\n(operating_state: domain-policy [3..9] | department [15..40] · {context,framework,plugin}-stack)"]
    SQUAD["Level 3: Sub-Departments, Operational Units, Tutors & Delivery Squads\n(role: department | squad · precedence: 40..60 | 86..89 · {context,framework,plugin}-stack)"]
    PROJ["Level 4: Application, Case & Service Projects\n(operating_state: project · precedence: 80 · Contextual Human-Stack 85..95)"]

    SUB <-->|"C-Backed Primitives &\nOSS-to-OSS Contributions"| OSS
    OSS -->|"workstation-sync.sh --sync\n(Read-Only $HOME Runtime)"| APP
    OSS <-->|"Downward: sync-upstream\nUpward: Anonymized PR (/enrich)"| CORP
    CORP <-->|"Downward: make delegate & make sync\nUpward: make complete & make promote"| DEPT
    DEPT <-->|"Downward: make delegate & make sync\nHorizontal: make consult (Ephemeral)"| SQUAD
    SQUAD <-->|"Downward: apply-project & make task\nUpward: make complete & /enrich (1-Hop PR)"| PROJ
Loading

📖 Step-by-step multi-tier commands, authority gates, 26-skill matrix, M1 -> M4 Personal Tutor Showcase, 4-Phase Customizable Kickoff Prompts (Cases 1–5), and scoped antigravity-agents workspace containment: docs/guides/02_hierarchical_layers_and_team_workflows.md and docs/reference/enterprise_pair_programming_governance.md.

2.3.1. Real-World Business View: 1 Company, 3 Departments & Specialized Squad Members

Imagine a company with Corporate Direction (Root 0) and 3 core departments (Legal, Engineering/Tech, and Brand/Marketing). Instead of working in isolated silos, each department defines its rules once (precedence: 0..100, where lower numbers carry higher authority), and any squad member combines the exact specialties their task requires inside Google Antigravity:

flowchart TD
    CORP["🏢 Company Direction (Root 0 · Precedence 10)\nShared identity, security & Single Source of Truth (SSoT) ledgers"]

    subgraph Depts["3 Core Departments (Each Owns Its Specialty Rules)"]
        LEG["⚖️ Dept 1: Legal & IP (Precedence 5)\nPrivacy (GDPR), IP & Contract Gates, Call Consent & Evidence-Backed Claims"]
        TECH["⚙️ Dept 2: Engineering / Tech (Precedence 25)\nClean Architecture, 100% Automated Tests & API Security"]
        MKT["🎨 Dept 3: Brand & Marketing (Precedence 30..35)\nVisual Identity, Tone of Voice, Campaigns & Social Channels"]
    end

    CORP --> LEG & TECH & MKT

    subgraph Workspaces["How Squad Members Combine Specialties for Real Tasks (via Antigravity)"]
        CASE1["👩‍⚖️ Case 1: LegalTech Member\n(Builds a Contract & Compliance Auditor MCP)\nOrder: Legal (5) -> Corp (10) -> Tech (25)\nResult: 100% tested code that never leaks a trade secret"]
        CASE2["📣 Case 2: Growth & Social Media Member\n(Builds an Automated Social Campaign Hub)\nOrder: Legal (5) -> Corp (10) -> Tech (25) -> Brand (30) -> Mkt (35)\nResult: Fast social publishing with OAuth safety, Brand lock & Evidence-Backed Claims"]
        CASE3["📞 Case 3: Transversal VoIP Service Team\n(Builds Company-Wide Telephony & Voice AI)\nOrder: Legal (5, call recording consent) -> Tech (25, SIP/SLA)\nResult: Shared VoIP service safely reusable by Legal, Sales & Support"]
    end

    LEG & TECH -->|"Combined in"| CASE1
    LEG & TECH & MKT -->|"Combined in"| CASE2
    LEG & TECH -->|"Combined in"| CASE3
    CASE3 -.->|"Consumed back as a governed capability by"| LEG & MKT
Loading

2.3.2. Comparing Outcomes: Traditional Silos vs. Cross-Departmental Composition

When a business need crosses specialties (for example, Legal needs a software tool or Marketing needs a social media bot), organizations can compare what happens across approaches:

Approach How the Task Is Executed What Happens in Practice (Functional Outcome)
❌ Traditional Way A: Hand Off to IT Silo Business writes a PDF specification and waits for IT to build it. Slow & Context-Blind: Weeks of alignment meetings; IT delivers working code that misses subtle legal, IP, or brand rules.
❌ Traditional Way B: Unmanaged "Shadow IT" Legal or Marketing builds a script/bot on their own with generic AI prompts. Fragile & Risky: Solves the immediate business goal, but with zero tests, hardcoded API keys, and high security/compliance risk.
✅ dotfiles-ubuntu Way 1: Business-Led (apply-project --parent-dir <dept> or make apply-template) A specialist inside Legal or Marketing builds the tool in their workspace while injecting Tech (25) rules. Domain-Driven & Engineered: The business department keeps full ownership and speed, while Antigravity enforces 100% tests, clean architecture, and security automatically.
✅ dotfiles-ubuntu Way 2: Tech-Led (layer-subtree.sh add <dept>) The Engineering squad builds the tool (or a transversal service like VoIP) while mounting Legal (5) and Brand (30) rules. Platform-Grade & Compliant: Engineers build scalable infrastructure where Antigravity blocks any code change that violates Legal (5) or Brand (30) rules before commit.

2.3.3. Summary of the 6 Reusable Organizational Patterns

Every cross-departmental workflow resolves to one of six composable governance patterns along the 0..100 Lex Superior spectrum:

Business / Functional Need Who Owns the Workspace Combined Rule Order (0..100 Lex Superior) How It Activates (1 Command) Effective Antigravity Agent Profile
1. Pure Departmental Governance (Contracts, IP Registries, Ledgers, SOPs) Root 0 or Department (Legal, Finance) universal-base + business-base (10) + <dept> (5..20) bootstrap-workspace / make sync Normative & SSoT Ledger Auditor (workspace_mode: business)
2. In-Department Automation (Scripts/tools inside a business repo) Department (Legal, Finance, Ops) <dept> (5..20) + business-base (10) + science-base + software-engineering (25) make apply-template (reversible via make sync) In-Situ Domain Automation Engineer (workspace_mode: hybrid)
3. Department-Owned Tech Product (e.g., LegalTech Contract/IP MCP) Legal (5) or Embedded Tech Squad Legal (5) $\rightarrow$ Corp (10) $\rightarrow$ Tech + FastAPI (25..50) apply-project <app> --parent-dir <dept> --template <stack> Software Architect Subordinated to Statutory/IP Law (hybrid)
4. Multi-Departmental Solution (e.g., Marketing + Social Media Hub) Marketing / Growth Squad (35) Legal/GDPR (5) $\rightarrow$ Corp (10) $\rightarrow$ Tech (25) $\rightarrow$ Brand (30) $\rightarrow$ Marketing (35) --parent-dir dept-marketing + layer-subtree.sh add (legal, brand) Full-Stack Growth Engineer Governed by Legal, Brand & Security
5. Transversal Enterprise Platform (e.g., Company-Wide VoIP Service) Platform service-node / squad (25) Inward: Legal (5, call consent) $\rightarrow$ Ops (20, SLA) $\rightarrow$ Tech/VoIP (25)
Outward: Exports templates/voip-pack + federated_mcps
Any department mounts layers/voip-platform or applies voip-pack Critical Infrastructure Provider (inward) / Governed Capability (outward)
6. Punctual Cross-Departmental Audit (e.g., Design checks IP/Contract Gate with Legal) Any consumer layer Active workspace + Ephemeral rcap1 Capsule (kr: true) make consult LAYER=dept-legal QUERY="..." Zero-Residue Read-Only Inter-Departmental Advisor (inter-layer)

2.3.4. Crystal-Clear Mental Model: $HOME (Organizational Membership) vs. Workspace (Active Case & Crossed Layers)

Every operator uses two orthogonal surfaces: $HOME (~/dotfiles-ubuntu or ~/<user-pc> via canonical symlink ~/dotfiles-ubuntu -> $DOTFILES_RUNTIME_DIR $\rightarrow$ ~/.gemini/config/AGENTS.md) defines which organization or department you belong to, while the active Workspace (<repo>/.agents/) defines what project, case, or administrative dossier you are solving today, which external knowledge libraries it mounts (layers/{geo-*,gov-*,sci-*,org-*}), which operational stack (context-stack, framework-stack, plugin-stack) governs how the layer operates and verifies, and your Consumer Viewpoint (Human-Stack M1..M4 at precedence: 85..95, adapting retrieval between academic-tutor-m1-m2 in docs/guides/ and professional-scientific-m3-m4 in docs/reference/):

Real-World Persona $HOME Global Baseline (~/dotfiles-ubuntu / ~/<user-pc>) Active Workspace & Crossed layers/* (0..80) Specialization Stack & Contextual Human-Stack (85..95) Effective Agent Behavior
1. Public Administration Chain (Public Root 0 $\rightarrow$ Public Dept $\rightarrow$ Civil Servant) • Public Admin: universal-base
• Dept Maintainer: public-gov-root (1)
• Civil Servant: dept-justice (3)
• Public Root 0: public-gov-root (1..2)
• Public Dept: dept-justice (3) & dept-territorial (4, statutes in docs/)
• Civil Servant: case-file-2026/ (80)
business-base + context-stack/scientific-methodology (domain-admin-law:M3) Enforces constitutional Root 0 (1..2), justice (3), and territorial (4) statutes; queries modular docs/ on demand (make consult).
2. Company / Law Firm Member Crossing Public Admin acme-dept-legal (15, inheriting acme-root at 10) Client case tax-appeal-case-x/ mounting layers/dept-justice (3) + layers/dept-tax (4) context-stack/{scientific-methodology,corporate-operations} (domain-civil-law:M4 + domain-tax-law:M2) Subordinates corporate strategy (10..15) to state justice/tax statutes (3..4); peer-level in civil law (M4), step-by-step verify on tax changes (M2).
3. Enterprise Tech Lead (M4) vs. Junior Squad Member (M1) Both stow acme-dept-tech (25, inheriting acme-root at 10) Both open checkout-api/ (50..80) Both apply framework-stack/fastapi-hexagonal; Lead sets domain-python:M4, Junior sets domain-python:M1 + soft-socratic-coach in .agents/SESSION.md Identical 100% test & architecture gates (0..80); Lead gets terse 4-channel execution (M4), Junior gets Socratic mentorship (M1).
4. Specialist Shifting Contexts (Same Person, Different Workspace) dept-research (20) or dept-legal (15) • Morning: Primary research/legal workspace
• Afternoon: Cross-cutting tax/compliance filing or Python tool (make apply-template)
• Morning: context-stack (domain-physics:M4)
• Afternoon: context-stack/software-engineering (domain-python:M1 + bridge-tech-for-business)
Mastery is contextual to the workspace: direct executive synthesis in their core science (M4), didactic guided scaffolding when crossing into code or tax (M1).
5. Individual Practitioner / Freelancer Default universal-base (workstation-sync.sh --setup) Any client or personal repo (apply-project) optionally mounting public layers/geo-* or layers/dept-* context-stack, framework-stack, or plugin-stack + optional personal Human-Stack in .agents/SESSION.md Full task-branch rigor (make task, make status, /review, /sclose) without needing a corporate Root 0.

📖 Full business, public-administration & architectural walkthroughs (Full 0..100 Deontic Spectrum, 5 $HOME vs. Workspace Personas, LegalTech MCP, Marketing Social Media Engine, and Transversal VoIP Platform): docs/reference/cross_departmental_and_human_stack_matrix.md.

2.3.5. From Zero to a Custom Governed Workspace in 3 Steps (Clone -> Open in Antigravity -> /sopen)

Once ~/dotfiles-ubuntu is installed in $HOME (./bootstrap.sh --workstation), initializing any new or freshly cloned repository (~/Projects/<your-repo>) requires zero manual CLI boilerplate:

  1. Create or clone your repository: git clone <url> ~/Projects/<your-repo> (or mkdir -p ~/Projects/<your-repo> && cd ~/Projects/<your-repo> && git init).
  2. Open the workspace in Antigravity: Add ~/Projects/<your-repo> under Projects in antigravity-agents (or run cd ~/Projects/<your-repo> && agy). Because ~/.gemini/config/skills/sopen/SKILL.md is stowed globally from $HOME, /sopen is immediately active in the empty folder (setup_state.state == "uninitialized").
  3. Run /sopen (interactive wizard or single-shot adapted prompt): Run bare /sopen for the interactive entity_kind × layer_role × stack_groups wizard, or paste the Customizable 4-Phase Initial Kickoff Prompt below (and use the 4-Step Upstream Upgrade Prompt whenever dotfiles-ubuntu or your parent layer advances):
# A. First-Time Workspace Onboarding & Purpose Customization (State U0/U1 -> State U2 "configured"):
/sopen — Bootstrap and customize this workspace [<layer-id>] (role: [corporate|domain-policy|department|squad|knowledge|project], precedence: [1..95], templates: [science-base,software-engineering,fastapi-hexagonal,geo-es,gov-es,sci-engineering]):
1. Phase A (Bootstrap, Auto-Cockpit & Purpose Alignment): Run bootstrap-workspace (which automatically installs, activates, and opens the node's default Cockpit Web in the browser at http://127.0.0.1:<8700+prec>/?env=dev), set our mission ([<1-sentence domain purpose>]), owner emails ([<owner@domain>,$(git config user.email)]), and Human-Stack ([domain-<area>:M1..M4]).
2. Phase B (Sovereign Rules & 1:1:1 Architecture): Tailor templates/<layer-id>/rules/<layer-id>.md with our domain invariants ([<RULE-01..03>]), replace all [Fill: ...] placeholders in README.md and .agents/LAYER_LINEAGE.md, and initialize docs/architecture/ and WORKTASK.md.
3. Phase C (Verification & Cross-Layer Consultation): Verify make consult against our mounted knowledge nodes (gov-*/geo-*/sci-*/org-*) using English technical terms or proper nouns (e.g. QUERY="thermodynamics" / "SHM" / "Tajo") and confirm 0 drift via make sync && make diff.
4. Phase D (Configured Transition & Live Cockpit Ready): Mark "- [x] Complete Layer Setup Blueprint..." in WORKTASK.md (transitioning setup_state.state to "configured"), refresh the live Node Cockpit (make activate-plugin — keep daemon_active: true so the browser panel remains live!), and output the initial git commit block.

# B. Ongoing 4-Step Upstream Upgrade & Version Reconciliation (State U2):
/sopen — Execute the 4-Step Upstream Upgrade & Version Reconciliation Flow:
1. Step 1 (Topology & Horizon Audit): Run make status, make horizon, and make upstream-diff.
2. Step 2 (Zero-Loss Reconciliation): Run make sync STRATEGY=reconcile (preserving templates/<layer-id>/rules/<layer-id>.md).
3. Step 3 (Selective Stack & Plugin Review): Verify active templates/plugins and confirm make diff (0 drift).
4. Step 4 (Environment Gate & Closure): Validate make env-gate ENV=tst|pre|pro and close via /sclose.

3. Natural Code Evolution, Command Consciousness & Reproducible Metrics

Code structure, CLI commands, and repository health evolve deterministically across three coupled axes:

3.1. 6-Stage Structural Evolution Ladder, Command Tiers (C1/C2/C3) & Bifurcated Age Loop

The diagram below maps how C1/C2/C3 command consciousness, the 6-stage code abstraction ladder, and the 14d/90d/180d age radar reinforce one another:

flowchart TD
    subgraph CMD["Command Consciousness Tiers (make status)"]
        C1["C1: Auto-Reflexive\n(status · diff · horizon · consult · verify · lint)"]
        C2["C2: Guided Tactical\n(task · sync · /continue · /sclose)"]
        C3["C3: Conscious Human-Gated\n(delegate · complete · promote · env-gate · /release)"]
        C1 --> C2 --> C3
    end

    subgraph EVO["6-Stage Structural Evolution (< 465 Lines, Probe E & 1:1:1 Subpackages)"]
        S1["1. Inline Expression"] --> S2["2. Pure Function"]
        S2 --> S3["3. Cohesive Class / @dataclass"]
        S3 --> S4["4. Catalog (dict) / Protocol"]
        S4 --> S5["5. 1:1:1 Module\n(tools_* · *_engine · NN_* · test_*)"]
        S5 --> S6["6. 1:1:1 Domain Subpackage\n(< 15 modules/dir · core/capsules/mcp_node/governance)"]
    end

    subgraph AGE["Bifurcated Age Radar (14d / 90d / 180d)"]
        TRIG["Prolonged Use Without Edits\n(> 90d Code/Specs · > 180d Policies)"]
        ALN["Trajectory A: Aligned (0 Drift)\nConsolidate -> Automate (C1) -> /enrich"]
        DRF["Trajectory B: Drifted / Compressed\nRefactor (6-Stage) -> Align 1:1:1 Spec"]
        TRIG --> ALN
        TRIG --> DRF
    end

    CMD --> EVO --> AGE
    ALN -.->|"Graduates Manual Steps to"| C1
    DRF -.->|"Escalates Abstraction in"| EVO
Loading

3.2. Value-Added Efficiency Metrics & Reproducible Human-Agent Validation Map

Both human operators and AI agents use this table as a verifiable conceptual contract to measure platform ROI and detect architectural drift across any governed repository:

Dimension / Lifecycle Point Reproducible Target Metric / Invariant Human & Architectural Value Added Agent Deviation / Drift Signal (Validation Gate)
1. Session Startup & Orientation (/sopen / make status) 1 CLI call (< 0.2s) returning operating_state, workspace_mode, command_tiers, horizon, and agent_diff Eliminates 6–8 slow shell/git/file probes at session start and prevents blind brain/ scans Multi-step manual git/ls probing on startup or attempting edits in oss-readonly-appliance
2. Context-Window & Compaction (AGENTS.md & rcap1) <= 18,000 bytes global AGENTS.md (universal-base ~8.9 KB); ~85% token savings at L1 Exon Skeleton (40–65 tokens/section) Zero rule eviction under Antigravity's 20,000-token inline budget; workspaces load only rules matching their workspace_mode TOKEN_BUDGET_EXCEEDED (> 18 KB), WORKSPACE_RULES_BUDGET_EXCEEDED (> 80 KB), or loading code rules in business mode
3. Natural Code Maintainability & 6-Stage Evolution < 465 lines hard cap (<= 400 target), Probe E ($M_{\text{cluster}} &lt; 1,200$), < 15 modules/dir (1:1:1 Subpackages), and O(1) file-prefix taxonomy (tools_*, *_engine, NN_*, test_*) Prevents God Components, coupled cluster drift, and flat-directory overload; every subpackage and module's 1:1:1 triad (Spec <-> Test <-> Code) is discoverable in $O(1)$ File >= 465 lines ([max-file-lines]), directory >= 15 modules, cross-engine _private imports, or missing Specification: pointer
4. Bidirectional 1:1:1 Test Symbiosis (Unit -> Imp -> E2E) 100.00% single-file isolated unit statement + branch coverage (0 Cross-Unit Masking), < 1s per unit test, # Arrange / # Act / # Assert, 0-byte __init__.py Self-documenting executable specs (Top-Down E2E -> Imp -> Unit reading; Bottom-Up Unit -> Imp -> E2E execution where each test_<mod>.py reaches 100% alone) Coverage < 100% in single-file isolation, missing AAA markers ([missing-aaa]), non-empty __init__.py ([init-purity]), or duplicate *Expanded/*Coverage test classes
5. Inter-Layer Governance & Stage Gates (dev -> tst -> pre -> pro) Strict 1-hop horizon, 5-role contextual & hierarchical authority (owner, maintainer, validator, member, consumer), 4-state $N$-departmental consensus (RECONCILED_FLOW $\rightarrow$ ESCALATE_TO_ROOT), and non-destructive .agents/proposals/ staging Unifies Business (Root 0 / Department SSoT ledgers, internal vs external entity lineage, & Lex Superior 0..100) and Technical (Squad / Project) delivery on feature/<TICKET-ID>-<slug> CROSS_TIER_PROMOTION_BYPASS, INHERITED_UPSTREAM_ASSET_IMMUTABLE, CROSS_DEPT_ESCALATION_TO_ROOT_REQUIRED, open P0 in tst, or unchecked WORKVALI.md items in pre
6. Bifurcated Age & Consolidation Radar (14d / 90d / 180d) Proposals <= 14d; Code/Specs reviewed at 90d; Policies/Templates reviewed at 180d Untouched artifacts aligned in active use graduate to C1 automation or /enrich; drifted artifacts are refactored before debt compounds Unresolved stale_proposals (> 14d), Source modified without updating its 1:1:1 Spec, or split idioms inside a touched module
7. OOP Capability Rings, Permanent $\leftrightarrow$ Ephemeral Symbiosis & rcap1 Membrane 5 CRUD rings (R0..W), 5-family Bot Catalog, Autonomous (R0..R2) vs. Actionable (W) MCP governance, hot-plug ephemeral-augmented leases (Zero Standing Privileges), and rcap1 Return Digest Membrane (seal-return / verify-return) Combines ~85% L1 token compaction, live Permanent $\leftrightarrow$ Ephemeral capability augmentation, and Crypto-Shredding (EPHEMERAL_LEASE_EXPIRED_OR_SHREDDED & SURFACE_BOUNDARY_VIOLATION) Running a live multi-tenant MCP hub on oss-dev, requesting write access on an inter-layer fork or validator role, or returning unsealed digests outside leased surface_globs

4. Repository Structure

The directory tree separates top-level GNU Stow OS dotfile modules (bash/, git/, and antigravity/ materializing the Google Antigravity 2.0 + Gemini runtime directly into ~/.gemini/config/ via stow -t ~ -R bash git antigravity) from non-stow system manifests, the 4 × 4 = 16 polymorphic template stack matrix (templates/{human,context,framework,plugin}-stack/*), docs/, and the 4-subpackage MCP engine:

~/dotfiles-ubuntu/
├── bash/                              ← stow module: ~/.bashrc, ~/.profile
├── git/                               ← stow module: ~/.gitconfig (includes ~/.gitconfig.local)
├── antigravity/                       ← stow module: ~/.gemini/config/* & ~/.local/share/applications/*
│   ├── .gemini/config/
│   │   ├── AGENTS.md                  ←   Global baseline (< 18 KB token budget cap)
│   │   ├── hooks.json                 ←   Lifecycle hook bindings (PreToolUse, PostToolUse, PostInvocation, Stop)
│   │   ├── scripts/                   ←   pre_tool_guard.py, post_edit_format.py, post_invocation_lint.py, stop_verify_tests.py
│   │   └── skills/                    ←   8 universal global skills (sopen, sclose, continue, enrich,
│   │                                      review, audit, architecture, governance)
│   └── .local/share/applications/     ←   antigravity-agents.desktop, antigravity-ide.desktop
│
├── docs/                              ← NOT stow — 3-tier navigable documentation hub (< 465 lines per file)
│   ├── README.md                      ←   Documentation index, Mermaid subsystem map & quick lookup
│   ├── guides/                        ←   Tier 2: Human operator & squad workflow guides
│   │   ├── 01_ubuntu_system_and_multi_machine_guide.md  ← Stow unfolding, manifests, bootstrap/audit & multi-machine sync
│   │   └── 02_hierarchical_layers_and_team_workflows.md ← 3-tier profiles, multi-layer lifecycle, authority & PR promotion
│   ├── architecture/                  ←   Tier 3A: Normative technical specifications (1:1:1 with code & unit tests)
│   │   ├── 01_system_and_stow_engine.md                    ← Ubuntu 26.04 engine, 3-stage APT filter, Stow
│   │   ├── 02_antigravity_governance_and_hooks.md          ← Token budget, 4 hook 1:1:1 contracts, 26 skills (8 global + 7 context-stack + 7 framework-stack + 4 plugin-stack)
│   │   ├── 03_contextual_mcp_and_federation.md             ← Zero-dependency MCP server protocol & schema (mcp-layer-v1)
│   │   ├── 04_compaction_surface_and_promotion_engines.md  ← rcap1 compaction & 0..N surface weaver (Subpackage 2: capsules/)
│   │   ├── 05_ephemeral_forks_and_department_bots.md       ← OOP capability rings, symbiotic Department Bots, rcap1 return membrane & TTL GC
│   │   └── 06_layer_governance_and_promotion_engines.md    ← Fork configurator, bootstrapper, authority, horizon, workflow & git-gov (Subpackage 4: governance/)
│   └── reference/                     ←   Tier 3B: Enterprise use cases & maintainer extension guides
│       ├── enterprise_pair_programming_governance.md         ← Enterprise Human-AI governance & Copilot mapping
│       ├── cross_departmental_and_human_stack_matrix.md      ← Cross-Departmental Contextual Algebra (0..80) & Human-Stack Matrix (85..95)
│       ├── contextual_mcp_and_multi_service_orchestration.md ← Node/Container MCP & multi-service orchestration
│       └── developer_and_extension_guide.md                  ← Maintainer playbook for evolving dotfiles-ubuntu
│
├── templates/                         ← NOT stow — 2-level polymorphic template taxonomy (human-stack/*, context-stack/*, framework-stack/*, plugin-stack/*)
├── scripts/                           ← NOT stow — CLI orchestrators, Contextual MCP Server & CI verification
│   ├── antigravity-install.sh         ←   Install/update Antigravity Agents, agy CLI & optional IDE
│   ├── audit-global-config.sh         ←   Verify ~/.gemini/config/ tree-unfolded symlinks & orphans
│   ├── workstation-sync.sh            ←   Workstation appliance setup (--setup), boot auto-sync & dotfiles-sync CLI
│   ├── dotfiles_mcp/                  ←   Modular Contextual MCP & Layer Orchestration package (4 domain subpackages, 27 modules)
│   │   ├── core/                      ←     1. Base Contracts, Catalogs & Topology Primitives (0 engine dependencies)
│   │   │   ├── constants.py, catalogs.py  ←   Declarative constants, regexes & MCP resource/tool/prompt catalogs
│   │   │   ├── manifest_helpers.py        ←   System manifest, skill frontmatter, SHA-256 & template schema helpers
│   │   │   └── blueprint_renderer.py, layer_topology_helpers.py ← Layer Makefile/onboarding renderers & subtree drift sync
│   │   ├── capsules/                  ←     2. Cryptographic Encapsulation (rcap1), Decapsulation & Surface Filtering
│   │   │   ├── capsule_engine.py          ←   Resonant rcap1 L0->L3 sealing, HMAC-SHA256 & ephemeral return digest membrane
│   │   │   ├── surface_weaver.py          ←   Stack-agnostic surface selector inference & Lex Specialis scoring
│   │   │   ├── tools_compaction.py        ←   Multi-resolution query_governance_rules & capsule minting
│   │   │   ├── tools_unfold.py            ←   Hop-by-hop unfold_context_capsule & TOCTOU line-drift relocation
│   │   │   └── tools_surface.py           ←   0..N resolve_surface_governance weaver & delegation advisories
│   │   ├── mcp_node/                  ←     3. OOP MCP Kernel, Capability Rings, Bot Catalog & Permanent <-> Ephemeral Symbiosis
│   │   │   ├── node_base.py, resources.py ←   Base node path-containment, warnings & 9 MCP resource readers
│   │   │   ├── capability_registry.py, dmcp_grcc_engine.py ← OOP permission rings, bot catalog & DMCP/GRCC capsule engine
│   │   │   ├── tools_federation.py        ←   Overview, drift audit, doc reader & federated MCP discovery tools
│   │   │   ├── ephemeral_fork_engine.py   ←   Zero-copy ephemeral Department Bot forks, project bridges & TTL GC
│   │   │   └── tools_ephemeral.py, server.py← orchestrate_ephemeral_fork tool & JSON-RPC 2.0 dispatcher
│   │   └── governance/                ←     4. Inter-Layer Lifecycle, 1-Hop Horizon, RBAC Authority & Promotion Engines
│   │       ├── fork_configurator.py       ←   Fork parameterization (init-fork), template scaffolding & apply-project
│   │       ├── workspace_bootstrapper.py  ←   Global profile composer (set-global-profile), subtree registrar & bootstrap-workspace
│   │       ├── workflow_engine.py         ←   Task-branch workflow (start/complete-task), 1-hop delegation & consult-layer
│   │       ├── git_governance_engine.py   ←   Git branch policy, dev->tst->pre->pro env gates, non-destructive staging & audit ledger
│   │       ├── authority_engine.py        ←   Layer owner vs. consumer authority gate (set/check-authority) & upward PR planner
│   │       ├── promotion_engine.py, plugin_service_engine.py ← Multi-layer pattern routing, promote-from-project & plugin services
│   │       ├── horizon_engine.py          ←   1-hop horizon radar (inspect-horizon), upstream section diff & 4-mode template reconciliation
│   │       └── cli_dispatcher.py          ←   Tiered 26-subcommand CLI dispatcher (C1/C2/C3/Ephemeral families) for layer-config.sh
│   ├── dotfiles_mcp_server.py         ←   Zero-dependency read-only Contextual MCP Server CLI entrypoint (stdio)
│   ├── layer-config.sh                ←   Layer parameterization, workspace bootstrap, authority, horizon & promotion CLI
│   ├── layer-subtree.sh               ←   Upstream fork sync & git subtree context graph manager (layers/*)
│   └── verify-repo.sh                 ←   Deterministic 8-stage CI & pre-commit verification suite
│
├── system/                            ← NOT stow — declarative system manifests (packages-manual.txt, snaps.txt, npm-globals.txt,
│                                        external.txt, gnome-*, nvm-default.txt, mcp-layer.json) & system/external/ recipe catalog
├── tests/                             ← NOT stow — automated test suite (tests/unit/, tests/imp/, tests/e2e/ — 100% branch coverage)
└── bootstrap.sh, backup.sh, audit.sh, Dockerfile, Makefile, pyproject.toml, VERSION, CHANGELOG.md, SECURITY.md, CONTRIBUTING.md

5. Lifecycle Hooks & CLI Orchestrator Cheat-Sheet

Daily governance and multi-layer operations are enforced by four Python 3.14 lifecycle hooks and the 26-subcommand layer-config.sh CLI:

5.1. Deterministic Python 3.14 Lifecycle Hooks (antigravity/.gemini/config/)

  • pre_tool_guard.py (PreToolUse) — Blocks non-empty writes (> 0 bytes) to consumer src/**/__init__.py or tests/**/__init__.py, manual edits to alembic/versions/*.py, and direct edits to inherited .agents/rules/layer-*.md across both file-write tools and run_command shell redirections (heredoc, tee, sed -i, cp/mv, dd, inline python -c), plus automatic execution of mutating git (add, commit, push, reset, reset --hard, rebase, checkout, merge, clean, clean -f, subtree) or alembic (revision, upgrade, downgrade, stamp, merge, edit) commands.
  • post_edit_format.py (PostToolUse) — Runs ruff format automatically on modified .py files.
  • post_invocation_lint.py (PostInvocation) — Enforces < 465 lines on modified .py, root README.md, and docs/**/*.md files, AAA test markers, 1:1:1 Specification: headers, ruff check, and always_on rule token budgets (18,000-byte AGENTS.md cap & 80,000-byte workspace cap) with force_continue.
  • stop_verify_tests.py (Stop) — Runs affected unit tests before concluding a task.

5.2. Multi-Layer CLI Orchestrator (./scripts/layer-config.sh — All 26 Subcommands)

All 26 subcommands of ./scripts/layer-config.sh are grouped below by template projection, workspace bootstrap, authority/promotion gates, and ephemeral forks:

# Template discovery, fork parameterization & static project projection:
./scripts/layer-config.sh list-templates
./scripts/layer-config.sh init-fork --id acme-dept-design --role department --precedence 30 --entity-kind enterprise --governing-root acme-corp-root --prune-default-templates
./scripts/layer-config.sh scaffold-template brand-design-system --kind context-stack --register-binding
./scripts/layer-config.sh apply-project <your-project> --template fastapi-hexagonal --layers all

# Global profile composition, subtree mounting & hierarchical workspace bootstrap/sync/status:
./scripts/layer-config.sh set-global-profile universal-base --lang en --stow
./scripts/layer-config.sh register-subtree dept-legal https://github.com/acme/dept-legal.git master
./scripts/layer-config.sh bootstrap-workspace /path/to/dept-legal --id dept-legal-ip --role domain-policy --precedence 5 --templates business-base --lang en
./scripts/layer-config.sh sync-layer /path/to/dept-legal --parent-dir /path/to/corporate-root --strategy reconcile
./scripts/layer-config.sh status <your-project>

# Layer owner vs. consumer authority gates, roster, 1-hop horizon, delegation, feature/<TICKET-ID>-slug & completion:
./scripts/layer-config.sh set-authority /path/to/dept-legal --owner-role "CLO" --emails "clo@acme.com"
./scripts/layer-config.sh manage-roster /path/to/dept-legal --add "qa@acme.com" --role validator
./scripts/layer-config.sh check-authority /path/to/dept-legal --op release --email "clo@acme.com"
./scripts/layer-config.sh configure-git-policy /path/to/dept-legal --protected main,master,env/pre,env/pro
./scripts/layer-config.sh check-env-promotion <your-project> --to-env pre --files "surfaces/web/terms.html" --email "qa@acme.com"
./scripts/layer-config.sh record-decision <your-project> --item ".agents/proposals/from-root/policy.md" --decision approve --reason "Reviewed"
./scripts/layer-config.sh inspect-horizon /path/to/corporate-root
./scripts/layer-config.sh compare-upstream /path/to/corporate-root --apply-safe
./scripts/layer-config.sh delegate-to-child /path/to/corporate-root --to-child dept-legal --task "Publish GDPR policy" --ticket LEGAL-2026-004
./scripts/layer-config.sh start-task <your-project> --task "LEGAL-2026-004"
./scripts/layer-config.sh complete-task <your-project> --task "LEGAL-2026-004" --deliverable "corporate/gdpr.md"
./scripts/layer-config.sh diff-project <your-project>
./scripts/layer-config.sh promote-from-project <your-project> --source .agents/rules/rule.md --create-pr

# Ephemeral Department Bot forks (TTL-bounded zero-copy sandboxes & 1-shot consultations):
./scripts/layer-config.sh consult-layer <your-project> --layer dept-legal --query "GDPR retention"
./scripts/layer-config.sh spawn-ephemeral --role dept-qa-bot --templates fastapi-hexagonal --tier flash --ttl 300
./scripts/layer-config.sh inspect-ephemeral --catalog
./scripts/layer-config.sh reap-ephemeral --id all

6. Development, Testing, Virtual Environment & CI

dotfiles-ubuntu separates zero-dependency runtime execution (requirements.txt — 0 packages in upstream; 100% Python 3.14 Standard Library for hooks and scripts/dotfiles_mcp_server.py) from development/testing tools (requirements-dev.txt — chains -r requirements.txt + pytest, pytest-cov, ruff, mypy, shellcheck-py):

cd ~/dotfiles-ubuntu
make install                                  # Create ./venv and install requirements-dev.txt
make test-cov                                 # Run unit + imp + e2e tests with 100.00% branch coverage gate
make lint                                     # Run ruff check + mypy --strict
make verify                                   # Run the full 8-stage deterministic CI verification suite
make docker-build && make docker-self-test    # (Optional) Build & verify Ubuntu 26.04 MCP Docker image

6.1. Versioning, Security & Contributing

About

[Succeeded by mtwuser/zero-cloud-gravity] Historical v5.0.0 archive — Declarative Ubuntu 26.04 LTS system engine, Google Antigravity 2.0 Human-AI governance suite (4 bases + 3 stacks), and zero-dependency Contextual MCP Server (rcap1 capsules, ephemeral forks & Docker).

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages