feat: add comply pipeline workflow

[jpower432]

Summary

This PR adds a user invocable command for running with multiple stages - scoping from a system profile + mapping determines imports and parameters harmonization + adherence to determine what evidence will be collection.

Related Issues

Blocked by #31
Closes #26
Demo'd using #39

Review Hints

 /comply:pipeline   # scoping → mapping → adherence
 /comply:pack       # generates Rego from the child policy

 ls .complytime/          # scoping.yaml, delta-report.yaml, child-policy.yaml
 ls policy/               # *.rego files

[em-redhat]

PR Review: #40 — feat: add comply pipeline workflow

CI Status

Check	Status	Classification
Test (1.26)	PASS	N/A
Standardized CI / Run linters	PASS	N/A
Security Scan / OpenSSF Scorecards	PASS	N/A
Vulnerability Scan / OSV-Scanner / osv-scan	PASS	N/A
Vulnerability Scan / Trivy Source Scan	SKIPPED	N/A

Local Tool Results

Local tool	CI check that covers it	CI status	Run locally?
golangci-lint	Standardized CI / Run linters	PASS	No
go test	Test (1.26)	PASS	No

All CI checks pass. No local tool execution needed.

Summary

This PR adds a multi-stage compliance pipeline workflow (scoping → mapping → adherence) exposed as plugin skills, backed by new MCP tools (analyze_parameter_delta, enhanced get_assessment_requirements with scope filtering). The delta engine design is sound — it gathers structured parameter pairs and defers interpretation to the model, which aligns with ADR 014. Code is well-tested and well-structured.

What Was Checked

• CI: All checks pass — tests, linting, security scans, vulnerability scans
• Alignment: PR changes match stated intent (issue #26, ADRs 012-015). Scope is consistent.
• Security: Reviewed resolveFromCatalog synthetic policy construction, input handling in MCP tool handlers, no hardcoded secrets, no injection vectors, no file path construction from external input.
• Architecture: Reviewed separation between delta engine (internal/requirement/delta.go), MCP tool layer (internal/mcp/tool_delta.go), and skill documentation. Clean package boundaries maintained.
• Convention packs: Checked against default, go, and severity packs.

Findings

One MEDIUM finding on test fixture consistency — see inline comments.

Verdict

APPROVE

Well-structured PR with clean separation of concerns, comprehensive tests, and clear ADR rationale.

This review was generated by /review-pr (AI-assisted).

[em-redhat]

[MEDIUM] [TC-001] This ArtifactSet is missing the Mappings field introduced in this PR. While Go zero-values uninitialized map fields to nil (which doesn't cause panics in the current code path), this is inconsistent with NewArtifactSet() which initializes all fields including Mappings. If future code writes to Mappings on this test set, it will panic.

Suggested change

	set := testDeltaArtifactSet()
	return &ArtifactSet{
	Catalogs: map[string]*gemara.ControlCatalog{"container-baseline": catalog},
	Policies: map[string]*gemara.Policy{"org-parent-policy": policy},
	Guidance: make(map[string]*gemara.GuidanceCatalog),
	Mappings: make(map[string]*gemara.MappingDocument),
	}

[em-redhat]

[MEDIUM] [TC-001] Same issue here — ArtifactSet missing Mappings field. Recommend adding Mappings: make(map[string]*gemara.MappingDocument) for consistency with NewArtifactSet().

Suggested change

	Catalogs: map[string]*gemara.ControlCatalog{"container-baseline": catalog},
	set := &requirement.ArtifactSet{
	Catalogs: map[string]*gemara.ControlCatalog{"container-baseline": catalog},
	Policies: map[string]*gemara.Policy{"org-policy": policy},
	Guidance: make(map[string]*gemara.GuidanceCatalog),
	Mappings: make(map[string]*gemara.MappingDocument),
	}

[hbraswelrh]

APPROVE with 2 comments (novel findings not covered by prior review).

This review was generated by /review-pr (AI-assisted).

[hbraswelrh]

[MEDIUM] [TC-001] ArtifactSet fixture missing Mappings field — same pattern @em-redhat flagged in delta_test.go and tool_delta_test.go, but this instance was not covered. Inconsistent with NewArtifactSet() which initializes all fields.

Suggested change

	set := &ArtifactSet{
	Catalogs: map[string]*gemara.ControlCatalog{"test-catalog": catalog},
	Policies: map[string]*gemara.Policy{"test-policy": policy},
	Guidance: map[string]*gemara.GuidanceCatalog{"guidance-1": guidanceCatalog},
	Mappings: make(map[string]*gemara.MappingDocument),
	}

[hbraswelrh]

[MEDIUM] [DR-001] Exported struct fields lack GoDoc comments. The JSON tags document wire format but not semantics — e.g., what distinguishes PolicySource from CatalogSource, or what Label represents in the domain model. Consider adding field-level comments for downstream consumers.

[marcusburghardt]

Value

Ran the full pipeline locally (scoping → mapping → adherence → pack). The separation
of concerns is clear and effective:

• MCP tools handle data retrieval — get_assessment_requirements with scope
  filtering and analyze_parameter_delta remove the manual cross-referencing work.
• AI handles interpretation — reading prose requirements and deciding if a
  concrete parameter value satisfies them. This is where heuristics fail and LLMs
  actually add value.
• Humans keep the decisions — maturity level, system classification, and
  parameter acceptance stay with the user.

The "gatherer, not judge" design (ADR 014) is the right call. Each stage produces
an auditable YAML artifact, not a chat transcript.

Commit history

There are places where a commit introduces something and the next one immediately
fixes or reworks it within the same session. A few examples:

• ce66915 adds the delta engine with verdicts, then 572ca66 (31 min later)
  redesigns it as a gatherer. f26f877 and b315548 clean up leftovers. These
  four commits are one design iteration.
• 8e8f3ca adds the skills, then ed67ab5, 4760978, and b9c33e9 are
  successive fixups to the adherence YAML snippet.
• aef7b01 adds --source/--schema flags, then 1bdfb41 (15 min later) removes
  a hardcoded version it introduced.

Completely normal during development. The suggestion is to squash before merge so
git log on main reads as intentional steps. An interactive rebase could bring
16 commits down to ~7 clean units:

1. feat: add --source and --schema flags to mcp serve
2. feat: add parameter delta engine, scope filter, and resource listing
3. feat: add /comply plugin with pipeline, pack, and setup skills
4. docs: add ADRs 012-015
5. fix: allow get_assessment_requirements to accept catalog names
6. fix: CI permission and lint errors
7. fix: initialize Mappings field in test ArtifactSet fixtures

Local testing with OpenCode

Testing this PR locally with OpenCode required some extra steps worth documenting:

1. Skill discovery mismatch: The skills live in skills/pipeline/SKILL.md but
   OpenCode expects .opencode/skills/pipeline/SKILL.md. I had to create symlinks
   under .opencode/skills/. Claude Code discovers them via the plugin manifest
   instead. If the team uses both tools, consider adding .opencode/skills/ symlinks
   to the repo (.opencode/ is already gitignored) or documenting the setup.

2. MCP server wiring: OpenCode uses .mcp.json while Claude Code uses its own
   plugin system. I created a temporary .mcp.json pointing to a locally built
   binary with test artifacts. This worked, but required building from source and
   creating sample Gemara YAML files since the repo has no standalone test fixtures —
   all test data is inline Go string constants.

3. No test fixtures shipped: Having a testdata/ or examples/ directory with
   a minimal catalog + policy YAML would make local testing straightforward for any
   tool. Right now, the reviewer has to reverse-engineer the expected YAML format
   from Go test files.

A short "Testing the pipeline locally" section in the PR description or a
examples/ directory with sample artifacts would lower the barrier for reviewers
using any tool.