Problem
`ctx.artifacts.appendActivity(line: string)` accepts a free-form string. The current guidance in MODULE_AUTHORING.md suggests the pattern ` key=value key=value`, but this is advisory only. In practice, module implementations diverge:
- Some prefix with the module name: `my-module.my-action field=value`
- Some omit the module prefix: `my-action field=value`
- There is no standard for which fields are required, their order, or how to represent compound values
- There is no distinction between a "started" log line and a "completed" log line
- Errors and outcomes are not represented — success/failure is fully implicit
This makes activity logs hard to read consistently across modules, and gives agents and humans no reliable structure to parse or display.
What we want
A standardized logging contract that:
- Defines a canonical line format — what prefix is required, what separator is used, which fields are mandatory vs optional
- Covers the action lifecycle — at minimum: when the action starts executing (what input it received), and optionally when it completes (what outcome it produced)
- Is enforced at the authoring level — either by convention in MODULE_AUTHORING.md or by a typed helper that produces the canonical format
- Is machine-readable enough to display — structured key=value or similar, so the dispatch renderer can parse and display activity lines without free-form string matching
Options to consider
- Convention only: define a strict format in MODULE_AUTHORING.md (e.g., `. key=value …`) with a required field list per action type
- Typed helper: replace or wrap `appendActivity(string)` with `appendActivity(action, fields)` where `fields` is a `Record<string, string | number>` — the implementation formats the canonical string
- Structured log entries: replace the string entirely with a typed object that the runtime formats for display
Notes
- Whatever format is chosen, it needs to be documented in MODULE_AUTHORING.md and reflected in the module-implementer and module-extender skill guides
- The `Artifacts` interface (`appendActivity(line: string): void`) is now part of the public dispatchkit surface — any change to the signature is a breaking change to module authors
Problem
`ctx.artifacts.appendActivity(line: string)` accepts a free-form string. The current guidance in MODULE_AUTHORING.md suggests the pattern ` key=value key=value`, but this is advisory only. In practice, module implementations diverge:
This makes activity logs hard to read consistently across modules, and gives agents and humans no reliable structure to parse or display.
What we want
A standardized logging contract that:
Options to consider
Notes