[jcombs-pointblue]

Phase R1 of project-per-environment.md (DirXMLDevWeb #169, decided 2026-10-26): the core half, usable from the CLI. User reference: docs/promotion.md.

What's in it

• tree.compare <target> --with <source>
  • Translation: the source is put into the target's terms. Drivers and servers go through promotions/<source>.properties (the overrides file's form). The driver set's name and DN, and each driver's DN, are always the target's.
  • Files are compared with their values set aside (every key EnvironmentCompare.values lists is emptied on both sides), so a value that differs never makes its file look changed. Values are compared on their own, key by key.
  • Look-alike drivers: drivers only one side has that resemble each other under other names are proposed for the map (EnvironmentCompare.matches).
• The promotion record, promotions/<source>.json: per file and per value, a fingerprint of each side at the last promotion or pairing.
  • Buckets: pending, target's own, both changed, known, unchanged since the record, not paired yet.
  • Unrecorded files: once a pair has a record, a file with no entry was absent from both sides, so a new file shows as pending or as the target's own.
• promote.plan / promote.apply
  • Choosing: --object takes a file or a directory; --pending; --contents takes a file merged line by line, which R2 will use.
  • Values: the target's stay unless named with --value. A file's package baseline goes with it.
  • Refusals, with nothing written:
    • a chosen file the target's model wouldn't hold, such as a new policy whose driver.xml wasn't promoted with it, or a removal whose manifest still lists it;
    • a new validation error (unless --force).
  • Writing: only files whose bytes change. The result gives the trailer Promoted-from: <source>@<commit>.
• promote.pair takes the first record. promote.accept and promote.forget handle promotions/<source>.known.json.
• Small changes elsewhere:
  • DriverSet.name is no longer final, so a source can take the target's identity.
  • EnvironmentCompare.values and matches and ModelDiff.textDiff are now public. textDiff's Javadoc also corrected: it returns every line, not only the changed ones.

Not in R1

• Branch, commit and pull request: the page's job (R2). promote.apply writes the tree in place.
• Pair with… proposals, promoting cases/, MCP tools: R3.

Testing

• PromoteTest (8 tests): QA and production as separate trees, with a renamed driver, a mapped server, another driver-set DN and a value that differs. Covers:
  • each bucket and partial promotion;
  • values kept unless named;
  • a new policy with its manifest, and a removal;
  • merged contents;
  • the validation refusal;
  • the baseline;
  • the CLI's exit codes.
• Full build: mvn -o clean install passes, 963 tests (11 skipped). -Pidm.portable test and bin/ci-portable.sh pass (71).
• By hand with bin/idm: the synthetic fixture imported as acme-prod/tree and acme-qa/tree, then pair, change both, compare, plan, apply, accept. The policy came over, production kept its own GCV value, and the accepted value then counted as known.

🤖 Generated with Claude Code