Prepare v0.1.0: MIT license, /devsecops-engineer commands, README, and release scaffolding

[mdixon47]

Closes the v0.1.0 scope from #180.

@damienjburks — this is scoped to the four things you asked for. The research, the alternate rule-catalog layout, and the methodology comparisons are tabled for v0.2.0+ as you requested; none of that is here.

There is a second section below containing correctness fixes found while working in the repo. One of them changes the normative catalog and needs your explicit sign-off — it is called out. Happy to split it into its own PR if you would rather review the release on its own.

---

Release requirements

1. License is now MIT

LICENSE.md is the standard MIT text, kept at the repository root and free of appended clauses so GitHub detects it as MIT rather than "Other".

Updated everywhere PolyForm was asserted: SKILL.md header, README.md, docs/CONTRIBUTING.md, docs/MAINTAINERS.md, and the issue-template contact links. Deleted docs/legal/COMMERCIAL-LICENSING.md — under MIT it describes a restriction that no longer exists.

Two legal edits worth a second pair of eyes:

• docs/legal/CLA.md named PolyForm in its relicensing clause; changed to "the MIT License or another open-source or source-available license". The broad grant still functions, but whether you want a CLA at all under MIT is your call.
• docs/legal/TRADEMARKS.md now states the boundary explicitly. It previously leaned on the noncommercial license to keep branding separate; under MIT it has to say so itself — the code is MIT, the DSB names, logos, and curriculum are not.

2. Command entry points

.claude-plugin/plugin.json (devsecops-engineer, v0.1.0, MIT) plus three commands:

Command	Mode
/devsecops-engineer:advise	Where controls belong, given a stack and the tools already owned
/devsecops-engineer:design	Implementation-ready pipeline configuration
/devsecops-engineer:assess	Findings against an existing pipeline or repository

Each is ~15 lines: select a mode, pass $ARGUMENTS through, read ${CLAUDE_PLUGIN_ROOT}/SKILL.md. assess discovers pipelines in the current repository when given no argument.

Commands stay thin, and it is enforced. A command that restates a rule creates a second catalog nobody validates, and then /devsecops-engineer:assess and a plain "review this pipeline" start giving different answers. tests/test_commands.py fails any command containing a rule ID or an enforcement level, and the policy is written down in docs/CONTRIBUTING.md.

SKILL.md stays at the repository root. The single-file install path and the standalone guarantee are unchanged.

3. README and onboarding

Rewritten as a product front door: what it is → why (four concrete outcomes) → 60-second install (skill and plugin) → three copy-paste prompts, each linked to the matching worked example → common workflows → how the reasoning works → documentation index → status → license.

Adds a table of contents, and links every file under docs/. docs/legal/CLA.md had never been reachable from the README. tests/test_readme.py asserts every ToC anchor resolves to a real heading and every docs/**/*.md is linked, so neither can drift.

4. v0.1.0 release prep

CHANGELOG.md with the v0.1.0 entry and explicit pre-1.0 language: the catalog and output structure will evolve with real usage; rule IDs are already stable and are deprecated rather than renumbered. A test asserts plugin.json and the changelog agree on the version, so they cannot diverge at tag time.

Also moved project documentation into docs/ to keep the root to the files people actually look for — README.md, SKILL.md, LICENSE.md, CHANGELOG.md. All moves are git renames, so history follows.

---

Correctness fixes

Found while working in the repo. Each is verifiable, and each has a regression test.

Needs your sign-off: 21 rules were keyed to the wrong capability

SKILL.md §2 step 3 resolves each rule's capability once, so one declared tool satisfies every rule naming it. That made these resolve to REUSE — requirement satisfied the moment an organization declared any pipeline-configuration scanner:

• DSB-SRC-001 branch protection, DSB-SRC-002 review before merge, DSB-SRC-003 fork trigger isolation
• DSB-ID-001/002/004 federated identity, least privilege, environment separation
• DSB-EVD-001/002/003 evidence retention, auditability, findings routing
• DSB-BUILD-004 ephemeral build environments

A Checkov-class tool does none of those things. Same shape elsewhere: sbom-generation on DSB-BUILD-001 meant Syft satisfied "builds execute from version-controlled source", and secret-scanning on DSB-ID-003 meant a detector satisfied a rule requiring a secret store.

The fix adds 10 capabilities to the registry and re-keys 21 rules onto them: build-traceability, dependency-resolution-control, build-environment-isolation, source-control-hardening, secrets-management, workload-identity-management, deployment-gating, pipeline-evidence-retention, security-findings-management, exception-management. §4's table is updated, and a paragraph explains why adjacent-sounding capabilities must stay distinct.

This is a change to the normative catalog. No rule IDs, requirements, rationale, enforcement levels, or applicability conditions changed — only the capability each rule resolves against. docs/CONTRIBUTING.md gains a checklist item so it does not recur.

The GitHub Actions reference pipeline failed on itself

delivery.yml's DSB-EXC-003 assertion grepped for continue-on-error: true, and its own source line contains that literal. Verified: it matched itself and exited 1 on a clean repository. That is indistinguishable from a real finding, and is how a check ends up deleted.

Patterns now live in env, bracket-escaped so they cannot self-match. The check also allows a line annotated # DSB-WARN: <rule-id> — §5.2 says continue-on-error is how this platform expresses WARN, so the blanket ban contradicted the skill. Both assertions verified: they pass on the file and still fire on real violations.

Other example defects

• aws ecs deploy is not an AWS CLI command. Replaced with describe-task-definition → register-task-definition → update-service, pinned to the digest the scan passed against.
• docker push payments-api:… targeted the public default registry with no login, contradicting DSB-ART-001. Added the ECR registry and login, and split the publish role from the deployment roles per DSB-ID-002.
• The scan jobs ran in parallel with test, contradicting DSB-TEST-001 (BLOCK) which the same file annotates as enforced. Now needs: test.
• The Jenkins example pinned its shared library to @v3, a mutable reference — the exact defect DSB-SC-002 exists to catch. Pinned to a commit; tests/test_examples.py now covers it.

Schema rejected fields the rules depend on

schema/workload-profile.schema.json is additionalProperties: false but omitted source.fork_prs_allowed (DSB-SRC-003), policy.signing_required (DSB-ART-002), policy.provenance_required (DSB-ART-003), registry.* (DSB-SC-001), and cicd.shared_library — all documented in §2's closed vocabulary. Two of the three published example profiles failed their own schema. Array fields also could not express unknown, though §2 says every field is tri-state. Fixed, with a test that walks §2's vocabulary block and fails on any field the schema rejects.

Repository now follows its own rules

• tools/requirements.txt pinned exactly. >= floors mean a commit does not resolve a fixed dependency set — DSB-BUILD-002 (BLOCK). Note this overlaps deps: update pyyaml requirement from >=6.0.2 to >=6.0.3 in /tools #3, deps: update pytest requirement from >=8.3.0 to >=9.1.1 in /tools #4, and deps: update jsonschema requirement from >=4.23.0 to >=4.26.0 in /tools #5; the pins match the versions Dependabot proposed, so those can likely be closed.
• CI now runs generate_mappings.py --check so the failure names its own fix.

Documented procedures that did not work

• TESTING.md's "prove the checks actually fire" exercise targeted module-2-6, module-3-1, a string not present in SKILL.md — a verified no-op that left the validator passing and taught the reader the opposite lesson. Rewritten and verified to fail.
• CONTRIBUTING.md's documented rule format omitted the curriculum module title the validator requires, so a contributor copying it got a CI failure.
• test_curriculum.py pinned snapshot_date == "2026-08-12", which turned following the documented refresh procedure into a broken build.

---

Verification

$ python tools/validate_skill.py
OK: 42 rules across 11 families, no violations

$ python tools/generate_mappings.py --check
OK: docs/framework-mappings.md is current

$ python -m pytest -q
106 passed

Up from 56 tests. Every fix above has a test that fails without it. All relative Markdown links across the repository resolve.

Not in this PR

The alternate rule-catalog layout from the implementation report — rules/build.yaml family files, scripts/validate_rules.py, references/capability-catalog.md, enforcement-model.md, applicability.md, restructured examples/advise|generate|review/ — is a parallel implementation of what already works here, and is the research you asked to table.

One correction to that report: it lists DSB-SCAN-001..010 and DSB-TEST-001..003. The live catalog has 8 SCAN rules and 2 TEST rules, and no-bloat behavior is carried by principles 5–7 plus the capability-resolution step rather than a dedicated DSB-SCAN-010. The 42/11 totals are right; the per-family breakdown is not.

After merge

Tag and publish v0.1.0.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a0d3c614e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Split identity controls before resolving them once

When existing_controls.workload-identity-management contains a full-scope OIDC provider, Step 3 resolves this capability once and consequently marks DSB-ID-002 as REUSE, even though federation does not prove that deployment roles are least-privileged; the same alias also suppresses DSB-ID-004 environment-separation findings. Give federation, privilege scoping, and environment isolation distinct capabilities, or support per-rule scope, so an identity tool cannot incorrectly satisfy unrelated BLOCK requirements.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Resolve the task definition from the ECS service

When an ECS service name differs from its task-definition family, this deployment fails before registering a revision because the AWS CLI option documentation limits --task-definition to a family, family:revision, or task-definition ARN, while this line passes the service name. Query the service's current taskDefinition ARN with describe-services, or introduce a separate task-definition-family setting, rather than assuming both names match.

Useful? React with 👍 / 👎.

[leeclay95]

Verified locally: validate_skill.py OK (42 rules / 11 families), generate_mappings.py --check current, 106 tests pass.