Instruction file imported from percebus/ai-tooling (.github/instructions/security/sssc-gap-analysis.instructions.md). Copyright stays with the author.

SSSC Phase 4 — Gap Analysis

Compare the repository's current supply chain security posture against the desired state using Phase 3 standards mapping output.

Gap Table Format

Produce a prioritized gap table sorted by Scorecard risk level (Critical > High > Medium > Low):

Gap	Scorecard Check	Risk	Concern	Current State	Target State	Adoption Type	Effort	Workflow/Script Reference
{description}	{check_name}	{Critical/High/Medium/Low}	{Low / Moderate / High}	{current}	{target}	{category}	{S/M/L/XL}	{reference}

The Risk column carries the OpenSSF Scorecard risk classification. The Concern column carries the qualitative residual concern level after considering the repository's current posture and compensating controls (Low, Moderate, or High). Concern is independent from Effort — a small effort may still address a high-concern gap.

Include all 20 Scorecard checks and any additional SLSA, Badge, Sigstore, or SBOM gaps not directly mapped to a Scorecard check.

Six Adoption Categories

Classify each gap into one of six adoption categories based on the required implementation effort:

1. Reusable Workflow Adoption

Reference an hve-core workflow directly via uses: in the target repository. Lowest effort — the target repo adds a workflow file that calls the reusable workflow.

Applicable checks: CI-Tests (#3), SAST (#14), Vulnerabilities (#19), and other checks where hve-core provides a reusable workflow_call workflow.

2. Workflow Copy/Modify

Copy a workflow from physical-ai-toolchain (or hve-core) and adapt it to the target repository's technology stack. Medium effort — requires editing workflow configuration.

Applicable checks: Dependency-Update-Tool (#8), SBOM (#15), Signed-Releases (#17), and other checks requiring repository-specific tuning.

3. Reusable Workflow + Script Adoption

Adopt both a reusable workflow and its supporting PowerShell or Python scripts. Medium effort — requires both workflow reference and script installation.

Applicable checks: Pinned-Dependencies (#13), Token-Permissions (#18), and other checks with validation scripts.

4. Platform Configuration

GitHub or Azure DevOps settings configured via the web UI or API. Variable effort — depends on organizational policies and admin access.

Applicable checks: Binary-Artifacts (#1), Branch-Protection (#2), Code-Review (#5), CII-Best-Practices (#4), License (#10), Security-Policy (#16), Webhooks (#20).

5. New Capability

Requires building something not available in either hve-core or physical-ai-toolchain. Highest effort.

Applicable checks: Fuzzing (#9) — requires setting up ClusterFuzzLite, OSS-Fuzz, or a custom fuzzing harness.

6. N/A / Organic

Not actionable as backlog items. These checks improve through natural project activity.

Applicable checks: Contributors (#6), Maintained (#11), Packaging (#12).

Effort Sizing

Assign T-shirt sizes based on implementation scope:

Size	Criteria	Typical Duration
S	Single file addition or configuration change	< 1 day
M	Multiple files or workflow customization required	1–3 days
L	Cross-cutting changes across CI/CD pipeline	3–5 days
XL	New capability build or major architectural change	1+ weeks

Qualitative Concern Levels

Assign a qualitative concern level to each gap reflecting residual risk after considering the repository's current posture and compensating controls. Concern is independent from Scorecard risk classification and from effort sizing.

Concern	Criteria
Low	Gap is informational or already partially mitigated by existing controls; minimal residual exposure
Moderate	Gap leaves measurable residual exposure but compensating controls reduce immediate impact
High	Gap leaves significant residual exposure with no effective compensating controls; prioritize remediation

Record concern in the gap table alongside Risk and Effort. Use Concern to break ties when multiple gaps share the same Scorecard risk classification.

Full 20-Check Reference Mapping

Use this reference table when mapping gaps. It provides the known implementation sources for each Scorecard check:

#	Scorecard Check	Risk	hve-core Implementation	PAT Implementation	Default Adoption Type	Default Effort
1	Binary-Artifacts	High	No binaries (convention)	Same	Platform config	S
2	Branch-Protection	High	CODEOWNERS, PR process	Same	Platform config	S
3	CI-Tests	Low	pr-validation.yml	ci.yml	Reusable workflow	M
4	CII-Best-Practices	Low	GOVERNANCE.md targets Silver	GOVERNANCE.md	Platform config	M
5	Code-Review	High	CODEOWNERS enforcement	CODEOWNERS	Platform config	S
6	Contributors	Low	Multi-contributor	Same	N/A (organic)	—
7	Dangerous-Workflow	Critical	Clean patterns; CodeQL	Same	Script adoption	S
8	Dependency-Update-Tool	High	dependabot.yml	dependabot.yml (12 ecosystems)	Workflow copy/modify	S
9	Fuzzing	Medium	❌ Gap	❌ Gap	New capability	L
10	License	Low	LICENSE (MIT)	LICENSE	Platform config	S
11	Maintained	High	Active dev	Active dev	N/A (organic)	—
12	Packaging	Medium	VS Code extension	Same	N/A (existing)	—
13	Pinned-Dependencies	Medium	Test-DependencyPinning.ps1, dependency-pinning-scan.yml	SHA-pinned actions	Workflow + script	M
14	SAST	Medium	CodeQL, PSScriptAnalyzer, ruff	CodeQL, ruff	Reusable workflow	M
15	SBOM	Medium	anchore/sbom-action	anchore/sbom-action, dual attest	Workflow copy/modify	M
16	Security-Policy	Medium	SECURITY.md (MSRC)	SECURITY.md	Platform config	S
17	Signed-Releases	High	attest-build-provenance, Sigstore	gitsign + dual attest	Workflow copy/modify	L
18	Token-Permissions	High	Test-WorkflowPermissions.ps1	Minimal perms	Workflow + script	M
19	Vulnerabilities	High	dependency-review.yml, pip-audit.yml	Same + Dependabot enrichment	Reusable workflow	M
20	Webhooks	Critical	Platform-managed	Platform-managed	Platform config	S

Adjust adoption type and effort based on the target repository's actual technology stack and existing tooling.

Gap Prioritization

Within the gap table, sort entries by:

Scorecard risk level: Critical > High > Medium > Low
Within the same risk level: checks with available reusable workflows before those requiring new capabilities
Within the same adoption type: lower effort before higher effort

Output

Write the analysis to .copilot-tracking/sssc-plans/{project-slug}/gap-analysis.md.

Structure the output as:

# Gap Analysis — {project-slug}

## Summary
- Total gaps: {count}
- Critical: {count} | High: {count} | Medium: {count} | Low: {count}
- Reusable workflow adoption: {count}
- Workflow copy/modify: {count}
- Workflow + script: {count}
- Platform config: {count}
- New capability: {count}

## Gap Table
{prioritized gap table}

## Adoption Recommendations
{per-category recommendations with specific workflow references}

Update state.json:

Set phases.4-gap-analysis.status to ✅
Add gap-analysis.md to phases.4-gap-analysis.artifacts
Advance currentPhase to 5

sssc-gap-analysis

About