Spec: CLI Update Enforcement

User Input

we are now to define an enforcement of the updating flow.

Currenlty we have a dp update command, gh releases and npm cli releases. also a changelog that notifies users.

id like us to make the .devpunks folder have a cliVersion and baselineVersion tags to be created.

cliVersion would change upon using cli

baselineVersion upon any writing of the scaffolding content (scaffold, update, any of those flows)

these version pins should then be used in a onSessionStart hook that runs a new dp command: check (or smth? you pick) that will highlight if our cli and baseline are drifting apart from latest. command guidance and dp-cli skill should provide knowledge about this command such as that if drift is detected it should warn the user about it, provide a summary of the related changelog so to explain the update content, and prompt for update before starting to work. the updating flow IS MANDATORY to be run in a subagent in case its accepted, so to not pollute main thread

Additional accepted direction: user accepted all open branches and asked to "close 100% everything", then requested delivery from spec through closeout without backlog creation.

Context

Harness projects already receive scaffolded guidance, hooks, skills, and changelog-backed release information through the dp CLI. The missing enforcement is a project-local memory of which CLI version and scaffold baseline version the project last accepted, plus a session-start check that warns operators before work begins when either side has drifted from latest.

This capability is for AI operators and maintainers using scaffolded Devpunks repos. It must make drift visible early, explain what changed, and keep update execution out of the main working thread when the user accepts remediation.

Acceptance Criteria

• .devpunks/settings.json persists cliVersion and baselineVersion fields for scaffolded projects.
• cliVersion updates when a dp CLI command is accepted as the current local command authority for the project.
• baselineVersion updates whenever scaffold-managed content is written by scaffold/setup/update flows.
• A new dp check command runs without writing scaffold-managed files.
• dp check detects installed CLI drift from the latest available CLI release.
• dp check detects scaffold baseline drift from the latest available baseline release.
• Drift output warns before work starts and separates CLI drift from baseline drift.
• Drift output summarizes relevant changelog content for the detected CLI and baseline drift.
• Drift output prompts the operator to run the appropriate upgrade/update flow before relying on scaffolded guidance.
• Session-start hook wiring calls dp check instead of raw dp update --check.
• Command guidance and the dp-cli skill document dp check, its drift warning behavior, changelog summary, and the rule that accepted remediation must run in a subagent.
• Existing dp update behavior remains available and continues to own scaffold writes.
• Existing CLI release and baseline release flows remain compatible with the new pins and check output.

Non-Goals

• No backlog creation for this delivery.
• No replacement of dp update with dp check.
• No automatic update execution from session-start without user acceptance.
• No remediation in the main thread after a user accepts drift guidance.
• No change to CLI package identity; commands remain punks and dp, package remains @punks/cli.

Constraints

• Shared dp-cli skill edits must be made first in /Users/stefan/Desktop/repos/wearedevpunks-skills, then synced into Harness with bun run sync:skills.
• Operator workflow, hook, and scaffold behavior changes must update docs/README.md, docs/runbooks/dp-cli-scaffolding.md, and relevant wiki/runbook mirrors.
• Changelog summaries must draw from Harness release notes: CHANGELOG.md for CLI releases and BASELINE_CHANGELOG.md for baseline-specific detail when applicable.
• Update remediation accepted from session-start guidance must be assigned to a subagent.

Review Status

Human-approved via closed requirements grill on 2026-06-30. Source: apps/wiki/content/docs/project/grilling/cli-update-enforcement-grill-status.md.

Open Questions

None.

Decision Log