agentic-dev/_story.md at 90fc2853f286a60d1c9a594f0a13fe8ad56664e1

Template

Files

Danijel Martinek 90fc2853f2 feat(work): add ISO timestamps + auto-bump on staged work-doc changes

- New scripts/work/bump-updated-timestamps.mjs stamps the `updated:`
  frontmatter field to the current ISO 8601 UTC timestamp on every
  staged docs/work/**/*.md file. Idempotent; adds the field after
  `created:` if missing.
- .husky/pre-commit invokes the bump script as step 2 (before
  rebuild-state) so _state.json sees the fresh timestamp.
- Backfill all existing work docs (4 PRDs + 3 epics + 21 stories):
    * created: promoted from \`YYYY-MM-DD\` -> ISO timestamp using
      git log --diff-filter=A on each file (first-commit date for
      stories that had no \`created:\` line, midnight UTC for PRDs
      and epics that had date-only created).
    * updated: added from \`git log -1 --format=%aI\` on each file
      (last-commit timestamp); will be re-stamped to "now" by the
      pre-commit hook on this commit.

Stories that had no \`created:\` line now get one.

2026-05-14 21:10:34 +02:00

3.8 KiB

Raw Blame History

id, epic, title, type, status, feature, depends-on, blocks, created, updated

epic

title

type

status

feature

depends-on

blocks

created

updated

09-ci-security-guide-and-docs

2026-05-14-ci-security-and-supply-chain

CI security guide + CLAUDE.md

technical-story

done

docs

01-trace-schema-extensions

02-socket-integration

03-renovate-adoption

04-major-bump-reevaluation

05-trace-revalidation-workflow

06-codeql-and-audit-signatures

07-gitleaks-precommit

08-reviewer-prompt-update

2026-05-14T18:59:12+02:00

2026-05-14T19:10:35.370Z

Goal

Write docs/guides/ci-security.md — the human reading-room for the four-pillar stack — and add a Key Conventions bullet to CLAUDE.md pointing agents and developers to ADR-023 + the guide.

Why

Each prior story lands a machine-enforced layer, but no single document explains the composed system to a developer or consumer who hasn't read all nine stories. docs/guides/ci-security.md fills that gap: it explains the four pillars, the failure-mode hierarchy, what settings are consumer-toggleable, and gives two worked examples so the mental model is concrete. The CLAUDE.md bullet ensures the enforcement stack is discoverable during every agent session via the startup context.

Done when

docs/guides/ci-security.md exists and covers:
- Overview of the four pillars (Renovate + Action SHA pinning, Socket, trace revalidation, GitHub-native gates).
- Per-pillar section with what the gate does, what it catches, and how to toggle it in a downstream consumer repo.
- Failure-mode hierarchy table (mirroring ADR-023 §5): pillar, trigger condition, action, label, who resolves.
- Consumer-toggleable settings list: GitHub native push protection, Socket GitHub App install, branch protection rules requiring library-policy/*-labeled checks before merge.
- Two worked examples: (a) a passing Renovate minor-bump PR (gates pass, auto-merges); (b) a blocked major-bump PR (Renovate opens PR → check.mjs requires lastRevalidated refresh → agent re-walks evaluate-library → trace updated → PR unblocked) + a hard-divergence revalidation issue (weekly cron finds Socket-flagged dep → per-dep library-policy/re-evaluation issue opened → agent closes issue after re-walk).
- Socket GitHub App install instructions for consumers.
- gitleaks installation instructions for developers (OS package manager / brew; hook exits gracefully if binary absent).
- Note that CodeQL requires GitHub Advanced Security on private repos.
CLAUDE.md Key Conventions section has a bullet: "CI security + supply-chain enforcement: Renovate for bumps + Action SHA pinning, Socket for supply-chain behavior, weekly trace revalidation, CodeQL + audit signatures + gitleaks. See ADR-023 + docs/guides/ci-security.md."
pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff all pass (docs + CLAUDE.md; no executable code).

In scope

docs/guides/ci-security.md — new guide file.
CLAUDE.md — one bullet addition to Key Conventions.

Out of scope

Configuring GitHub branch protection rules — documented as consumer action, not a tracked file change.
Installing the Socket GitHub App — documented as consumer action in the guide; no config file change.
Backfilling existing traces with last-revalidated — handled by the first revalidation cron run (Story 05).

Tasks

Write docs/guides/ci-security.md with: four-pillar overview, per-pillar sections, failure-mode hierarchy table (ADR-023 §5), consumer-toggleable settings list, Socket GitHub App + gitleaks install instructions, CodeQL note for private repos, two worked examples (passing minor-bump PR; blocked major-bump PR + hard-divergence revalidation issue); one commit, all gates pass.
Add CI security Key Conventions bullet to CLAUDE.md referencing ADR-023 + docs/guides/ci-security.md; one commit, all gates pass.

3.8 KiB Raw Blame History