Important
🚀 Architectural Succession & Permanent Historical Freeze (dotfiles-ubuntu v5.0.0 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):
- 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-textsystem/*manifests, audit system drift, or rebuild a machine from scratch. - Dotfile Symlink Management (
bash/,git/) — manage~/.bashrc,~/.profile, and~/.gitconfigvia GNU Stow while keeping personal identity and secrets in untracked local overrides (~/.bashrc.local,~/.gitconfig.local). - Local Antigravity 2.0 Governance (
antigravity/,templates/) — composableAGENTS.mdbaselines (human-stack:universal-base,academic-base,science-base,business-base), 4 deterministic Python 3.14 lifecycle hooks (PreToolUse,PostToolUse,PostInvocation,Stop), 26 reusable skills (8globalhuman-stack+7context-stack+7framework-stack+4plugin-stackacross/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 the4 × 4 = 16Template Stack Matrix:context-stack(academic-curriculum,scientific-methodology,software-engineering,corporate-operations),framework-stack(fastapi-hexagonal,angular-frontend,django-fullstack,nist-csf-security), andplugin-stack(corporate-web-portal,corporate-admin-api,layer-hub-portal,secops-mcp-guardian). - 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-dependencystdioJSON-RPC MCP server indexing layer Markdown into signedrcap1(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 ·0External Dependencies):
- Deterministic
$O(N)$ Structural Compaction (rcap1L0/L1+ 2D Geometry): Enforcing< 465lines/file,H1..H4hierarchy, 1-line lead sentences, and> *"...*"mandate quotes turns Markdown specs into pre-indexed ASTs — achieving88.7%(L0,522vs.4,622tok) and67.0%(L1,1,523vs.4,622tok) compaction across130k+tokens in~16 ms(0LLM summarization calls,0vector DBs, and-76.3%single-envelopezlib-first capsule size at518–577chars/capsule). SeeArchitecture 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 > E0monotonicity proofs (verify_epistemic_context_claims), andQ1..Q4lifecycle telemetry.- Zero-Checkout C-Backed Git Plumbing (
DMCP&GRCC): Multi-branch context projection readsgit ls-tree/git cat-filedirectly from.git/objects(zero_checkout: true,0working-tree mutations) and chains encrypted capsules underrefs/capsules/*without pollutingrefs/heads/*.- Mathematically Verified
1:1:1Architecture:37production modules (25executable inscripts/dotfiles_mcp/)$\leftrightarrow$ 371:1:1test suites (100.00%isolated unit line and branch coverage,< 2s)$\leftrightarrow$ 6normative architecture specifications (< 465lines/file).
The documentation hub is organized into 3 progressive-disclosure tiers so humans and AI agents locate exact specifications in
| 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 |
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.
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 --statusTurn 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.
Orchestrate Human-AI governance across Open Source (oss-dev / oss-readonly-appliance) Root 0 (corporate-root: Public Administration 1..2 | Company 10) Department (3..60, recursive 1..N: Statutory/Policy 3..9, Functional 15..40, Sub-Department / Unit / Squad 40..60) 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
📖 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.
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
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. |
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) Corp (10) 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) Corp (10) Tech (25) Brand (30) 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) Ops (20, SLA) 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 ~/.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.
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:
- Create or clone your repository:
git clone <url> ~/Projects/<your-repo>(ormkdir -p ~/Projects/<your-repo> && cd ~/Projects/<your-repo> && git init). - Open the workspace in Antigravity: Add
~/Projects/<your-repo>under Projects inantigravity-agents(or runcd ~/Projects/<your-repo> && agy). Because~/.gemini/config/skills/sopen/SKILL.mdis stowed globally from$HOME,/sopenis immediately active in the empty folder (setup_state.state == "uninitialized"). - Run
/sopen(interactive wizard or single-shot adapted prompt): Run bare/sopenfor the interactiveentity_kind × layer_role × stack_groupswizard, or paste the Customizable 4-Phase Initial Kickoff Prompt below (and use the 4-Step Upstream Upgrade Prompt wheneverdotfiles-ubuntuor 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.
Code structure, CLI commands, and repository health evolve deterministically across three coupled axes:
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
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 (< 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 |
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 RECONCILED_FLOW 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 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 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
|
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
Daily governance and multi-layer operations are enforced by four Python 3.14 lifecycle hooks and the 26-subcommand layer-config.sh CLI:
pre_tool_guard.py(PreToolUse) — Blocks non-empty writes (> 0 bytes) to consumersrc/**/__init__.pyortests/**/__init__.py, manual edits toalembic/versions/*.py, and direct edits to inherited.agents/rules/layer-*.mdacross both file-write tools andrun_commandshell redirections (heredoc,tee,sed -i,cp/mv,dd, inlinepython -c), plus automatic execution of mutatinggit(add,commit,push,reset,reset --hard,rebase,checkout,merge,clean,clean -f,subtree) oralembic(revision,upgrade,downgrade,stamp,merge,edit) commands.post_edit_format.py(PostToolUse) — Runsruff formatautomatically on modified.pyfiles.post_invocation_lint.py(PostInvocation) — Enforces< 465lines on modified.py, rootREADME.md, anddocs/**/*.mdfiles, AAA test markers,1:1:1Specification:headers,ruff check, andalways_onrule token budgets (18,000-byteAGENTS.mdcap &80,000-byte workspace cap) withforce_continue.stop_verify_tests.py(Stop) — Runs affected unit tests before concluding a task.
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 alldotfiles-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- Semantic Versioning: Tracked in
VERSION(5.0.0) andCHANGELOG.md(ongoing changes accumulate under## [Unreleased]and are promoted via/release). All CLI scripts support--version/-v. - Security & Secret Isolation: Personal Git identity (
~/.gitconfig.local) and shell secrets (~/.bashrc.local) are strictly isolated from tracked files; seeSECURITY.md. - Contributing & Extending: See
CONTRIBUTING.mdanddocs/reference/developer_and_extension_guide.md.