feat(molecules): per-molecule additional_instructions in config (#50)

[techygarg]

What does this PR do?

Adds an optional additional_instructions.{molecule} key to .lattice/config.yaml, so a project can give each workflow molecule a few lines of its own habits. Implements discussion #50 and closes the per-platform back-link gap promised in #46.

Type of change

• New atom
• New molecule
• New refiner
• Improvement to existing skill
• Documentation fix
• Other: build step — tools/install.sh now expands shared includes

Breaking change?

• Yes
• No — the key is optional. With no key, every molecule behaves exactly as before.

Why

Every setup has small workflow habits that sit outside a molecule's core: "suffix the blueprint with the platform", "read the backend repo in ../api before designing", "in the handoff, name the reviews this design needs". Today people either repeat them every session or are tempted to edit the skill. They're too small and local for a refiner, and putting them in AGENTS.md/CLAUDE.md loads them into every session, molecule or not.

Feedback on #50 shaped the design:

• Real examples are session habits, not artifact rules. That includes what to read first, how to name output, which reviews to call for, and branch naming. ShuratCode's test: if it shapes the artifact, it's a standard; if it shapes the session, it goes here.
• Molecule level is the sweet spot. Both commenters agreed it should not reach atoms.
• The main risk is misuse as a second AGENTS.md. kkumawat333 asked for clear guidance on when to use which, so the docs carry it.
• Visibility. A teammate must be able to tell why two sessions behaved differently.

How it works

additional_instructions:
  design_blueprint:
    - Suffix the context doc name with the platform: {feature}-ios or {feature}-android.
    - Before designing, read the other platform's context doc if it exists.

Before Step 1, the molecule reads its own key (one line or a list), then:

1. Shows the lines word for word under "Additional instructions (from config):".
2. Applies them with highest priority for the whole session, including on resume. They win over the molecule's own steps, gates and STOP rules, its atoms, standards documents and learnings.

Supported keys: requirement_forge, design_blueprint, code_forge, refactor_safely, bug_fix, review, architecture_compass. The setup molecules (lattice-init, refiners-update) don't read it.

Design decisions

• Highest priority, gates included, no runtime policing. It's a tool in the user's hands. I first proposed exempting approval gates. Dropped it: many users are solo, the cost of skipping a gate falls on whoever wrote the line, and a framework that second-guesses a deliberate config line isn't a tool. The only safeguard is showing the lines at session start. Nothing nags at runtime: no move suggestions, no length warnings, no override logging.
• Placement guidance is advice, not enforcement. docs/configuration.md → "Choosing where an instruction goes" covers it:
  • Two questions: does it apply outside this molecule (→ AGENTS.md/CLAUDE.md)? Does it shape the artifact (→ usually a refiner's standards document) or the session (→ here)?
  • A comparison table of the three places: scope, when it loads, what it holds, size, example.
  • The common mistakes.
• No all_molecules key. A line every workflow needs is cross-cutting and belongs in AGENTS.md/CLAUDE.md. That's the same rule the guidance teaches.
• Molecules only. Atoms are shared by many molecules, so an atom-level key would quietly change all of them.

One source, no copy-paste: source/shared/ + include marker

The section is the same in all 7 molecules. Instead of 7 copies, it lives once in source/shared/additional-instructions.md. Each molecule's source has one line before ## Workflow:

<!-- include: additional-instructions -->

After copying each skill, tools/install.sh (which build-skills.sh calls) replaces the marker with the snippet. It fills in __SKILL_KEY__ from the folder name (design-blueprint → design_blueprint) and fails loudly if a snippet is missing. The marker itself is the opt-in, so no map of molecules is needed, and atoms and refiners are never touched. Every generated skill in skills/ stays complete on its own.

Considered and rejected:

• A new framework:additional-instructions atom. Every run would read one more file. The priority rule would sit in a separate file from the gates it overrides, which weakens it. About 2 lines would still repeat per molecule. The atom would teach no engineering principle, and it would show up as a do-nothing 28th skill in every host. The duplication only costs us when maintaining files, so it's fixed where the copies are generated.
• Folding it into knowledge-priming. That atom's scope is different, requirement-forge only loads it when a codebase exists, and it can be triggered on its own.
• A shell script that reads the YAML. The priority rule still has to be written in markdown, YAML parsing in bash is fragile, and it would need the host path fallback chain.

design-blueprint back-link fix (#46)

Step 1.5 used to write the requirement back-link only when the requirement file was named features/{context-doc-name}.md. A platform-suffixed context doc ({feature}-ios), the main example in the new docs, silently got no link. It now uses the requirement_doc path and the context doc's real filename, with one Design: line per context doc, and creates ## Links if it's missing.

Related wording change: Step 2 recorded [Entry] as "the first Decisions Log entry". That's now "in the Decisions Log", since the resume logic finds it by tag, not position.

Skill checklist

Modified molecules

• ## Required Skills unchanged
• Workflow steps unchanged, apart from the design-blueprint back-link and [Entry] wording above
• No atom content copied inline
• New section sits right before ## Workflow, matching the existing precedent of review's ## Config Resolution

Testing

Tool used: Claude Code
Model: Claude Opus 5.5
Invoked against: build pipeline and validators. No molecule was run live against a project with the key set.
What worked correctly:

• skills/ generated through the include path matches the previous inline output byte for byte. The one exception is review/SKILL.md, which now ends with a newline that its source lacked.
• No unexpanded markers in skills/; source/shared/ isn't installed as a skill; still 27 skills.
• With the snippet removed, install.sh exits 1 naming the missing file and leaves no temp files.
• bash -n tools/install.sh passes. shellcheck wasn't available locally, so the CI shell-safety job is the first real shellcheck run.
• skill-validate on design-blueprint: PASS (run before the include refactor).

Edge cases to try in review:

• No .lattice/config.yaml / no key: should be silent, same behavior as before.
• One string instead of a list.
• A line that skips a gate, e.g. "run Levels 2–4 without stopping": it should be shown and applied.
• {feature}-ios naming: the back-link should point at the suffixed context doc.

Documentation

• docs/configuration.md — key reference, rules, "Choosing where an instruction goes"
• docs/how-it-works.md, docs/practical-guide.md — pointer + Q&A
• docs/plugins.md, CONTRIBUTING.md, PROJECT.md — source/shared/ + include build step
• Dev skills (skill-validate, skill-forge, skill-review, skill-tighten, skill-enhance) read and edit the shared snippet instead of inlining it; skill-validate reports broken includes

Anything else?

Deferred from the #50 thread, each worth its own change:

• Review step after Level 4 in design-blueprint (ShuratCode): the molecule would wait for a named reviewer, then record the result and any spec update. The most valuable item left.
• Batch mode chosen in the session: an owner asking to run levels without stopping already works informally.
• lattice-init warning when a config line repeats an agent-file or refiner line.