Orchestrata Ultimate › Plans › installer-config-manifest-plan

Installer hardening — a declared manifest replaces every literal in deploy/install-claude-config.sh

Source: plans/installer-config-manifest-plan.md at 8a2cb42ad · last changed 2026-10-09 · first committed 2026-10-09 · 246 lines.

Prose pending.

Plan text

Installer hardening — a declared manifest replaces every literal in deploy/install-claude-config.sh

Status: Proposed 2026-10-09 (user ruling: "fix the installer so the 5 issues never occur again, use configuration not hardcoding"). Amends SPEC-108 FR-001 / ERR-004 and SPEC-020. Scope: deploy/install-claude-config.sh, claude/scripts/{patch_settings,register_hooks}.py, the new claude/deploy.manifest.json + generators, their tests, one ADR.

0. The five measured defects (review of 2026-10-09, all reproduced live)

Cross-cutting cause: the installer hardcodes what it manages. SUBTREES=(hooks tools agents skills commands workflow), five cp lines, the dependency fallback jinja2 neo4j pydantic redis, the drift-check regex at line ~488 (which once lost statusline-command.sh), the plugin id, the smoke-test hook, and the backup retention of 3 are all literals in bash. Every past omission in this file (statusline-command.sh, test_*.py exclusion, the VERSION-before-verify marker) was a literal that drifted from intent. The fix is one declared manifest the installer reads, generators that render settings from it, and a verifier that checks every section of it, not only hooks.

1. Requirements

• Spec: specs/108-environment-installer/spec.md FR-001, ERR-004 (amend); specs/020-claude-code-harness/checklists/requirements.md (new REQ-020 rows below).
• Platform conventions (~/.claude/hooks/platform_conventions_prompt.py, RUL-021/027): a user-level deployment obeys the five deploy rules; the verifier refuses success unless the running thing is the deployed thing. This plan extends "running thing" from files to the effective configuration Claude loads.
• New REQ ids (to add to SPEC-020 checklist; numbering continues after the last row):
  • REQ-020-3xx-A manifest: every path, file list, id and policy the installer uses is read from claude/deploy.manifest.json; the bash script contains no managed-content literal.
  • REQ-020-3xx-B permissions are generated from structured entries, never typed as rule strings.
  • REQ-020-3xx-C the verifier lints every permission layer against a declared forbidden-grant list.
  • REQ-020-3xx-D autoMode.environment is rendered from env/*.env + a declared facts file, replaced wholesale, and validated against the prod profile.
  • REQ-020-3xx-E every declared section (hooks, permissions, defaultMode, env, statusLine) is diffed declared-vs-live; a declared-but-absent entry fails the deploy.
  • REQ-020-3xx-F the instruction chain of every registered project root is audited against the manifest's allowlist; an unlisted ancestor CLAUDE.md fails verification.
  • REQ-020-3xx-G every ~/.claude/<path> literal a deployed hook cites resolves to a deployed file.

2. Design

One manifest, three generators, one verifier. claude/deploy.manifest.json (schema below) is the only place the installer learns what it manages. Three generators under claude/scripts/ render the parts of settings.json the deployment owns: gen_permissions.py (structured entries → rule strings), gen_automode.py (env/*.env + declared facts → autoMode), and the existing gen_plugin.py (unchanged input, now reads subtrees from the manifest). patch_settings.py becomes the single writer and applies every owned section idempotently (replace-by-owner-key, never append). register_hooks.py becomes verify_settings.py: a generic declared-vs-live diff over every section, plus the three new audits (permission lint, instruction chain, hook citations). The bash installer shrinks to: read manifest, stage, copy what the manifest lists, run the writer, run the verifier.

Why generate rule strings instead of lint them: a linter can only warn that /tmp/** is "probably" wrong, because / is a legal project-relative prefix. A structured entry {"tool":"Write","scope":"filesystem","glob":"/tmp/**"} has one correct rendering (Write(//tmp/**)), so the class of defect cannot be typed. The lint still runs on layers the installer does not generate (settings.local.json, project .claude/settings.json) because those are hand-edited by design.

Twin check: claude/scripts/ IS in the AST snapshot (ORCHESTRATA_AST_ROOTS includes claude; symbols --pattern ensure_owned_hooks resolves to claude/scripts/patch_settings.py:109). The 2026-10-09 review's "0 symbols" came from searching a MODULE name through symbols, which matches symbol names; source claude.scripts.patch_settings.<fn> is the correct query. No source-root change is needed. The graph side is a separate gap (see plans/ live-sync roots work, 2026-10-09): scripts/ast_live_sync.py hardcodes DEFAULT_SOURCE_DIR = "src/orchestrata_ultimate", so the code-intelligence graph never received scripts/, claude/ or tests/ modules.

2.1 Manifest schema — claude/deploy.manifest.json

{
  "schema": 1,
  "prefix_default": "~/.claude",
  "interpreter": {"env": "FT_PYTHON", "default": "~/.local/bin/python3.14t"},
  "subtrees": ["hooks", "tools", "agents", "skills", "commands", "workflow"],
  "files": [".envrc", "statusline-command.sh", "settings.hooks.json",
            "scripts/patch_settings.py", "scripts/verify_settings.py",
            "scripts/write_provider_restriction.py", "scripts/gen_permissions.py",
            "scripts/gen_automode.py", "CLAUDE.md"],
  "deps_fallback": ["jinja2", "neo4j", "pydantic", "redis"],
  "backup_retention": 3,
  "plugin": {"id": "orchestrata@orchestrata", "marketplace": "orchestrata", "source_tree": "plugins/orchestrata"},
  "smoke_hook": "hooks/platform_conventions_prompt.py",
  "settings": {
    "declaration": "settings.hooks.json",
    "owned_keys": ["hooks", "permissions.defaultMode", "permissions.allow", "env", "statusLine", "autoMode"]
  },
  "permissions": {
    "entries": [
      {"tool": "Bash", "scope": "command", "pattern": "incus list:*"},
      {"tool": "Read", "scope": "filesystem", "glob": "/tmp/**", "effect": "deny",
       "except": ["/tmp/claude-*/**"]}
    ],
    "forbidden_grants": {
      "description": "allow rules that hand out a generic interpreter defeat every Bash guard",
      "patterns": ["Bash(python* -c*", "Bash(python*", "Bash(sh -c*", "Bash(bash -c*",
                   "Bash(perl -e*", "Bash(node -e*", "Bash(eval*", "Bash(uv run python*"],
      "layers": ["settings.json", "settings.local.json", "<project>/.claude/settings.json",
                 "<project>/.claude/settings.local.json"],
      "on_violation": "fail"
    }
  },
  "automode": {
    "facts": "claude/automode.facts.json",
    "env_profiles_glob": "env/*.env",
    "sensitive_profiles": ["prod"],
    "routine_profiles": ["test", "dev"]
  },
  "instruction_chain": {
    "project_roots_from": "projects_dir",
    "allowed_ancestors": ["<prefix>/CLAUDE.md", "<project>/CLAUDE.md"],
    "on_unlisted": "fail"
  }
}

<prefix>/<project> are the two substitution tokens; no absolute path appears in the manifest. A JSON Schema (claude/deploy.manifest.schema.json) validates it at install time and in tests.

2.2 Decision entries (forks surfaced before coding)

• D1 claude/settings.json in the repo (legacy: fastMode, enforcement_hook, hardcoded python3, allow: ["Bash","Incus"]) is neither deployed nor checked. Delete it. The declaration is settings.hooks.json, renamed settings.declared.json because it now holds every owned section. (Alternative rejected: make it the declaration. Its content is stale on every line and a second declaration file is the defect class this plan removes.)
• D2 Deploy a user-level CLAUDE.md from claude/CLAUDE.md as a managed file, so the three hooks that cite it (platform_conventions_prompt.py, install_secret_guard.py, session_resume_context.py) are true. (Alternative rejected: strip the citations. The platform-conventions text is meant to live there per its own hook.)
• D3 Ancestor CLAUDE.md outside the prefix and the project root fail verification; the installer never deletes them (they belong to other repos). The remedy is printed. (Alternative rejected: auto-rename to CLAUDE.md.disabled. Mutating another repo from this installer is a one-way door nobody ruled on.)
• D4 Forbidden grants in settings.local.json fail verification rather than being removed. Same reasoning as D3: the file is the user's by design; the verifier names the rule and the bypass it enables.
• D5 autoMode is owned: the deploy replaces the block. claude auto-mode setup output is consumed once into claude/automode.facts.json by gen_automode.py --import, then never read from the live file again. Re-running setup after a deploy is reported as drift.
• D6 session_resume_context.py resolves the memory index from the session's project (<projects_dir>/<slug>/memory/MEMORY.md, worktree-mapped the way Claude Code maps it), not a hardcoded -home-mohamed. Small, but it is the same defect class.

One ADR: ADR-0062 "Deployed configuration is generated from a declared manifest; the installer carries no managed-content literal" — Status Proposed, one-way-door because every later addition to ~/.claude has to go through the manifest or fail the drift check.

3. Implementation units

4. Wiring plan

• Composition root: deploy/install-claude-config.sh is the only caller. Order after the change: manifest.py validate → stage from pinned ref → copy subtrees + files → shebang retarget → gen_permissions.py --write-decl + gen_automode.py --write-decl (both write into the staged declaration, never into the live file) → patch_settings.py (writer) → plugin sync → verify_settings.py --check (every audit) → drift check from manifest list → promote VERSION.
• Consumer path: deploy/ship.sh:567 → installer (unchanged entry). install.sh (SPEC-108) → installer --prefix (unchanged).
• Lifecycle: generators and verifier run under $PREFIX/.venv/bin/python (deployed venv), never the system interpreter; --verify mode runs the verifier only and mutates nothing.
• Config: the manifest is versioned with the repo and deployed to $PREFIX/deploy.manifest.json so --verify on a machine without a checkout audits against the deployed declaration. env/*.env is read from the pinned ref's archive, not the working tree.

5. Wiring proof

• Construction: a fresh --prefix "$tmp" deploy from HEAD produces a settings.json whose permissions.allow, defaultMode, autoMode and hooks equal the generators' output and whose VERSION records HEAD.
• Reachability, one per defect, each a test that fails if its mechanism is removed:
  1. a manifest entry {"tool":"Write","scope":"filesystem","glob":"/tmp/**"} renders Write(//tmp/**); a hand-typed Write(/tmp/**) in the declaration fails lint.
  2. a fixture tree <tmp>/CLAUDE.md above <tmp>/ws/repo with projects_dir naming repo fails verify_settings.py --check with the file named; listing it in allowed_ancestors passes.
  3. a fixture settings.local.json with Bash(python3 -c ' *) fails the lint and the message names the bypass; removing the rule passes.
  4. with env/prod.env declaring 10.53.1.0/24, a facts file that lists 10.53.1.10 as a routine service fails gen_automode.py --check; the rendered block has unique keys.
  5. declaring defaultMode: auto and an allow in the declaration, then deploying, yields both in the live file; deleting either from the live file fails --verify.

6. Traceability gate

• Each generator/verifier function carries @traces for its REQ-020-3xx row; shell units are traced through the SPEC-020 checklist rows the way decision_adr_trigger.sh is.
• python scripts/serialize_codebase_ast.py check-traces green; RTM regenerated in the commit.
• ADR-0062 minted via the decision skill in all three homes (docs/wiki/graph) before the installer edit lands; the decision skill's design-waiver rule is not invoked.

7. Quality gates

• Coverage ≥90% on manifest.py, gen_permissions.py, gen_automode.py, patch_settings.py, verify_settings.py (subprocess-visible).
• ruff, pyright ratchet, test-review.py clean; no mocks (fixtures are real temp trees and real JSON files); no monkeypatch (interpreter and prefix enter via --prefix/manifest env keys).
• deploy/install-claude-config.sh --verify green on this workstation after the deploy, with defects 2 and 3 expected to FAIL until the two $HOME ancestor files and the local allow rule are resolved by the user (D3, D4): the verifier reports them; the plan does not remove them.
• Ship through deploy/ship.sh in the same motion as the merge (deployment is not a separate decision).

8. Order of work

1. ADR-0062 (Proposed) + SPEC-108/020 amendments — half a day.
2. Manifest + schema + loader + the literal-free installer (no generators yet; behaviour identical) — the existing verification suite proves nothing regressed.
3. verify_settings.py generic section diff + declared defaultMode/allows land (defect 5).
4. gen_permissions.py + project .claude/settings.json migrated to entries (defect 1).
5. Permission lint across layers (defect 3).
6. gen_automode.py with --import of the current block, then prod-subnet validation (defect 4).
7. claude/CLAUDE.md managed + instruction-chain audit + hook-citation audit (defect 2).
8. _dispatch.sh STANDDOWN logging, session_resume_context.py memory path, AST source root.
9. Deploy via ship.sh; run --verify; record the two user-owned remediations it reports.

9. Definition of done

• [ ] grep -cE 'jinja2|orchestrata@orchestrata|hooks tools agents|platform_conventions_prompt|statusline-command' deploy/install-claude-config.sh → 0
• [ ] ~/.claude/settings.json permissions.defaultMode, permissions.allow, autoMode equal generator output; re-running the installer changes 0 bytes
• [ ] Write(//tmp/...) probe is refused on this workstation (or the entry is deliberately absent); no /-prefixed filesystem-intent rule exists in any layer
• [ ] --verify names /home/mohamed/CLAUDE.md, /home/mohamed/workspace/CLAUDE.md and Bash(python3 -c ' *) as findings until resolved
• [ ] autoMode.environment has unique keys, no fragment lines, and lists 10.53.1.0/24 only under sensitive targets
• [ ] scripts/serialize_codebase_ast.py symbols --pattern verify_settings returns the module
• [ ] ADR-0062 Accepted on Mohamed's ruling; RTM rows for REQ-020-3xx-A..G implemented + tested

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks