GuardSuite Pillar Template Monorepo

This repository houses everything needed to spin up production-grade GuardSuite pillars:

• guardsuite-core/ – shared SDK providing the canonical schema, evaluator lifecycle, CLI helpers, and canonicalization utilities.
• src/pillar/ – the canonical GuardTemplate pillar implementation that downstream teams extend.
• src/vectorscan/ – a live example pillar that demonstrates how the scaffold couples to guardsuite-core.

Use this repo as the north star for new GuardSuite products: start from src/pillar, depend on guardsuite-core, and follow the same CI/test posture.

Repository Layout

guardsuite-core/              # shared package consumed by every pillar
src/pillar/                   # canonical scaffold + implementation for new pillars
src/vectorscan/               # example pillar built from the scaffold
schemas/                      # canonical JSON schema + tooling
tools/, scripts/, fixpack/    # shared utilities, scaffold tools, sample fixpacks

Key entry points:

• src/pillar/cli.py – CLI that wires loader→evaluator→renderer via guardsuite-core.
• tests/ – regression suite that all new pillars should keep green.
• src/pillar/rules/registry.py – forwarder that exposes registry helpers from a stable namespace for downstream scaffolds.
• scripts/scaffold_new_pillar.py – copies the template into src/<pillar_id>/ and rewrites placeholders.

PH-002 Scaffolding Highlights

The 2.1.x specification requires core contract scaffolding that now lives in this repo:

• Evaluator pipeline + lifecycle tracing (src/pillar/evaluator.py): every stage transition is instrumented and surfaced through metadata.pipeline_trace and metadata.lifecycle_state. Pass --profile <name> to pillar scan to see the value echoed in the metadata block.
• Canonical schema fragments (schemas/core/common_issue_fragment.json, common_metadata_fragment.json, common_output_fragment.json) and pillar extension README guardrails (schemas/pillar/README.md). Each fragment contains x-fragment-governance metadata so guardtemplate verify can reason about provenance.
• Canonical output placeholder (schemas/output/canonical_output.json) plus a lightweight validator shim (src/pillar/schema_validator.py) invoked before results leave the evaluator.
• Adapter boundary + utilities (src/pillar/adapters/__init__.py, src/pillar/utils/resource_canonicalizer.py) defining the discover/fetch_metadata/capability_manifest interface pillars must implement.
• CLI surface parity: pillar verify now emits template_logs/verify-report.json, and pillar validate-self writes both template_logs/selftest-report.json and template_logs/canonical-output-preview.json. Both commands accept the contract flags --json, --quiet, --profile, and --out.
• Binary ABI manifest (binary_abi_manifest.yml) enumerates every core module with per-architecture checksum placeholders so PH-003+ can swap in signed digests.

Quick smoke checks:

# Run evaluator with lifecycle instrumentation visible in metadata.pipeline_trace
PYTHONPATH=src python -m pillar.cli scan tests/fixtures/minimal_plan.json --profile dev --output json | jq '.metadata'

# Generate placeholder verify/self-test artifacts
PYTHONPATH=src python -m pillar.cli verify --json
PYTHONPATH=src python -m pillar.cli validate-self --json --out template_logs/selftest
ls template_logs/

Getting Started

# 1. Install poetry + deps for the root template
make install

# 2. Validate the GuardTemplate pillar before making changes
poetry run pytest tests -v

# 3. Validate the sample pillar (vectorscan) wiring
cd src/vectorscan && poetry install && poetry run pytest -v

Creating a New Pillar

python scripts/scaffold_new_pillar.py \
	<pillar_id> \
	--profile vector \
	--with-workflows \
	--verify \
	--maintainer-name "Your Name" \
	--maintainer-contact "slack:#pillar-channel"

Key flags:

• --profile {vector,compute,pipeline} copies profile-specific docs + fixtures into docs/PROFILE_NOTES.md so GTM material matches the pillar class.
• --with-workflows copies .github/ and .pre-commit-config.yaml so the new pillar inherits CI + lint from day one.
• --maintainer-* values populate docs/spec.yml maintainer metadata before the scaffold is copied.
• --verify runs poetry install, poetry run pytest -q, and poetry run python tools/validate_spec.py from the new pillar to guarantee the scaffold is green before you push.

After scaffolding:

1. Open src/<pillar_id>/src/<pillar_id>/evaluator.py and set PillarEvaluator.PILLAR_NAME plus rule registrations.
2. Drop domain rules into src/<pillar_id>/src/<pillar_id>/rules/ (patterned after vectorscan/rules/public_buckets.py).
3. Add fixpack snippets under src/<pillar_id>/fixpack/<ISSUE_ID>.hcl and keep remediation hints pointed at fixpack:<ISSUE_ID>.
4. Update pyproject.toml to depend on guardsuite-core via a path or released tag.
5. Fill out docs/spec.yml (hero copy, integrations, CLI table) and re-run poetry run python tools/validate_spec.py until it stays consistent.
6. Tune tools/guardscore_config.template.json if the pillar has bespoke scoring rules, then run poetry run pytest -v until green.

Logging & Error Handling

• The CLI now uses structlog for structured JSON logs. Set PILLAR_LOG_LEVEL or pass --log-level {CRITICAL|ERROR|WARNING|INFO|DEBUG} to override the default WARNING level.
• All runtime failures bubble up as PillarError subclasses (PlanLoadError, EvaluationError, RenderingError, UnexpectedError) so new pillars can attach custom context while keeping consistent semantics.
• Errors are emitted as JSON payloads on stdout:

{
	"status": "error",
	"pillar": "PILLAR_NAME_REPLACE_ME",
	"timestamp": "2025-11-19T12:34:56.789012+00:00",
	"error": {
		"code": "PLAN_LOAD_ERROR",
		"message": "Unable to read plan input.",
		"exit_code": 2,
		"retryable": false
	}
}

• Info/debug logs stay on stderr so downstream automation can stream stdout safely while still capturing telemetry.

Working with guardsuite-core

guardsuite-core exposes:

• guardsuite_core.cli.BaseScanner
• guardsuite_core.engine.BaseEvaluator
• guardsuite_core.canonical.canonicalize_output
• guardsuite_core.validator.validate_output

Keep pillar packages thin by subclassing the core base classes and delegating schema logic to them. When developing locally, both the root template and pillars depend on the path version specified in their respective pyproject.toml files.

Development Workflow

# Format + lint
make format
make lint

# Run the reference CLI against fixtures
make run-example                  # uses tests/fixtures/minimal_plan.json
cd src/vectorscan && make run-example || true  # vectorscan provides same target

Recommended checks before sending changes:

• poetry run pytest tests -v
• cd src/vectorscan && poetry run pytest -v
• ruff . and black --check . (or just make lint)

Pillar CLI Surface

pillar-template exposes the same contract every downstream pillar must keep:

• scan – evaluates a plan and emits canonical JSON or the structured text renderer. Flags: --output {text,json}, --json, --quiet, --stdin, --explain ISSUE_ID, --strict, and the inherited --version.
• validate – replays the evaluator, asserts it passes guardsuite-core.validator.validate_output, then prints valid/issues. Flags: --json/--text, --quiet, --stdin, plus the shared --version.
• rules – lists registered rule ids, severities, and fixpack hints. Flags: --format {text,json}, --json, --quiet; --stdin is rejected with CLI_USAGE_ERROR so automation notices misuse.
• explain – shortcut for scan --explain ISSUE_ID with identical logging semantics and strict-mode behavior.

All commands flow through guardsuite_core.cli.BaseScanner, so --json, --stdin, --quiet, and --version remain global and deterministic. Fixpacks ship in-repo under fixpack/<ISSUE_ID>.hcl; explain/rules output surfaces remediation_metadata (fixpack_id, filename, available, snippet_preview) for every issue, matching fixpack_remediations in the evaluator payload.

CLI Explain Command

pillar.cli now ships a dedicated explain command so operators can surface fixpack references without re-running the full scan with --explain flags:

PYTHONPATH=src python -m pillar.cli explain tests/fixtures/minimal_plan.json

• Pass --issue-id TEMPLATE-001 to focus on a specific problem; omit it and the CLI selects the first canonical issue reported by the evaluator.
• Output matches scan --explain exactly, including exit codes for missing issue identifiers and the fallback "No issues available to explain." message when the plan is clean.
• --output json (or --quiet) emits { "issue_id": ..., "fixpack_ref": ... } so downstream tooling can parse the explain payload deterministically.
• The command accepts the same --stdin, --strict, and --version options as scan, ensuring parity for scripting environments.

CI & Quality

.github/workflows/ci.yml applies to both the template and sample pillar. It installs dependencies, runs lint, then executes the pytest suites so every pull request proves canonical schema compliance.

Reference Pillar: vectorscan

src/vectorscan mirrors what a real pillar repo would look like once scaffolded:

• pyproject.toml points at ../../guardsuite-core.
• src/vectorscan/src/vectorscan/evaluator.py registers rule_public_buckets for smoke coverage.
• tests/ copies the template suite but imports vectorscan.* so the package can be published as-is.

Use it as a blueprint when wiring your own pillar into CI or when validating new rules/fixpacks.

Resources

• Canonical schema: schemas/guardsuite_pillar_schema.json
• Spec overview: docs/pillar_requirements.md
• Scaffold instructions: README_DEVELOPER.md
• Developer deep-dive: README_DEVELOPER.md (top level)
• Sample pillar docs: src/vectorscan/README.md

---

GuardSuite pillars share the same DNA: they lean on guardsuite-core, emit canonical schema, and ship deterministic fixpacks. Keep this monorepo healthy and every new product inherits a production-ready foundation.