@tiic-tech/openworkflow 0.1.1 → 0.1.2

package/references/planning-skill-runtime-exposure.md

@@ -0,0 +1,159 @@
+# Planning Skill Runtime Exposure Boundary
+
+This reference defines the accepted design-only boundary for exposing planning
+skills such as `decompose-to-changes`, `analyze-changes`, and `select-change`
+through OpenWorkflow runtime and generated adapter surfaces.
+
+It implements the approved `C004` Option B path. It does not authorize runtime
+registry, artifact registry, adapter generation, or generated-surface changes.
+
+## Purpose
+
+Planning skills are currently repo-local dogfood skills. They operate on
+durable planning artifacts under `changes/<plan_id>/` and are useful before the
+formal `.openworkflow` spec/change/team chain is fully instantiated.
+
+Runtime exposure is valuable only if it preserves three boundaries:
+
+- source skills remain implementation-independent planning behavior;
+- core owns semantic workflow and artifact contracts;
+- adapters own platform-specific delivery and generated files.
+
+## Authority Boundaries
+
+### Core Semantic Registry
+
+Core may define semantic command or capability names, command scope, allowed
+outputs, forbidden outputs, handoff behavior, and artifact contract metadata.
+
+Core must not contain Codex-specific paths, frontmatter rules, generated file
+names, or skill invocation syntax.
+
+### Artifact Contracts
+
+Artifact contracts may define source-of-truth files, required fields, summary
+policies, current pointers, and read-order expectations.
+
+Planning artifacts must stay summary-first. Default low-context read models
+should consume `SUMMARY.yaml`, current slices, or compact indexes before full
+candidate queues.
+
+### Adapter Delivery
+
+Adapters own generated skill files, platform metadata, frontmatter, file layout,
+manifest entries, and drift checks for their platform.
+
+The Codex adapter may generate `.agents/skills/ow-*` surfaces only from source
+registries and templates. Generated files must not be hand-edited to prove a
+behavior change.
+
+### Generated Surfaces
+
+Generated `.agents/**`, `.openworkflow/**`, and managed `AGENTS.md` sections are
+outputs. Product behavior changes must land in source registries, artifact
+contracts, templates, validators, or references first, then be regenerated with
+`openworkflow sync`.
+
+### Source Skills
+
+Source skills under `skills/` remain the dogfood implementation references
+until runtime exposure is accepted. Their behavior can be promoted only through
+explicit, validated source contracts.
+
+## Runtime Exposure Invariants
+
+- One source of truth per behavior: source skill, core command, artifact
+  contract, and adapter template must not each define competing semantics.
+- Runtime exposure must preserve repo-local delivery as the default trust
+  model.
+- Every new generated surface needs parity or drift validation before it is
+  trusted.
+- Planning queues are feat boundaries; selected candidates remain commit-sized
+  slices.
+- Cross-queue analysis is advisory; selection remains inside one owning queue.
+- High-risk candidates still require a decision report and explicit approved
+  option before implementation.
+
+## Approved Command Semantics
+
+The accepted C010 direction is to promote the planning source skills to formal
+OpenWorkflow semantic command ids:
+
+- `/ow:decompose-to-changes`: creates, queries, and maintains one
+  `CANDIDATE_CHANGES.yaml` queue under `changes/<plan_id>/`. It owns planning
+  decomposition and queue maintenance, but it must not select a candidate or
+  implement code.
+- `/ow:analyze-changes`: reads one or more candidate queues and writes advisory
+  `CHANGE_ANALYSIS.yaml` evidence. It recommends the next plan id and candidate
+  id, including high-risk stop recommendations, but it must not mutate queues,
+  select candidates, or authorize high-risk implementation.
+- `/ow:select-change`: consumes a queue or explicit analysis recommendation and
+  writes `SELECTED_CHANGE.yaml`, `ATOM_TASKS.yaml`, and
+  `IMPLEMENTATION_BRIEF.md` for one commit-sized candidate. It must re-check
+  branch, dirty-tree, dependency, and high-risk gates before selection.
+
+These command ids are core semantic decisions. Core owns the command names,
+source-of-truth behavior boundaries, required and forbidden context, output
+contracts, and high-risk gates.
+
+The C011 generated-surface follow-up delivers these command ids through Codex
+repo-local skills generated from the command registry. Source skills remain the
+behavior references for the planning protocols; generated `.agents/skills/ow-*`
+surfaces must stay derived from source registries and templates.
+
+## Read-Model Expectations
+
+Planning runtime exposure must not load full planning history by default.
+
+Default read models should prefer:
+
+1. `.openworkflow/CURRENT_STATE.yaml` for active pointers.
+2. `SUMMARY.yaml` for each active planning queue.
+3. `CHANGE_ANALYSIS.yaml` when a cross-queue decision is being consumed.
+4. `SELECTED_CHANGE.yaml` and `ATOM_TASKS.yaml` for the selected candidate.
+5. Full `CANDIDATE_CHANGES.yaml` only when selection, queue maintenance, or
+   audit requires source truth.
+
+`references/planning-artifact-contracts.md` defines the planning artifact
+registration roles and minimum summary fields. Runtime exposure work must
+depend on that registration contract before adding command, adapter, or
+generated-surface behavior.
+
+## Follow-Up Candidate Split
+
+Future runtime exposure should be split into smaller candidates:
+
+- `C009`: define planning artifact registration and summary/read-model
+  contract. Complete when limited to contract/reference design.
+- `C010`: add command or capability registry semantics without adapter
+  generation. High risk until a specific registry boundary is approved.
+- `C011`: add Codex adapter generation for accepted planning surfaces. Complete
+  for Codex repo-local delivery of DTC, AC, and SC generated skills.
+- `C012`: add runtime-surface and agent e2e verification fixtures. Medium risk
+  when it only verifies existing source behavior; high risk if it changes
+  generated surfaces.
+- `C013`: reassess full `C004` runtime exposure after the smaller candidates
+  prove boundaries.
+
+## Validation Gates
+
+Every follow-up must run:
+
+- `npm run validate`
+- `git diff --check`
+
+Runtime or generated-surface follow-ups must also run:
+
+- `node dist/cli/src/index.js sync --root . --tools codex --json`
+- `node dist/cli/src/index.js doctor --root . --tools codex --json`
+- `npm run verify:runtime-surface`
+- `npm run verify:agent-e2e`
+
+## Non-Goals
+
+- No runtime command registry changes in the design-only boundary.
+- No artifact registry changes in the design-only boundary.
+- No adapter generation changes in the design-only boundary.
+- No generated `.agents/**`, `.openworkflow/**`, or `AGENTS.md` edits in the
+  design-only boundary.
+- No remote git or GitHub mutation.

package/references/proto-redesign-artifact-contracts.md

@@ -0,0 +1,217 @@
+# Proto Redesign Artifact Contracts
+
+This reference defines the artifact vocabulary for the image-first `/ow:proto`
+redesign. It is intentionally source-level: it does not change command runtime,
+generated adapter surfaces, or validation command visibility.
+
+## Scope
+
+The redesigned proto flow has two prompt-producing modes:
+
+- `strategic_proto_prompt_pack`: first-pass prompts generated from product
+  vision and optional validation evidence.
+- `refined_proto_prompt_pack`: screen-bound refinement prompts generated from
+  baseline prototype output, the original prompt pack, and a tune request.
+
+Review and decision evidence is recorded separately so prototype exploration
+does not become hidden production implementation.
+
+## Input Policy
+
+### VISION-Only Input
+
+`/ow:proto` may proceed from vision-only input when no validation artifact
+exists. In that mode it must:
+
+- state that validation evidence is absent
+- extract the core product uncertainty from the vision
+- generate strategic prototype directions, not implementation tasks
+- avoid pretending that a validation decision has already happened
+
+### Validation Present
+
+When `VALIDATION.yaml` and `PROTOTYPE_BRIEF.md` are present, `/ow:proto` must:
+
+- preserve the validation core question
+- keep validation include and exclude scope as hard prototype boundaries
+- use validation acceptance as evidence questions
+- avoid broadening into later or supporting features unless the validation
+  artifact explicitly includes them
+
+### Automatic Validation
+
+Automatic validation after vision creation is a separate future change. This
+contract only defines how proto consumes validation when it exists and how proto
+falls back when it does not.
+
+## Validation Consumption Policy
+
+`/ow:proto` treats validation as decision context, not as a mandatory gate.
+The active policy is `optional_explicit_validation`:
+
+- If `VISION.md` or a vision contract exists and validation artifacts are
+  absent, proto may proceed in `vision_only` mode.
+- If validation artifacts exist, proto must consume them and preserve their
+  boundaries.
+- If the user explicitly asks to skip validation, proto may proceed in
+  `vision_only` mode and record that validation was skipped.
+- If the vision is too vague to identify a product uncertainty, proto should
+  stop and ask for vision clarification instead of manufacturing validation.
+- Automatic validation derivation after vision creation is allowed only as a
+  future feature behind a separate selected change.
+
+### Input Priority
+
+When inputs disagree, apply this priority:
+
+1. Latest explicit user instruction.
+2. Accepted validation decision or prototype brief.
+3. Vision contract and non-goals.
+4. Current session constraints.
+5. Conservative product inference.
+
+Validation artifacts should narrow prototype scope. They should not silently add
+features that the vision excludes.
+
+### Required Policy Fields
+
+Every proto prompt pack should record:
+
+- `validation_input.mode`: `vision_only`, `validation_present`, or
+  `internally_derived`
+- `validation_input.refs`: source validation artifact refs, if any
+- `validation_input.notes`: concise explanation of missing, skipped, or
+  consumed validation context
+
+Use `internally_derived` only after a future feature explicitly implements that
+behavior. Until then, the value is reserved for compatibility.
+
+### Behavior Matrix
+
+| Situation | Proto behavior | Required note |
+|---|---|---|
+| Vision exists, validation missing | Proceed from vision | `validation_input.mode: vision_only` |
+| Vision exists, user skips validation | Proceed from vision | Note explicit skip |
+| Validation and prototype brief exist | Consume validation | `validation_input.mode: validation_present` |
+| Validation conflicts with vision | Stop for decision | Name the conflict |
+| Vision too vague | Stop for clarification | Name missing vision facts |
+| User asks to auto-validate | Create follow-up change | Do not silently auto-trigger |
+
+## Strategic Proto Prompt Pack
+
+Purpose: convert a product vision into multiple high-fidelity prototype prompt
+directions grounded in distinct strategic hypotheses.
+
+Required sections:
+
+- `source`: vision, optional validation refs, constraints, target tool, target
+  language, requested direction count
+- `normalized_input`: domain, primary user, core pain, behavior change, success
+  signal, differentiator, non-goals, trust or privacy constraints
+- `strategic_core`: target user, behavior change, mechanism, differentiator,
+  boundary conditions, central uncertainty
+- `directions`: one entry per strategic prototype direction
+- `build_recommendation`: first direction to generate and why
+- `review_plan`: success signals, failure signals, and next test
+- `negative_constraints`: what the generated prototype must not imply
+
+Each direction requires:
+
+- `direction_id`
+- `name`
+- `strategic_hypothesis`
+- `validates`
+- `main_risk`
+- `prototype_prompt`
+- `pm_judgment`
+
+Prototype prompts should specify screens, journey, interactions, AI or system
+behavior, trust/privacy controls, visual direction, anti-goals, and concrete
+sample content.
+
+## Refined Proto Prompt Pack
+
+Purpose: convert baseline prototype screens and a tune request into
+screen-bound prompts for the next generation pass while preserving product
+system intent.
+
+Required sections:
+
+- `source`: baseline screens, baseline prompt, product vision, tune request,
+  target form factor, locked elements, regeneration scope
+- `baseline_audit`: screen ids, journey stages, user goals, visible components,
+  system states, product features, trust boundaries, visual cues
+- `product_system`: product thesis, primary loop, interaction model,
+  information architecture, design language, component vocabulary, copy style,
+  trust and boundary system, anti-goals
+- `delta_rules`: `must_inherit`, `must_add`, `must_remove`, `flexible_change`
+- `screen_manifest`: target screen ids, source mappings, generation order
+- `global_design_prompt`
+- `screen_prompts`
+- `negative_prompt`
+- `acceptance_checklist`
+
+Each screen prompt requires:
+
+- `prompt_id`
+- `target_screen_id`
+- `source_screen_ids`
+- `screen_name`
+- `strategic_purpose`
+- `user_goal`
+- `system_state`
+- `canvas`
+- `must_inherit`
+- `must_add`
+- `must_remove`
+- `flexible_changes`
+- `layout_structure`
+- `required_components`
+- `required_copy`
+- `interaction_states`
+- `system_behavior`
+- `trust_privacy_safety`
+- `visual_style_rules`
+- `negative_constraints`
+- `desired_user_feeling`
+- `acceptance_criteria`
+
+## Review Evidence
+
+Prototype review evidence should record:
+
+- generated artifact refs
+- source prompt pack refs
+- selected direction or screen ids
+- user feedback
+- accepted elements
+- rejected elements
+- tune requests
+- recommendation: `continue`, `tune`, `pivot`, `stop`, or `needs_more_evidence`
+- follow-up candidate ids when available
+
+Review evidence may refer to generated images, screenshots, or design tool
+outputs, but it should not embed large binary artifacts.
+
+## Decision Handoff
+
+After first-pass proto generation:
+
+- if one direction is accepted, hand off to tune or design/spec planning
+- if the direction is promising but not sufficient, create a refined prompt pack
+- if no direction validates the product uncertainty, revisit vision or
+  validation
+
+After tune generation:
+
+- accepted improvements become `must_inherit` in the next tune pass
+- rejected elements become negative constraints
+- production implementation must wait for an explicit selected change or spec
+
+## Non-Goals
+
+- Do not generate production implementation tasks from prompt packs.
+- Do not add `/ow:proto2html`.
+- Do not remove or internalize `ow:validation`.
+- Do not expose runtime command or adapter surfaces from this contract.
+- Do not hand-edit generated `.agents/` or `.openworkflow/` surfaces.

package/references/proto2html-artifact-contracts.md

@@ -0,0 +1,113 @@
+# Proto2html Artifact Contracts
+
+This reference defines the artifact vocabulary for `/ow:proto2html`. It is a
+contract-only change: it does not add a command, source skill, generated
+adapter surface, or HTML implementation.
+
+## Purpose
+
+`/ow:proto2html` converts an accepted benchmark prototype image or accepted
+screen group into one HTML reconstruction. It is a fidelity reconstruction
+step, not product exploration.
+
+The command boundary is intentionally narrow:
+
+- Input: accepted benchmark image evidence, source prompt lineage, and relevant
+  prototype review notes.
+- Output: one local HTML prototype plus structured fidelity evidence.
+- Handoff: a locked HTML prototype that can later feed `/ow:html2spec`.
+
+## Source Of Truth
+
+The source artifact is:
+
+```text
+.openworkflow/html-prototypes/<id>/HTML_PROTOTYPE.yaml
+```
+
+Supporting evidence lives next to it:
+
+```text
+.openworkflow/html-prototypes/<id>/
+  HTML_PROTOTYPE.yaml
+  prototype.html
+  FIDELITY_REPORT.yaml
+  screenshots/
+  SUMMARY.yaml
+```
+
+`HTML_PROTOTYPE.yaml` is the compact source of truth. `prototype.html`,
+screenshots, and visual diffs are evidence refs, not embedded YAML content.
+
+## Required Input
+
+Proto2html must start from accepted prototype evidence. At least one benchmark
+source is required:
+
+- accepted benchmark image path
+- accepted generated image set with selected benchmark id
+- accepted baseline screen group
+- accepted refined prompt pack with generated image refs
+
+The input record must preserve:
+
+- source prototype evidence ref
+- source prompt pack ref, when available
+- benchmark image or screen refs
+- decision or review evidence that accepted the benchmark
+- reconstruction scope
+- explicit exclusions
+
+If no accepted benchmark evidence exists, proto2html should stop and return to
+`/ow:proto` or `/ow:tune`.
+
+## HTML Output
+
+The output contract describes one single-file HTML reconstruction:
+
+- `html_artifact.path`: local path to `prototype.html`
+- `html_artifact.type`: `single_file_html`
+- `html_artifact.entrypoint`: relative path opened for review
+- `render_targets`: viewport targets used for reconstruction
+- `implementation_notes`: reconstruction choices that affect fidelity
+
+The HTML artifact should be reviewable locally and should not become a
+production app. Application architecture, persistence, auth, backend APIs, and
+deployment config are out of scope.
+
+## Fidelity Evidence
+
+Fidelity evidence records how closely the HTML reconstruction matches the
+accepted benchmark:
+
+- benchmark refs
+- rendered screenshot refs
+- visual comparison notes
+- matched elements
+- fidelity gaps
+- browser or rendering checks
+- known limits
+
+Fidelity gaps should be actionable and bounded. They should explain whether the
+gap is acceptable for spec extraction or requires another reconstruction pass.
+
+## Decision And Handoff
+
+The artifact result should be one of:
+
+- `accepted`: HTML is good enough to lock for spec extraction.
+- `needs_reconstruction`: HTML needs another proto2html pass.
+- `return_to_tune`: benchmark image is not stable enough.
+- `blocked`: required benchmark or rendering evidence is missing.
+
+The normal accepted handoff is `/ow:html2spec`.
+
+## Non-Goals
+
+- Do not explore new product directions.
+- Do not generate new prototype images.
+- Do not tune the visual concept; return to `/ow:tune` for that.
+- Do not create engineering specs.
+- Do not create production implementation tasks.
+- Do not add `/ow:proto2html` runtime command or adapter surfaces from this
+  contract-only change.

package/references/skill-system-lifecycle.md

@@ -0,0 +1,198 @@
+# Skill System Lifecycle
+
+This reference defines OpenWorkflow's native skill format and lifecycle. It is
+the read-first contract for future changes that edit skill generation, adapter
+delivery, generated-surface validation, or runtime command exposure.
+
+## Format Contract
+
+An OpenWorkflow runtime skill is a Markdown skill file with YAML frontmatter and
+XML-like semantic blocks. It is not a full XML document and must not be wrapped
+in a top-level `<skill>` element.
+
+Current generated Codex runtime skills follow this shape:
+
+```md
+---
+name: "ow-proto"
+description: "Create image-first strategic prototype prompt packs..."
+---
+<!-- generated-by: openworkflow; adapter: codex; adapter-version: 0.1.0; template-id: codex.skill.ow.proto -->
+# /ow:proto
+
+<user_behavior>
+...
+</user_behavior>
+
+<agent_protocol>
+...
+</agent_protocol>
+
+<codex_skill>
+...
+</codex_skill>
+```
+
+The frontmatter is for agent discovery. The Markdown heading and prose are for
+human and agent readability. The XML-like blocks are for stable agent protocol
+boundaries.
+
+## Frontmatter Policy
+
+Required fields for generated runtime skills:
+
+- `name`: the repo-local skill name, such as `ow-proto`
+- `description`: short invocation guidance for the target agent platform
+- `metadata`: generated identity fields, including generator name, adapter id,
+  adapter version, template id, source command id, semantic trigger, and skill
+  name
+
+Source skills under `skills/` may use their own frontmatter as required by the
+skill authoring system, but source skills are not runtime `/ow:*` surfaces until
+they are registered and generated through an adapter.
+
+The generated marker remains the ownership signal used by sync and cleanup.
+Structured metadata gives validators and agents a queryable identity layer, but
+it does not replace the generated marker.
+
+## Protocol Blocks
+
+OpenWorkflow uses XML-like blocks because they give agents low-context,
+machine-locatable boundaries inside otherwise readable Markdown.
+
+The block taxonomy is:
+
+- `<user_behavior>`: visible-response behavior and interaction style for the command.
+- `<agent_protocol>`: private command protocol. Agents must not quote or expose this block as routine output.
+- `<source_of_truth>`: durable state root, currently `.openworkflow/`.
+- `<stage>` and `<command_visibility>`: lifecycle stage and user/internal command visibility.
+- `<interaction_mode>`: command-specific mode, such as conversation-first or image-first.
+- `<inner_thinking>`: private reasoning guardrails. This block authorizes private classification and scope checks, not disclosure of chain of thought.
+- `<required_context>`: files or indexes that must be loaded before acting.
+- `<optional_context>`: files that may be loaded only when summaries or required context are insufficient.
+- `<forbidden_context>`: paths that should not be loaded for this command.
+- `<allowed_outputs>`: durable outputs the command may create or update.
+- `<conditional_outputs>`: outputs allowed only under named conditions.
+- `<artifact_contracts>`: compact artifact contracts relevant to the command.
+- `<forbidden_outputs>`: outputs the command must not create.
+- `<audit_checkpoints>`: before, during, and after checks that keep the workflow trustworthy.
+- `<working_protocol>`: common execution rules for loading, acting, and narrowing scope.
+- `<artifact_checkpoint>`: rules for when durable artifact writes are appropriate.
+- `<anti_patterns>`: known behavior that should be rejected.
+- `<handoff>` and `<handoff_commands>`: readiness and next-command boundaries.
+- `<codex_skill>`: Codex adapter metadata that links the generated skill to the semantic command.
+
+Blocks may contain Markdown lists or short prose. They are XML-like delimiters,
+not an XML schema. Block contents should still escape literal `<`, `>`, and `&`
+where generated content needs to be rendered inside another XML-like block.
+
+## Lifecycle
+
+The source-of-truth chain is:
+
+1. `packages/core/src/commands/registry.ts` defines semantic `/ow:*` commands,
+   stages, visibility, target artifacts, and command protocols.
+2. `packages/core/src/artifacts/registry.ts` defines discovery artifact
+   contracts consumed by command generation and audit outputs.
+3. Adapter generators, currently under `packages/adapters/codex/src/`, render
+   repo-local runtime surfaces.
+4. `openworkflow init` and `openworkflow sync` write generated surfaces.
+5. Generated files are committed only after source changes and sync or init have
+   produced them.
+
+Generated Codex surfaces include:
+
+- `.agents/skills/ow-*/SKILL.md`
+- `.agents/skills/ow-*/agents/openai.yaml`
+- `.agents/openworkflow-adapter.yaml`
+- `.openworkflow/audit/*`
+- `AGENTS.md` managed content when onboarding guidance changes
+
+Do not hand-edit generated surfaces to change product behavior. Update command
+registries, artifact registries, adapter templates, schemas, validators, or
+source skills, then regenerate.
+
+## Repo-Local Delivery
+
+OpenWorkflow's default delivery is repo-local. Runtime skills live with the
+repository so agents can consume the same workflow contract as the codebase.
+
+OpenSpec's global Codex prompt installation model is useful as a reference for
+adapter abstraction, but it is not the default OpenWorkflow model. OpenWorkflow
+should not move `/ow:*` behavior into user-home prompt files because that would
+weaken reproducibility, reviewability, and repository auditability.
+
+Future adapter work may introduce delivery metadata such as skill-only,
+command-only, or both. That metadata must keep repo-local delivery as the
+default unless a future change explicitly accepts a different trust model.
+
+## Relationship To OpenSpec
+
+The OpenSpec research produced useful lifecycle lessons:
+
+- Template source and generated skill files should be separated.
+- A central registry should list skills, command ids, directory names, and
+  delivery targets.
+- Adapter-specific path and frontmatter rules should live behind adapter
+  boundaries.
+- Generated files should carry version or generated metadata that supports
+  drift detection.
+- Profile or delivery concepts can separate "which workflows exist" from "how
+  they are installed."
+
+OpenWorkflow should not copy these parts directly:
+
+- Markdown-only runtime skill protocols are too weak for OW's artifact and
+  handoff boundaries.
+- Global Codex prompt installation does not match OW's repo-local audit model.
+- File-existence-only drift checks are weaker than OW's command, artifact, and
+  audit contracts.
+- Hardcoding all protocol text in one template layer would make artifact
+  contracts secondary; OW should keep command and artifact registries as the
+  primary source.
+
+## Static Skills And Dynamic Instructions
+
+Runtime skills are static command contracts. They tell the agent what command
+means, what context to load, what outputs are allowed, and when to hand off.
+
+Dynamic artifact instructions are a separate possible layer. The design contract
+is in `references/artifact-instruction-envelope.md`. If OW later adds an
+OpenSpec-like instruction envelope, it should be generated for a specific
+artifact or selected task and may use tags such as `<task>`, `<context>`,
+`<rules>`, `<dependencies>`, `<output>`, `<template>`, and
+`<success_criteria>`.
+
+Dynamic instruction envelopes must never be copied into produced artifacts
+unless the artifact contract explicitly asks for them. They are constraints for
+the agent, not user-facing artifact content.
+
+## Drift And Validation Expectations
+
+Future validation should be able to answer:
+
+- Does every registered runtime command have the expected generated skill?
+- Does every generated skill identify its command, adapter, and template?
+- Do generated skills contain required frontmatter and protocol blocks?
+- Do generated audit indexes match command and artifact registries?
+- Does sync reproduce generated surfaces without manual patching?
+
+Until structured generated metadata is added, the generated marker remains the
+minimum ownership signal. Changes that touch runtime skills, adapter output, or
+audit indexes should run repository validation and runtime-surface verification
+when those commands are in scope.
+
+## Change Boundaries
+
+Use this reference before selecting or implementing changes that touch:
+
+- skill generation
+- command registry exposure
+- artifact contract registration
+- adapter delivery
+- generated-surface validation
+- `.agents/**`
+- `.openworkflow/audit/**`
+
+Small documentation or source-skill changes do not need to regenerate runtime
+surfaces unless they change the registered command or adapter output.