# Teach agents to generate valid Harness DSL

## Traceability

- Spec ID: harness-dsl-generation-skill
- Status: Implemented

## Intent

Ship a package-local skill that teaches coding agents to author complete,
valid Harness as Code v0.1 documents. The skill must route agents to the
canonical language contract, require deterministic compiler and resolver
validation, and preserve the runtime's declared-versus-materialized strength
boundary.

The skill belongs to `packages/harness/skills/` so it evolves with the DSL and
is included in the `@qoder-ai/harness` tarball. It is generation guidance, not
an executor: it must not start Qoder or Pi sessions, handle model credentials,
or claim native enforcement without runtime evidence.

## Acceptance Scenarios

- AC-1: Invoking `$generate-harness-dsl` gives an agent a concise workflow for
  eliciting a target, declaring components, bindings, plugins, and
  compositions, and returning a complete `.harness` document.
- AC-2: The routed reference documents the v0.1 grammar, semantic constraints,
  version and identifier rules, configuration value types, and the
  declared-versus-materialized strength boundary without duplicating runtime
  ownership.
- AC-3: A portable Node script compiles a supplied `.harness` file with the
  package public API, resolves all or selected compositions, emits structured
  JSON diagnostics, and exits non-zero for invalid or unresolved input.
- AC-4: Behavior tests exercise the validator with valid and invalid files;
  the skill package passes the system skill validator and repository agent
  asset lint.
- AC-5: The npm package manifest includes the package-local skill, and an npm
  pack inspection confirms `SKILL.md`, its reference, validator, and generated
  UI metadata are present without secrets or source-local dependencies.
- AC-6: A fresh AI forward test, run outside the repository worktree, follows
  the skill to produce DSL that passes the deterministic validator and reports
  any resolution degradation honestly.
- AC-7: Relative Markdown links remain valid and the repository documentation
  link graph stays green.

## Non-goals

- Changing the Harness DSL grammar, IR, resolver, or executor behavior.
- Running Qoder or Pi SDK inference as part of DSL generation or validation.
- Storing API keys, authentication material, or other secrets in the skill or
  generated DSL.
- Installing the skill globally or adding a new Coding Agent host adapter.
- Claiming `wired` or `enforced` materialization from declarations alone.
- Publishing a package, changing versions, release notes, or the changelog.

## Plan and Tasks

1. Initialize the package-local skill with the standard skill scaffolder and
   generate its UI metadata.
2. Write a compact `SKILL.md`, a routed v0.1 contract reference, and a portable
   compiler/resolver validation script.
3. Include the skill directory in the package tarball and add behavior tests
   for the validator's success and failure contracts.
4. Run skill, package, documentation, and pack validation, then forward-test
   the instructions with a fresh AI agent from a neutral directory.
5. Record observed evidence and review the final staged/unstaged boundary.

## Test and Review Evidence

- AC-1/AC-2: `SKILL.md` routes to one focused v0.1 contract reference and the
  package example. System `quick_validate.py` accepted the skill structure and
  metadata; `agent-lint --profile agent-assets-review` reported one skill with
  zero findings, errors, warnings, or advisories.
- AC-3/AC-4: `npm run harness:build` and the 42-test package suite passed. The
  behavior tests execute the shipped Node validator against both the package
  example and invalid temporary input, asserting parsed JSON, exit status, and
  declared-versus-realized strength rather than source text.
- AC-5: package `npm pack` prepack gates passed and produced a 40-entry tarball
  containing `SKILL.md`, `agents/openai.yaml`, `references/dsl-contract.md`, and
  `scripts/validate.mjs`. A clean temporary install of that tarball ran the
  installed validator successfully against the installed Qoder example.
- AC-6: an isolated fresh agent used the skill to create
  `safe-repository-change` outside the repository. Independent validation
  compiled and resolved it with no diagnostics, satisfying repository impact
  at advisory strength and reporting verification honestly degraded from
  declared `enforced` to materialized `advisory`. An attempted Qoder CLI run
  stopped before inference because the isolated config was not logged in; it
  is not counted as forward-test evidence.
- AC-7: the focused documentation link graph passed all six assertions, and
  root pack verification passed with 524 npm entries and 546 runtime-zip
  entries. Generated Langium source verification also passed.
- Full regression: the root test run passed 1,322 of 1,324 tests. Two unrelated
  governance tests timed out at their 120-second limit; a focused rerun passed
  52 of 54 but timed out in two different test cases, indicating an unstable
  baseline timing issue rather than a deterministic assertion or changed DSL
  package behavior. Package, generated-source, documentation, validator, and
  pack gates all completed successfully when run separately.
- Risk: the validator imports `dist/` relative to the packaged skill. The clean
  tarball install smoke proves this layout; source-tree contributors must build
  before invoking it, and the failure message gives that command.
- Risk: generated DSL can overstate a host binding. The reference, workflow,
  behavior test, and fresh-agent output all preserve the v0.1 advisory ceiling
  and expose degradation in the resolution report.