docs(soc2): document JS package provenance

[Wentzel-DevDocs]

Summary

• Adds the SEC-004 package security and provenance baseline for devdocsai-js.
• Documents npm publish controls, token handling, package integrity, SBOM/audit evidence, provenance target state, explicit gaps, and SOC 2 control mapping.
• Links the baseline from the repo README.

Verification

• npm ci passed. Warnings: deprecated dependencies and 47 audit findings on current dependency tree.
• npm run lint passed.
• npm run test passed: 17 files / 143 tests.
• npm run build passed.
• git diff --check passed.
• Removed generated *.tgz files before commit.

Linear

• DEV-100

Notes

• Existing older draft PR [SEC-004] Harden devdocsai-js package security and provenance #7 covers similar provenance text, but it is on a non-WENTZEL branch. This PR recreates the work on the required WENTZEL branch and updates the doc against current main workflow state.
• The doc intentionally lists Snyk, CodeQL, and SBOM workflows as gaps on main because those controls are in separate open PRs and are not yet merged.

Summary by CodeRabbit

• Documentation
  • Added a Compliance section to the README outlining package security and release controls.
  • Added a comprehensive compliance baseline documenting package security, publishing controls, provenance, release procedures, evidence requirements, integrity checks, and CI/release gating for public packages.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ec8be237-2832-465b-ad8f-643477f8cc37

📥 Commits

Reviewing files that changed from the base of the PR and between f1d65de and 4ac704b.

📒 Files selected for processing (2)

• README.md
• docs/compliance/package-security-provenance.md

✅ Files skipped from review due to trivial changes (2)

• README.md
• docs/compliance/package-security-provenance.md

---

📝 Walkthrough

Walkthrough

Adds a new SEC-004 “Package Security and Provenance Baseline” document under docs/compliance and updates the README with a “Compliance” section linking to it; the document defines scope, publishing controls, token handling, provenance targets, integrity and SBOM evidence rules, CI gates, release checklist, known gaps, and verification commands.

Changes

SOC 2 SEC-004 Compliance Baseline

Layer / File(s)	Summary
README Compliance Section README.md	README updated with new "Compliance" section linking to the SEC-004 package security and provenance baseline document.
Scope, Repository Config, and SOC 2 Controls docs/compliance/package-security-provenance.md	Document establishes in-scope packages and artifact boundaries, identifies repository configuration as source of truth, and maps SOC 2 controls (CC6.1/6.7/6.8/7.1/8.1/9.2) to evidence sources.
Release Workflow and Token Handling docs/compliance/package-security-provenance.md	Specifies GitHub Actions release workflow controls including Changesets invocation, operating restrictions on main, required workflow permissions and evidence capture; documents secrets.NPM_TOKEN storage, rotation triggers, and scope review expectations.
Package Integrity Requirements and Evidence Generation docs/compliance/package-security-provenance.md	Sets package integrity expectations (narrow files allowlists, prepack rebuild, npm pack --workspaces tarball creation, lockfile policy); defines SBOM/vulnerability evidence generation commands and storage under artifacts/security; and lists required SEC-004 CI gates and current coverage notes.
Release Checklist, Gaps, and Verification docs/compliance/package-security-provenance.md	Provides per-release evidence checklist with ownership, documents explicit gaps remaining until follow-up work/account evidence is completed, and includes repository-root verification commands and tarball cleanup instructions.

🎯 1 (Trivial) | ⏱️ ~3 minutes

"I hopped through docs with pen and cheer,
A checklist tucked and gaps held clear,
Provenance stitched and tokens named,
Releases traceable, signs framed,
🐇🔐 a tidy trail for every year."

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(soc2): document JS package provenance' accurately summarizes the main changes: adding SOC 2 compliance documentation for package provenance to the devdocsai-js repository.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch WENTZEL_DEV-100-js-package-provenance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Wentzel-DevDocs]

DEV-100 remote CI update

All observed remote checks are green:

• lint: success
• test: success
• bundle-size: success
• CodeRabbit: success

PR remains draft/open for human review, approval, merge, and post-merge main CI confirmation.

[Wentzel-DevDocs]

Ready-for-review handoff:

• Configured checks are green/non-blocking.
• Merge state was reported CLEAN in the GitHub sweep.
• No code changes made during this handoff; this only moves the PR out of draft for human review.
• Do not merge from automation. Do not close the Linear item until a human approves, the PR merges to main, and post-merge main status is verified green.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/compliance/package-security-provenance.md`:
- Line 39: The SOC 2 control ID "C1.1" in the Control Mapping table row "Protect
confidential release credentials and source integrity" is ambiguous; either
confirm it is an intentional custom/supplemental control and add a documented
definition and cross-reference for "C1.1" in the compliance docs, or replace
"C1.1" with the correct SOC 2 CC-series control identifier that matches the
intended control and update any mapping text to reference that CC identifier;
ensure the change is applied to the SOC 2 Control Mapping table row that
contains "Protect confidential release credentials and source integrity" so
auditors can find a clear, documented mapping.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c231a6df-b6c3-44e7-99b8-121d72b66f9d

📥 Commits

Reviewing files that changed from the base of the PR and between 6ccbfdc and f1d65de.

📒 Files selected for processing (2)

• README.md
• docs/compliance/package-security-provenance.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Search for C1.1 control references and documentation in the repo
# to verify this is an established internal control designation

rg -i 'C1\.1|control.*C1\.1' --type=md -C2

Repository: devdocsorg/devdocsai-js

Length of output: 803

---

Clarify SOC 2 control ID C1.1 in package security provenance mapping

C1.1 only appears in the SOC 2 Control Mapping table row in docs/compliance/package-security-provenance.md and has no other matching definitions/references in the repo’s Markdown. Confirm whether C1.1 is an intentional custom/supplemental designation (and document it) or update the mapping to the appropriate CC-series control for audit clarity.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/compliance/package-security-provenance.md` at line 39, The SOC 2 control
ID "C1.1" in the Control Mapping table row "Protect confidential release
credentials and source integrity" is ambiguous; either confirm it is an
intentional custom/supplemental control and add a documented definition and
cross-reference for "C1.1" in the compliance docs, or replace "C1.1" with the
correct SOC 2 CC-series control identifier that matches the intended control and
update any mapping text to reference that CC identifier; ensure the change is
applied to the SOC 2 Control Mapping table row that contains "Protect
confidential release credentials and source integrity" so auditors can find a
clear, documented mapping.