/install-maintain - Install Script Maintenance

Automates the complete lifecycle of CODITECT install script maintenance - from error report to GCS deployment.

System Prompt

EXECUTION DIRECTIVE: When the user invokes /install-maintain, execute the install script maintenance workflow:

1. If error report provided: Classify, analyze, fix, and deploy
2. If --analyze-only: Run analysis without making changes
3. If --deploy-only: Deploy current version to GCS
4. If --rollback: Restore previous GCS version

---

Usage

# Full workflow: analyze, fix, and deploy
/install-maintain "User reports: FileNotFoundError in session-retrospective.py"

# Analyze only (no changes)
/install-maintain --analyze-only

# Deploy current version to GCS
/install-maintain --deploy-only

# Rollback to previous version
/install-maintain --rollback

# Verbose output
/install-maintain --verbose "Error report here"

Options

Option	Short	Description
--analyze-only	-a	Run analysis without making changes
--deploy-only	-d	Deploy current version to GCS
--rollback	-r	Restore previous GCS version
--verbose	-v	Show detailed output
--dry-run		Preview changes without executing

Workflow Phases

Phase 1: Error Intake

• Parse error report
• Classify issue type (hardcoded_path, missing_file, schema_mismatch, etc.)
• Assign severity and task ID

Phase 2: Analysis

• Run automated checks
• Identify root cause
• Generate fix recommendations

Phase 3: Fix Implementation

• Apply fixes using Edit tool
• Update version number
• Validate syntax

Phase 4: Cross-Check

• Validate ADR-057 compliance
• Validate ADR-103 compliance
• Run hook validator

Phase 5: Git Operations

• Stage changes
• Create commit with conventional format

Phase 6: GCS Deployment

• Backup current version to .bak
• Upload new version with cache-control headers
• Set Cache-Control: no-store, no-cache, must-revalidate, max-age=0
• Force CDN cache invalidation

Phase 7: Post-Deploy Validation

• Health check via gcloud (bypasses CDN)
• Health check via curl with cache-busting query string
• Verify CDN cache-control headers
• Automatic rollback on failure

Examples

Process Error Report

/install-maintain "User on fresh macOS install gets 'no such table: projects'"

Expected Output:

Install Script Maintenance - F.1.1

Phase 1: Error Intake
- Issue Type: schema_mismatch
- Severity: critical
- Task ID: F.1.1

Phase 2: Analysis
- Root Cause: ADR-103 projects.db not initialized
- Line 456: Missing projects.db schema creation

Phase 3: Fix
- Applied: Added projects.db initialization
- Version: 2.7.0 -> 2.7.1

Phase 4: Cross-Check
- ADR-057: PASS
- ADR-103: PASS
- Hook Validator: PASS

Phase 5: Git
- Commit: abc123def
- Message: fix(install-script): Add projects.db initialization per ADR-103

Phase 6: GCS Deployment
- Backup: coditect-install.py.bak
- Upload: SUCCESS
- URL: https://storage.googleapis.com/coditect-dist/coditect-install.py

Phase 7: Health Check
- Download: OK
- Syntax: PASS
- Version: 2.7.1 matches

SUCCESS: Install script v2.7.1 deployed

Analyze Only

/install-maintain --analyze-only

Expected Output:

Install Script Analysis

Hardcoded Paths: 0 found
Syntax: VALID
ADR-057: COMPLIANT
ADR-103: COMPLIANT
Hook Configuration: VALID

No issues detected.

Deploy Only

/install-maintain --deploy-only

Expected Output:

Deploying current version to GCS...

Pre-flight: PASS
Backup: coditect-install.py.bak created
Upload: SUCCESS
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
Health Check (gcloud): v2.8.0 ✓
Health Check (CDN): v2.8.0 ✓

Deployed: v2.8.0 to gs://coditect-dist/coditect-install.py
URL: https://storage.googleapis.com/coditect-dist/coditect-install.py

CDN Cache Note: If CDN still serves old version, use query string to bypass:

https://storage.googleapis.com/coditect-dist/coditect-install.py?v=2.8.0

Rollback

/install-maintain --rollback

Expected Output:

Rolling back to previous version...

Current Version: 2.7.1
Backup Version: 2.7.0

Restoring backup...
Health Check: PASS

Rolled back to v2.7.0

Issue Types

Type	Description	Auto-Fixable
hardcoded_path	Absolute paths like /Users/, /home/	Yes
missing_file	Referenced file doesn't exist	No
schema_mismatch	Database schema doesn't match ADR-103	Yes
dependency_error	Missing Python package	No
permission_error	File/directory access denied	No
symlink_broken	Symlink target missing	Yes
hook_config_error	Hook configuration invalid	Yes
version_mismatch	Incompatible version	Yes

Prerequisites

• gcloud CLI installed and authenticated
• gsutil available
• Write access to gs://coditect-dist/ bucket
• Git configured for commits

Related Commands

Command	Purpose
/backup	Backup context database
/cx	Extract context
/checkpoint	Create session checkpoint

Related Components

Component	Type	Description
install-script-maintainer	Agent	Orchestrates maintenance
install-script-lifecycle	Skill	Patterns and practices
install-script-deployment	Workflow	Step-by-step process
install-script-validator.py	Hook	Validation script

GCS Details

Property	Value
Bucket	gs://coditect-dist/
File	coditect-install.py
Backup	coditect-install.py.bak
Public URL	https://storage.googleapis.com/coditect-dist/coditect-install.py
Cache-Control	no-store, no-cache, must-revalidate, max-age=0

CDN Cache Handling

GCS uses CDN edge caching. After deployment, edge caches may still serve old versions until TTL expires.

Deployment Commands (with cache control):

# Upload with cache-control headers
gcloud storage cp ~/.coditect/scripts/CODITECT-CORE-INITIAL-SETUP.py \
  gs://coditect-dist/coditect-install.py \
  --cache-control="no-store, no-cache, must-revalidate, max-age=0"

# Verify object metadata
gcloud storage objects describe gs://coditect-dist/coditect-install.py \
  --format="value(cacheControl)"

Validation Commands:

# Check via gcloud (bypasses CDN)
gcloud storage cat gs://coditect-dist/coditect-install.py | grep "SCRIPT_VERSION"

# Check via curl with cache-busting
curl -s "https://storage.googleapis.com/coditect-dist/coditect-install.py?v=$(date +%s)" \
  | grep "SCRIPT_VERSION"

# Check CDN response headers
curl -sI "https://storage.googleapis.com/coditect-dist/coditect-install.py" \
  | grep -i cache-control

If CDN still serves old version:

1. Add query string: ?v=2.8.0 (bypasses cache)
2. Wait up to 1 hour for edge cache expiry
3. Use gcloud storage cat for immediate access

ADR Compliance

This command enforces compliance with:

• ADR-057: CODITECT Core Initial Setup architecture
• ADR-103: Four-database separation architecture
• ADR-074: Governance hooks

---

Script: Uses install-script-maintainer agent ADR: ADR-057, ADR-103 Version: 1.1.0