Skip to content

feat: audience attribute (human | agent) on technique output declarations (#224 V4)#227

Merged
m2ux merged 2 commits into
mainfrom
feat/224-v4-audience-attribute
Jul 14, 2026
Merged

feat: audience attribute (human | agent) on technique output declarations (#224 V4)#227
m2ux merged 2 commits into
mainfrom
feat/224-v4-audience-attribute

Conversation

@m2ux

@m2ux m2ux commented Jul 14, 2026

Copy link
Copy Markdown
Owner

Summary

Adds an optional audience attribute (human | agent) to technique output / #### artifact declarations so each artifact's intended reader — and therefore its on-disk format — is known at authoring time. Purely additive and behaviour-neutral (absent ⇒ human), this is PR #1 of epic #224 (cluster 2 / backlog item V4) and the RC4 enabler for converting agent-state artifacts to compact structured data.

🐛 Issue 📐 Engineering


Motivation

Technique output declarations carry no signal about who each produced artifact is for. Human-facing artifacts (reviews, plans) and agent-only state artifacts are declared identically, so every artifact is authored as prose — verbose to produce, costly in tokens, and unreliable for an agent to read back later in the same run. Without an explicit reader marker, the downstream verbosity-reduction work (V5+) has no principled basis for deciding which artifacts may become compact structured data.

This change introduces the audience marker as the enabling primitive. On its own it changes nothing a reader sees and no workflow behaviour, but it lets later work serialize agent-audience artifacts as JSON with confidence about the intended reader.


Changes

  • Protocol specification - documents the audience attribute on output / #### artifact declarations, the agent-⇒-JSON on-disk convention under the artifactPrefix rule, and authoring guidance (decision test, per-side anti-patterns, V5 out-of-scope note).
  • Schema - adds the optional audience enum (human/agent) to the technique output schema, validated under strict parsing so an out-of-set value is rejected loudly at load.
  • Loader - generalizes subsection parsing to a reserved-key set and lands audience on parsed outputs, passed through verbatim.
  • Delivery projection - carries the audience through the worker-delivered technique bundle and the get_activity artifacts contract, so an artifact's format is known at write time; the projection round-trip needed no source edit.
  • Corpus lint - a standalone check:audience guard flags any agent-audience output whose artifact name is not JSON, baseline-snapshotted (empty by design) and wired into the lint suite with a regression guard.
  • Tests - per-surface coverage across loader parse (human/agent/absent/invalid), schema accept/reject under strict parsing, projection carry-through, and activity-contract carry-through; full suite 579 passed, 0 failed.

🤖 AI Assistance

  • Assistant / Model: claude / claude-opus-4-8
  • Context scope: repo-only
  • Prompt classes: code-generation, test-writing, docs
  • Provenance log: 08-provenance-log.md

📌 Submission Checklist

  • Changes are backward-compatible (or flagged if breaking)
  • Pull request description explains why the change is needed
  • Self-reviewed the diff
  • I have included a change file, or skipped for this reason: additive optional field, no user-facing behaviour change
  • If the changes introduce a new feature, I have bumped the node minor version
  • Update documentation (if relevant)
  • No new todos introduced

🔱 Fork Strategy

  • Node Runtime Update
  • Node Client Update
  • Other
  • N/A

🗹 TODO before merging

  • Ready for review
  • Address reviewer feedback
  • Squash if needed on merge (use local signed squash-merge flow)

Seed commit anchoring the draft PR for PR #1 of epic #224 (server-side
V4: audience attribute on technique output declarations). Implementation
follows.
@m2ux m2ux self-assigned this Jul 14, 2026
m2ux added a commit that referenced this pull request Jul 14, 2026
Record draft PR #227 in the Links table now that the PR exists.
Add an optional audience enum (human | agent) to technique output /
artifact declarations, threaded end-to-end and additively:

- schema: audience on OutputItemDefinitionSchema plus the hand-maintained
  technique.schema.json (kept in lockstep)
- loader: parse the audience reserved sub-section on an output entry;
  strict-mode schema rejects invalid values
- get_activity: composeActivityArtifacts carries audience into the
  artifacts contract and _meta.artifacts
- docs: technique-protocol-specification section 3.2 documents the
  attribute, the agent-audience JSON convention, and human-vs-agent
  authoring guidance (decision test plus anti-patterns; per-artifact
  schemas are out of scope for this PR)
- lint: standalone scripts/check-audience.ts guards the agent-JSON
  convention across the corpus
- tests: parser, schema, projection carry-through, and contract coverage

Declarations without audience remain valid (backward-compatible).
PR #1 of epic #224 (V4).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Mike Clay <mike.clay@shielded.io>
@m2ux m2ux marked this pull request as ready for review July 14, 2026 06:06
m2ux added a commit that referenced this pull request Jul 14, 2026
DCO attestation (certify) and finalized PR #227 (Final body, marked
ready-for-review) for #224 V4. Awaiting review.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Mike Clay <mike.clay@shielded.io>
@m2ux m2ux merged commit c83ef2d into main Jul 14, 2026
2 checks passed
m2ux added a commit that referenced this pull request Jul 14, 2026
Review approved clean (no reviewer changes) for #224 V4; PR #227
ready-for-review with finalized body. review-analysis artifact + README.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Mike Clay <mike.clay@shielded.io>
m2ux added a commit that referenced this pull request Jul 14, 2026
Close-out for #224 V4: 14-COMPLETE.md (summary + retrospective), test
plan finalized with source links. Worktree removed; PR #227 ready and
approved, open pending merge. Work-package workflow complete.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Mike Clay <mike.clay@shielded.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant