Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0093

ADR-0093: Promotion, test and gate work re-injects the process, test and gate memories, and compaction resets the injector

← ADR-0092 · ADR-0094 →

The record

Status: Accepted · Date: 2026-10-12 · Ruled: 2026-10-12 (Mohamed's directive; the mechanism below is designed under it)

Context

• The directive. Mohamed, 2026-10-12, verbatim: "now configure those memories to be triggered every time we work on the promotion so you never forget especially the tests and gates".

• The memories. "Those memories" are the project memory files built the same day by three verification swarms:

  • dev-test-promote-deploy-process, code-rules, test-rules, gates-logic;
  • system-components-and-wiring, janus-fork-and-prolog-bridge, prolog-rulebases-and-atoms, recurring-pitfalls-checklist;
  • plus the existing tests-run-once-rul-032 and prod-promotion-blocked-by-fleet-drift.

  All live in ~/.claude/projects/-home-mohamed-workspace-orchestrata-ultimate/memory/.

• How they load today. By default only the index, MEMORY.md, is in context; a memory file is read only when a session remembers to read it. The 2026-10-12 session broke rules those files state: it demanded forced test runs against RUL-032, quoted clock times that came from no command, and described a check's scope without reading it.

• The existing injector lies after compaction.

  • claude/hooks/workflow_context_inject.py, a UserPromptSubmit hook, classifies a prompt by keyword into four domains: development, testing, deployment and environments.
  • It injects each domain's summary once per session. Later matches print [workflow] <domain> methodology already in context this session.
  • Its seen-state is $XDG_RUNTIME_DIR/claude-workflow-inject/<session_id>.json (_state_path), keyed by session id alone.
  • Compaction keeps the session id but drops the injected text. After a compaction the hook therefore asserts something false and never re-injects. On 2026-10-12, post-compaction prompts received [workflow] development, deployment methodology already in context this session.

• How project memory is keyed. Claude Code keys project memory by the git common dir. Every checkout of this repo (git rev-parse --path-format=absolute --git-common-dir → /home/mohamed/workspace/orchestrata-ultimate/.git, measured from orchestrata-ultimate-architecture and from wt-INTEGRATION) shares ~/.claude/projects/-home-mohamed-workspace-orchestrata-ultimate/memory/.

Decision

Mohamed's directive above is the decision. Under it:

1. Prompt trigger.
   • workflow_context_inject.py gains a promotion domain. Its triggers are word-boundary regexes: promote, promotion, deploy, deployment, ship, release, prod, production, rollback, "test env", promote_env, run_tests, gate, gates, preflight.
   • Its block carries a fixed tests-and-gates checklist of at most 20 lines. The checklist is versioned in the repo and ships with the plugin (ADR-0092).
   • For each named memory file, the block gives its one-line description, its **How to apply:** line and its absolute path, and instructs the session to read the files before running a promotion, test or gate command.
   • A named memory file that is missing is named as missing in the block. It is never skipped silently.
2. Command trigger.
   • A PreToolUse(Bash) hook injects the same checklist and paths on EVERY Bash command that runs promote_env.py, ship.sh, install-orchestrata.sh, install-claude-config.sh, install-plugin.sh, provision_app_container.sh, run_tests.py, .run_exclusive.sh, gate.py, gates.py, tofu, or git push.
   • It never dedups: the command is the moment a forgotten rule costs.
3. Truthful dedup. The injector's seen-state is cleared whenever the context is rebuilt, by SessionStart with source compact, resume or clear. "Already in context" is then printed only when the text is in the current context. This applies to all five domains.
4. Memory dir resolution.
   • The path is ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/<parent of the git common dir, with every "/" replaced by "-">/memory, computed from the hook's cwd.
   • Outside a git repository the triggers emit only the checklist.
5. Delivery is measured, not assumed.
   • A test drives a real headless claude session and asserts that the injected text reaches the session for both the UserPromptSubmit event and the PreToolUse event.
   • This is the 2026-08-13 lesson recorded in _emit: a hook can run, write its state, exit 0 and deliver nothing.

Alternatives rejected

• Index lines in MEMORY.md only ("read X before promoting"). This still depends on the session remembering to read, which is the failure being fixed. Such lines are still added as a second layer.
• Paste every memory file in full on each match. The files are long (detailed by request). Re-pasting them on every prompt crowds out the context, and the injector's own design notes say a methodology re-pasted on every turn stops being read. The checklist, the paths and the per-command reminder carry the binding rules; the files carry the detail.
• A separate new UserPromptSubmit hook. It would duplicate the injector's keyword classification, per-session state and _emit delivery form.

Consequences

• Every promotion, test and gate command runs with the checklist in context at that moment.
• The four existing domains stop asserting "already in context" after a compaction (decision 3).
• The checklist text is versioned in the repo and ships with the plugin. The long-form memories stay machine-local and are referenced by absolute path.
• Kimi does not run Claude hooks, so Kimi briefs keep restating the guards (memory kimi-k3-is-the-executor).

Provenance

• Directive: Mohamed, 2026-10-12 (quoted verbatim in Context).
• Evidence (origin/master 22363abb2):
  • scripts/serialize_codebase_ast.py source workflow_context_inject.main, …_emit and …_state_path with --source claude/hooks/workflow_context_inject.py;
  • git rev-parse --path-format=absolute --git-common-dir, run from both checkouts named in Context.
• The orchestrator designed the mechanism under the directive. Changing the mechanism requires a new ADR.

Related ADRs

• Also mentioned: ADR-0092

Rulings cited

• RUL-032: RUL-032 — A test runs once per code state; escalation never re-runs a proven test

Specs cited

None (or no spec page exists for the ones named).