Skip to content

docs: sync documentation with implementation#1145

Open
nextlevelshit wants to merge 15 commits intomainfrom
fix/doc-fix-20260420-195123-8e6d
Open

docs: sync documentation with implementation#1145
nextlevelshit wants to merge 15 commits intomainfrom
fix/doc-fix-20260420-195123-8e6d

Conversation

@nextlevelshit
Copy link
Copy Markdown
Collaborator

@nextlevelshit nextlevelshit commented Apr 20, 2026

Summary

Automated documentation sync to fix drift between AGENTS.md and the current codebase. 4 of 4 scan findings fixed, 0 skipped. Types addressed: INCOMPLETE (2), INACCURATE (1), MISSING_DOCS (1). No source code modified.

Changes

AGENTS.md

  • File Structure tree — internal/ (DOC-1): Added 8 missing package entries in alphabetical order: attention/, classify/, fileutil/, humanize/, ontology/, testutil/, timeouts/, tools/. internal/ontology in particular was notably absent despite being documented in the Ontology Context Injection section.
  • File Structure tree — .agents/ comment (DOC-2): Replaced "Default personas, pipelines, contracts" with "Runtime artifacts: personas, pipelines, contracts, workspaces, traces, state DB" to reflect that .agents/ is the runtime root (defaults live embedded in internal/defaults/).
  • File Structure tree — cmd/wave/ (DOC-3): Replaced the single generic line with two specific entries: cmd/wave/main.go (CLI entry point) and cmd/wave/commands/ (Cobra subcommand implementations), so readers adding a new command know exactly where to look.
  • Pipeline Selection table (DOC-4): Added a note paragraph directing readers to wave list pipelines as the authoritative source for the full installed-pipeline catalog, covering the doc-*, plan-adr, plan-task, test-gen, audit-*, impl-*, and wave-smoke-* families that were not previously surfaced in the curated table.

Findings Addressed

ID Type Severity Title File
DOC-1 INCOMPLETE medium File Structure tree missing 8 internal packages AGENTS.md
DOC-2 INACCURATE low .agents/ tree description understates directory contents AGENTS.md
DOC-3 INCOMPLETE low cmd/ tree entry hides commands subpackage AGENTS.md
DOC-4 MISSING_DOCS low wave-evolve / undocumented pipelines in Pipeline Selection table AGENTS.md

Skipped

None. All 4 findings were fixable via docs-only edits.

Test Plan

  • All documentation changes are docs-only (no source code modifications)
  • Markdown formatting verified after edits (code fence for File Structure block still closed at line 113)
  • Tree rendering preserved: ├── / └── connectors intact
  • No new internal links introduced; existing link docs/migrations.md untouched
  • No content deletions; only additions and in-place replacements

@nextlevelshit
feat(contract): add shared artifact schemas for pipeline I/O protocol
9f41ca6 
Introduce eight canonical JSON schemas under internal/contract/schemas/shared/
that become the lingua franca for cross-pipeline handover: issue_ref, pr_ref,
branch_ref, spec_ref, findings_report, plan_ref, workspace_ref, scope_result.

The schemas are embedded via go:embed and exposed through a small registry
API (Lookup, Exists, Names). The sentinel "string" type is accepted as a
no-schema free-text fallback so pre-existing untyped pipelines keep working.

This is the foundation layer of the pipeline I/O protocol; consumers land in
follow-up commits. See docs/adr/010-pipeline-io-protocol.md.
@nextlevelshit
feat(manifest): typed pipeline inputs, outputs, and sub-pipeline wiring
bd871dc 
Extend the pipeline schema with optional type annotations:

  - InputConfig.Type   — declares the canonical I/O type of the pipeline's
                          input (issue_ref, pr_ref, ..., or "string").
  - PipelineOutput.Type — declares the canonical type of a named output.
  - Step.InputRef       — typed wiring for composition steps, replacing the
                          ad-hoc string template form. Exactly one of
                          'from: <step>.<output>' or 'literal: <text>'.

All new fields are optional. Unset or empty == "string", preserving
backward compatibility with every existing pipeline. See
docs/adr/010-pipeline-io-protocol.md.
@nextlevelshit
feat(pipeline): type-checked I/O handover at load time
8afd149 
Wire the shared schema registry into YAMLPipelineLoader so malformed
pipelines fail at parse time rather than at runtime. Adds:

  - ValidatePipelineIOTypes — catches unknown type names on input/outputs,
    malformed or conflicting input_ref blocks, and pipeline_outputs that
    point at non-existent steps.
  - TypedWiringCheck — cross-pipeline compatibility check (producer output
    type must match consumer input type). Invoked by higher layers that
    have access to a sub-pipeline loader.

YAMLPipelineLoader.Unmarshal now runs ValidatePipelineIOTypes immediately
after defaulting, so every code path that loads a pipeline (CLI, TUI,
WebUI, composition executor) gets load-time type validation for free.

Tests cover known/unknown types, string sentinel behaviour, empty-type
legacy fallback, InputRef exclusivity and the loader's rejection path.
@nextlevelshit
feat(pipeline): honour typed input_ref wiring in composition executor
fe1d1b6 
Teach CompositionExecutor.resolveStepInput about the new Step.InputRef
block. Resolution order is now:

  1. InputRef.From      -> raw JSON from tmplCtx.StepOutputs[srcStep]
  2. InputRef.Literal   -> template-resolved string
  3. Legacy SubInput    -> template-resolved string
  4. Parent input       -> tmplCtx.Input

Legacy string-templated sub-pipeline inputs keep working unchanged, so
every existing composition pipeline continues to run.
@nextlevelshit
refactor(pipelines): migrate four reference pipelines to typed I/O
8f30ddd 
Prove out the typed I/O protocol on four pipelines that exercise every
branch of the design:

  - impl-issue     — input: issue_ref, output: pr_ref.
  - impl-speckit   — input: string (natural-language feature description
                      is the right model), output: pr_ref.
  - plan-scope     — input: string (fetch-epic step parses it), adds a
                      new typed 'scope' output bound to scope_result.
  - ops-epic-runner — shows scope -> iterate over child_issues -> impl-issue
                       wiring. Iterate binds each element as {{item}}; the
                       child's declared input.type (issue_ref) matches the
                       element schema of scope_result.child_issues.

Both the .agents/pipelines/ and internal/defaults/pipelines/ copies are
updated. Step-level prompts, artifacts, contracts, and retry policies are
unchanged. Remaining 53 pipelines keep their implicit 'string' typing —
see the ADR for the phase-2 migration TODO list.
@nextlevelshit
docs(adr): ADR-010 pipeline I/O protocol
dbf985a 
Record the design of the typed pipeline I/O protocol: shared schema
registry, typed inputs/outputs, typed composition wiring, load-time
validation, and the phase-2 migration plan for the remaining pipelines.
@nextlevelshit
refactor(pipelines/audit): typed I/O migration
b5843c7 
Add explicit input.type and pipeline_outputs[*].type declarations to all
audit-* pipelines per ADR-010. Inputs default to string (free-text audit
scope hints); outputs mapped to findings_report. audit-dead-code-review
declares input.type: pr_ref since it scans PR diffs.

Load-validated via TestAllShippedPipelinesLoad. Live smoke skipped:
audit-dead-code-issue and audit-doc create GitHub issues (destructive);
audit-dead-code creates branches (destructive); remainder deferred to
batch end.
@nextlevelshit
refactor(pipelines/impl): typed I/O migration
b7f14e4 
Declare input.type and pipeline_outputs[*].type on all impl-* pipelines
per ADR-010.

Inputs: issue_ref for pipelines taking a GitHub issue/PR reference
(impl-issue-core, impl-research, impl-review-loop, impl-smart-route);
string for free-text feature/fix descriptions (impl-feature, impl-hotfix,
impl-improve, impl-prototype, impl-recinq, impl-refactor, impl-speckit).

Outputs: pr_ref where the artifact genuinely references a produced PR;
findings_report where the artifact is an analysis/verdict/verification
report (impl-hotfix.verdict, impl-improve.verification,
impl-refactor.verification, impl-smart-route.assessment,
impl-issue-core.assessment).

Load-validated only. Live smoke skipped — all impl-* pipelines are
destructive (open PRs, create branches, push code).
@nextlevelshit
refactor(pipelines/plan): typed I/O migration
fc1168c 
Declare input.type and pipeline_outputs[*].type on all plan-* pipelines
per ADR-010. plan-research takes issue_ref; plan-adr, plan-approve-implement,
plan-task take string. Outputs typed plan_ref except plan-scope.report
(scope_report is a bespoke verification shape, left as string).
plan-scope.scope already typed scope_result by prior migration.

Load-validated only. Live smoke skipped — plan-scope creates issues
(destructive); plan-research posts plans to issues (destructive);
plan-adr writes ADR docs (could run locally but out of scope).
@nextlevelshit
refactor(pipelines/ops): typed I/O migration
b7afbc4 
Declare input.type and pipeline_outputs[*].type on all ops-* pipelines
per ADR-010.

Inputs: pr_ref for PR-review pipelines (ops-pr-review, ops-pr-review-core,
ops-pr-fix-review); issue_ref for issue-driven ops (ops-implement-epic,
ops-refresh, ops-rewrite); string for the rest (ops-bootstrap,
ops-debug, ops-issue-quality, ops-parallel-audit, ops-release-harden,
ops-supervise, ops-hello-world, ops-epic-runner already string).

Outputs: findings_report for review/audit/debug reports; pr_ref for
ops-rewrite (enhancement_results retyped to findings_report since it is
a verification report, not a PR); workspace_ref for ops-bootstrap;
issue_ref for ops-refresh; scope_result for ops-epic-runner.scope
(matches the plan-scope sub-pipeline output).

Load-validated only. All ops-* pipelines either open PRs, post comments,
or modify issues — destructive, live smoke skipped.
@nextlevelshit
refactor(pipelines/doc): typed I/O migration
6186d0d 
Declare input.type: string and pipeline_outputs[*].type: findings_report
on doc-changelog, doc-explain, doc-fix, doc-onboard per ADR-010.
All four accept free-text scope hints and produce finding-style reports
about documentation drift or generated content.

Load-validated only. doc-fix and doc-onboard may open PRs (destructive);
doc-changelog and doc-explain are read-only but live smoke deferred to
batch-end.
@nextlevelshit
refactor(pipelines/wave): typed I/O migration
7f52619 
Declare input.type and pipeline_outputs[*].type on all wave-* pipelines
per ADR-010. All wave-* inputs are string (free-text audit/smoke focus
areas, PR refs as text, branch names). Outputs are findings_report for
the self-evolution pipelines (wave-audit, wave-evolve, wave-review,
wave-security-audit, wave-test-forge, wave-test-hardening,
wave-validate, wave-smoke-test); pr_ref for wave-land (ships a PR);
findings_report for wave-review, wave-scope-audit, wave-orchestrate
(retyped from incorrect pr_ref default — classification/review/issues
are analysis outputs, not PR references).

wave-smoke-* and wave-ontology-* pipelines declare input.type: string
and keep empty pipeline_outputs by design — they exercise executor
paths and need free shape per ADR-010 phase 2 notes.

Load-validated only. Live smoke on read-only wave-smoke variants
deferred (depends on bubblewrap + mount state).
@nextlevelshit
refactor(pipelines/misc): typed I/O migration
0afa423 
Declare input.type and pipeline_outputs[*].type on the remaining
non-categorised pipelines per ADR-010:

- bench-solve: input string (problem statement), output findings_report
- test-gen: input string (target package), output findings_report
- full-impl-cycle: input issue_ref (GitHub issue), output pr_ref
  (composes impl-issue-core → test-gen → audit-* → wave-land →
  ops-pr-review-core, all now typed)

Load-validated only. full-impl-cycle opens PRs (destructive);
test-gen may create PRs; bench-solve runs the SWE-bench-style loop
and is safe to smoke but deferred pending BENCH_HOME state.
@nextlevelshit
test(pipeline): load-validate every shipped pipeline YAML
d6e2a5a 
Add TestAllShippedPipelinesLoad as a regression guard for the typed I/O
protocol. Walks .agents/pipelines and internal/defaults/pipelines,
invokes YAMLPipelineLoader.Load (which runs ValidatePipelineIOTypes)
on every *.yaml file. Any future pipeline with an unknown type name,
broken step reference, or malformed input_ref now fails CI instead of
breaking silently at runtime.
@nextlevelshit
docs: sync documentation with implementation
4805dee 
Fix 4 documentation inconsistencies found by doc-fix pipeline:
- DOC-1: internal/ tree missing 8 packages (AGENTS.md) — added attention, classify, fileutil, humanize, ontology, testutil, timeouts, tools
- DOC-2: .agents/ description outdated (AGENTS.md) — reflects runtime contents (workspaces, traces, state DB), not defaults
- DOC-3: cmd/wave/ layout not specific (AGENTS.md) — split into main.go entry point and commands/ subpackage
- DOC-4: Pipeline Selection table incomplete (AGENTS.md) — added note pointing to 'wave list pipelines' for full list

Skipped 0 items.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nextlevelshit