ADR-006: shared action types as the action identity contract. Add guide how to write ADRs

Author: Aksem

docs/adr/0006-shared-action-types-as-the-action-identity-contract.md

@@ -0,0 +1,73 @@
+# ADR-0006: Shared action types as the action identity contract
+
+- **Status:** accepted
+- **Date:** 2026-03-21
+- **Deciders:** @Aksem
+- **Tags:** actions, api, architecture, environments
+
+## Context
+
+Handlers may discover and invoke other actions at runtime through `IActionRunner`.
+That raises a contract question: how should one action identify another across
+extension environments?
+
+Two architectural directions were considered:
+
+- **Type-based identification.** Actions are identified by their shared action
+  definition type. Callers depend on the same lightweight definition package and
+  use that type when requesting an action.
+- **String-based identification.** Actions are identified by a string key that can
+  be resolved even when the action definition type is not installed in the caller's
+  environment.
+
+The main force behind the string-based option is cross-environment invocation: one
+environment may want to call an action implemented elsewhere. If action definitions
+are not available everywhere, a string identifier appears to decouple callers from
+those packages.
+
+However, introducing string identity shifts the architecture toward looser and less
+verifiable contracts. It makes action lookup depend on convention rather than shared
+types, and it weakens refactor safety and discoverability.
+
+This decision therefore depends on a broader packaging rule: whether FineCode treats
+action definitions as lightweight shared contracts that can be installed in every
+participating environment, or as implementation-bound artifacts that may be absent
+from some environments.
+
+## Related ADRs Considered
+
+None — no existing ADR covers the `IActionRunner` API design.
+
+## Decision
+
+FineCode will use **type-based action identification**. Actions are identified
+through their shared action definition types, not through string-only
+identifiers.
+
+This decision establishes the following architectural rule:
+
+- **Action definition packages are shared contract packages.** They must remain
+  lightweight, dependency-safe, and installable in any environment that needs to
+  refer to those actions.
+- **Action implementations belong elsewhere.** Heavy runtime dependencies,
+  platform-specific integrations, and tool execution logic belong in handler or
+  environment-specific packages, not in the shared action-definition package.
+
+With that boundary in place, cross-environment action invocation still works because
+all participating environments can depend on the same shared action-definition
+package. A string-based lookup mechanism is therefore not part of the primary
+architecture.
+
+## Consequences
+
+- **Action identity is explicit and type-safe.** Callers and runners share the same
+  contract type, which improves readability, refactor safety, and tooling support.
+- **Package boundaries matter more.** Action-definition packages must be kept small
+  and free of heavy implementation dependencies. Extensions that define new actions
+  are expected to separate contract types from execution logic.
+- **Cross-environment compatibility becomes a packaging concern, not a lookup concern.**
+  Environments that collaborate on actions must share the relevant contract package.
+- **String-only lookup is deferred, not rejected.** If FineCode later needs to invoke
+  actions whose definitions genuinely cannot be installed in the calling environment,
+  the architecture should be revisited and an additional identifier mechanism may be
+  introduced at that time.

docs/adr/README.md

@@ -24,6 +24,29 @@ a new ADR supersedes the old one rather than editing it.
 4. Set status to `proposed` and open a PR for review.
 5. Once merged, update status to `accepted` and add a row to the index table below.
 
+## How to write a good ADR
+
+ADRs should capture the **durable architectural decision**, not the current
+implementation shape. A useful test is: if we refactor the API next month but
+keep the same decision, would the ADR still read correctly?
+
+- Write the decision at the level of architecture, contracts, boundaries,
+  ownership, compatibility, or policy.
+- Prefer titles that describe the enduring rule, not the current mechanism.
+- Record the forces and constraints that make the decision necessary, not just
+  the selected solution.
+- Use one primary term consistently throughout the ADR. If a language-specific
+  implementation term is helpful, introduce it once as an example rather than
+  switching terms back and forth.
+- Keep method names, function signatures, field layouts, and matching logic out
+  of the main narrative unless they are themselves the architectural decision.
+- Put narrow implementation details in `Implementation Notes` only when they are
+  needed to avoid ambiguity.
+- If an alternative is deferred rather than rejected, say when the decision
+  should be revisited and what condition would trigger that review.
+- Keep examples short. Prefer explaining the rule and trade-off over documenting
+  the present code structure.
+
 ## Index
 
 | #    | Title                                                                                                                          | Status   | Date       | Tags                           |
@@ -33,3 +56,4 @@ a new ADR supersedes the old one rather than editing it.
 | 0003 | [One Extension Runner process per execution environment](0003-process-isolation-per-extension-environment.md)                  | accepted | 2026-03-19 | architecture, extension-runner |
 | 0004 | [Auto-shutdown on disconnect timeout](0004-auto-shutdown-on-disconnect-timeout.md)                                             | accepted | 2026-03-19 | lifecycle, wm-server           |
 | 0005 | [Zero-based line numbers and ResourceUri fields in action payloads and results](0005-zero-based-lines-and-resourceuri-fields-in-action-payloads-and-results.md) | accepted | 2026-03-20 | actions, conventions           |
+| 0006 | [Shared action types as the action identity contract](0006-shared-action-types-as-the-action-identity-contract.md)            | accepted | 2026-03-21 | actions, api, architecture, environments     |

docs/adr/template.md

@@ -28,6 +28,14 @@ What becomes easier or harder as a result of this decision? What are the
 trade-offs?
 
 <!--
+Authoring checklist:
+- Does the title describe the enduring decision rather than the current implementation?
+- Would this ADR still be correct if the API or method names changed next month?
+- Is the "Decision" section framed as an architectural rule, contract, or boundary?
+- Are implementation details kept out of the main narrative unless they are the decision?
+- Is one primary term used consistently throughout the document?
+- If an alternative is deferred, does the ADR say when to revisit it?
+
 ## Optional sections
 
 The sections above are the minimal required set. Add any of the following