fix: resolve installer failures and add comprehensive validation (#189 )

* fix: ContextScout falls back to global core/ when local core/ missing

Users who install OAC globally have core standards at
~/.config/opencode/context/core/ but no local core/ directory.
ContextScout now does a one-time check on startup: if local
core/navigation.md doesn't exist, it checks the global path
from paths.json. This resolves the ENOENT errors when agents
try to read core/standards/ files that only exist globally.

- paths.json: enabled global path (~/.config/opencode/context)
- contextscout.md: added global_fallback rule with 2-glob cap
- Fallback is ONLY for core/ files, never project-intelligence

* docs: add context resolution explanation to README

Explains how ContextScout resolves context files: local-first,
global fallback only for core/ files, project-intelligence always
local. Includes flow diagram, key rules, and common setup table.

* fix: resolve installer failures and add comprehensive validation

## Summary
Fixes critical installer failures where ContextScout and other components couldn't find their configuration files after installation. Adds comprehensive validation system to prevent future issues.

## Problems Fixed

### 1. Missing Critical Files (13 dead registry references)
Files were referenced in registry but didn't exist on disk:
- workflows-delegation (split into 3 files)
- design-iteration (split into 8 files)
- animation-patterns (split into 6 files)
- adding-agent (split into 2 files)
- adding-skill (split into 3 files)
- navigation-design (split into 2 files)
- external-libraries (split into 3 files)
- claude-code-docs/* (directory removed)

### 2. Missing Infrastructure Files
ContextScout failed after installation because 2 critical files weren't in registry:
- paths.json - Context root configuration
- navigation.md - Root navigation for discovery

### 3. Profile Inconsistencies
Profiles referenced components that don't exist:
- context:adding-skill → context:adding-skill-basics
- context:animation-patterns → animation-basics/components/advanced
- context:design-assets (removed - doesn't exist)
- context:to-be-consumed/* (removed - directory doesn't exist)
- skill:context-manager → subagent:context-manager

## Changes Made

### Registry (registry.json)
- Removed 13 dead references
- Added 27 new split-file entries
- Added 2 critical infrastructure entries
- Fixed all 5 profile configurations
- Updated ContextScout dependencies
- Updated agent-metadata.json dependencies

### New Validation Scripts
- scripts/registry/check-dependencies.ts - Comprehensive dependency checker
- scripts/tests/test-installer-files.sh - Installer simulation test
- scripts/registry/fix-registry.py - Automated registry fixer
- scripts/hooks/pre-commit - Git pre-commit hook

### Documentation
- docs/maintenance/REGISTRY_FIXES_SUMMARY.md
- docs/maintenance/CONTEXTSCOUT_FIX.md
- docs/maintenance/REGISTRY_VALIDATION.md

## Validation Results

Before:
- 13 missing files in registry
- 78 orphaned files on disk
- 3 missing dependencies
- Installer would fail

After:
- 244 total paths, 0 missing
- 262 dependency checks, 0 failures
- 0 orphaned dependencies
- All profiles consistent
- Installer works correctly

## Testing

```bash
# Registry validation
bun run scripts/registry/validate-registry.ts
# ✓ All 244 paths valid

# Dependency checking
bun run scripts/registry/check-dependencies.ts
# ✓ All 262 checks passed

# Installer test
./scripts/tests/test-installer-files.sh --local --profile=essential
# ✓ All files accessible
```

## Usage

### Run validation before commits:
```bash
bun run scripts/registry/check-dependencies.ts
```

### Install pre-commit hook:
```bash
cp scripts/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

### Test installer:
```bash
./scripts/tests/test-installer-files.sh --local --profile=essential
```

## Impact

This fix ensures:
- ✓ Installer downloads all required files
- ✓ ContextScout works immediately after install
- ✓ No broken dependencies
- ✓ No missing profile components
- ✓ Future issues caught by validation

## Breaking Changes

None - all changes are additive or fix broken references.

## Related

- Fixes: ContextScout failing after installation
- Prevents: Missing file errors during install
- Adds: Comprehensive validation system

* fix: resolve shellcheck warnings in test scripts

- Remove unused REPO_URL variable from test-installer-files.sh
- Add shellcheck disable comments for cleanup functions used via trap
- Fixes CI failures in ShellCheck Analysis workflow

* fix: resolve shellcheck errors across all scripts

Fixed arithmetic expansion issues and code quality warnings:
- Changed ((var++)) to POSIX-compliant 1 syntax
- Fixed unquoted variables and grep pipe issues (SC2002, SC2143)
- Added shellcheck disable comments for intentional patterns
- Fixed variable initialization and return statement placement

Scripts fixed:
- scripts/tests/*.sh (5 files)
- scripts/registry/*.sh (4 files)
- scripts/validation/*.sh (2 files)
- scripts/*.sh (2 files)
- evals/framework/scripts/*.sh (2 files)

All scripts now pass shellcheck --severity=warning

* chore: trigger CI shellcheck validation

2026-02-06 17:07:42 +00:00

4.3 KiB

Raw Blame History

ContextScout Fix - Critical Files Missing from Installer

Problem

After running the installer, ContextScout fails with errors like:

"Cannot locate context root"
"Cannot discover context"
"paths.json not found"

Root Cause

Two CRITICAL files required by ContextScout were NOT included in the registry:

paths.json (.opencode/context/core/config/paths.json)
- Defines the context root location
- Loaded via @ reference by agents on startup
- Without it: ContextScout doesn't know where to look for context
navigation.md (.opencode/context/navigation.md)
- Root navigation file for context discovery
- ContextScout starts discovery HERE
- Without it: ContextScout has no entry point for discovery

Solution

1. Added Critical Files to Registry

Created two new registry entries in registry.json:

{
  "id": "context-paths-config",
  "name": "Context Paths Configuration",
  "type": "context",
  "path": ".opencode/context/core/config/paths.json",
  "description": "CRITICAL: Context root path configuration - loaded via @ reference by agents",
  "tags": ["config", "paths", "critical", "context-system"],
  "dependencies": [],
  "category": "essential"
},
{
  "id": "root-navigation",
  "name": "Root Navigation",
  "type": "context",
  "path": ".opencode/context/navigation.md",
  "description": "CRITICAL: Root navigation file for context discovery - ContextScout starts here",
  "tags": ["navigation", "root", "critical", "context-system"],
  "dependencies": [],
  "category": "essential"
}

2. Added to All Profiles

Updated all 5 profiles to include these critical files:

essential
developer
business
full
advanced

3. Added ContextScout Dependencies

Updated ContextScout's dependencies to explicitly require these files:

"dependencies": [
  "command:check-context-deps",
  "context:registry-dependencies",
  "context:context-system",
  "context:mvi",
  "context:structure",
  "context:workflows",
  "subagent:externalscout",
  "context:root-navigation",
  "context:context-paths-config"
]

Files Modified

Registry & Configuration

registry.json - Added 2 critical context entries, updated ContextScout dependencies

Profiles

.opencode/profiles/essential/profile.json - Added critical files
.opencode/profiles/developer/profile.json - Added critical files
.opencode/profiles/business/profile.json - Added critical files
.opencode/profiles/full/profile.json - Added critical files
.opencode/profiles/advanced/profile.json - Added critical files

Validation Results

Registry Validator:
✓ Total paths checked:    244
✓ Valid paths:            244
✓ Missing paths:          0
✓ Missing dependencies:   0

Installer File Test:
✓ All files accessible
✓ 0 files would fail

Testing After Fix

Run the installer:

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s essential

ContextScout should now work without errors:

opencode
# Then ask ContextScout to discover context

Verify files were installed:

ls -la .opencode/context/navigation.md
ls -la .opencode/context/core/config/paths.json

Why This Happened

The installer uses registry.json to determine which files to download. If a file isn't listed in the registry, it won't be installed.

These two files were essential infrastructure files that were:

Referenced by agent code
Required for ContextScout operation
Present in the repository
BUT not included in registry.json

Prevention

To prevent this in the future:

Always run registry validation before committing:

bun run scripts/registry/validate-registry.ts

Test the installer after registry changes:

./scripts/tests/test-installer-files.sh --local --profile=essential

When adding new critical infrastructure files:
- Add them to registry.json
- Include them in all relevant profiles
- Add as dependencies to components that require them

See .opencode/agent/subagents/core/contextscout.md for ContextScout requirements
See .opencode/context/core/config/paths.json for context path configuration
See .opencode/context/navigation.md for root navigation structure

4.3 KiB Raw Blame History