diff --git a/CHANGELOG.md b/CHANGELOG.md index c57881b..90dc7c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.29] - 2026-08-24 + ### Added - **Portable Project Work Contract (draft).** Add the `project-work/v0` @@ -23,6 +25,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Validation coverage.** `make check` now runs the project-work control battery (examples, structural rejects, classifier-key alignment) and the project-work contract manifest. +- **Local fallback guidance.** Use an org-qualified `3leaps/crucible` sibling + clone from the consuming repository and consistent `../crucible/` paths in + onboarding, adoption, and upstream-sync documentation. ## [0.1.28] - 2026-08-20 @@ -964,7 +969,8 @@ PDR, EPR}` — as a shared standard, with a thin mandate (type set + naming) - Getting started guide for multiple user personas (new repo, existing repo, adopting org) - Migration guidance for 3leaps and adopting ecosystems -[unreleased]: https://github.com/3leaps/crucible/compare/v0.1.28...HEAD +[unreleased]: https://github.com/3leaps/crucible/compare/v0.1.29...HEAD +[0.1.29]: https://github.com/3leaps/crucible/compare/v0.1.28...v0.1.29 [0.1.28]: https://github.com/3leaps/crucible/compare/v0.1.27...v0.1.28 [0.1.27]: https://github.com/3leaps/crucible/compare/v0.1.25...v0.1.27 [0.1.25]: https://github.com/3leaps/crucible/compare/v0.1.24...v0.1.25 diff --git a/Makefile b/Makefile index 45a9094..e553f3e 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ # make check - Run all quality checks # make fmt - Format all files -.PHONY: all help bootstrap bootstrap-force tools check test fmt lint lint-schemas lint-config lint-role-prompts lint-coverage-attestation build clean version +.PHONY: all help bootstrap bootstrap-force tools check test fmt fmt-check lint lint-schemas lint-config lint-role-prompts lint-coverage-attestation build clean version # lint-config added as dependency of lint - validates config/*.yaml against schemas .PHONY: version-set version-patch version-minor version-major .PHONY: precommit prepush deps-check @@ -48,10 +48,10 @@ help: ## Show available targets @echo "Required targets:" @echo " help Show this help message" @echo " bootstrap Install tools (sfetch -> goneat -> others)" - @echo " check Run all quality checks (fmt, lint, test)" + @echo " check Run non-mutating quality checks" @echo " test Run release-control negative tests" - @echo " fmt Format code (prettier, yamlfmt)" - @echo " lint Run linting (yamllint, schema validation)" + @echo " fmt Apply the goneat assessment policy" + @echo " lint Run goneat lint and schema validation" @echo " lint-schemas Validate JSON Schema files against meta-schema" @echo " build Build artifacts (validation is the build)" @echo " clean Remove build artifacts" @@ -185,33 +185,13 @@ tools: ## Verify external tools are available else \ echo "[!!] goneat not found - run 'make bootstrap'"; \ fi - @# Check prettier (via bun) - @if [ -x "./node_modules/.bin/prettier" ]; then \ - echo "[ok] prettier: $$(./node_modules/.bin/prettier --version) (bun)"; \ - elif command -v prettier >/dev/null 2>&1; then \ - echo "[ok] prettier: $$(prettier --version)"; \ - else \ - echo "[!!] prettier not found"; \ - fi - @# Check yamlfmt - @if command -v yamlfmt >/dev/null 2>&1; then \ - echo "[ok] yamlfmt: $$(yamlfmt --version 2>&1 | head -n1)"; \ - else \ - echo "[!!] yamlfmt not found"; \ - fi - @# Check yamllint - @if command -v yamllint >/dev/null 2>&1; then \ - echo "[ok] yamllint found"; \ - else \ - echo "[!!] yamllint not found"; \ - fi @echo "" # ----------------------------------------------------------------------------- # Quality Gates # ----------------------------------------------------------------------------- -check: fmt lint test ## Run all quality checks +check: fmt-check lint test ## Run all quality checks without modifying files @echo "[ok] All quality checks passed" test: ## Run release-control negative tests @@ -219,44 +199,34 @@ test: ## Run release-control negative tests @./scripts/test-release-guard-release-surfaces.sh @./scripts/release-guard-release-surfaces.sh -fmt: ## Format code (prettier for md/json, yamlfmt for yaml, shfmt for shell) +fmt: ## Format files using the repository goneat assessment policy @echo "Formatting..." - @# Format markdown and JSON with prettier (prefer bun-installed) - @if [ -x "./node_modules/.bin/prettier" ]; then \ - echo "[..] Formatting markdown and JSON (prettier via bun)..."; \ - ./node_modules/.bin/prettier --write "**/*.md" "**/*.json" --ignore-path .gitignore 2>/dev/null || true; \ - elif command -v prettier >/dev/null 2>&1; then \ - echo "[..] Formatting markdown and JSON (prettier system)..."; \ - prettier --write "**/*.md" "**/*.json" --ignore-path .gitignore 2>/dev/null || true; \ - else \ - echo "[!!] prettier not found, skipping md/json formatting"; \ - fi - @# Format YAML with yamlfmt - @if command -v yamlfmt >/dev/null 2>&1; then \ - echo "[..] Formatting YAML (yamlfmt)..."; \ - yamlfmt . 2>/dev/null || true; \ + @if command -v goneat >/dev/null 2>&1; then \ + goneat assess --categories format --fix --fail-on low --ci-summary; \ + goneat assess --categories lint --fix --lint-shell-fix --fail-on low --ci-summary; \ else \ - echo "[!!] yamlfmt not found, skipping YAML formatting"; \ + echo "[!!] goneat not found; run make bootstrap"; \ + exit 1; \ fi - @# Format shell scripts with shfmt. - @# Args must match .goneat/assess.yaml lint.shell.shfmt.args and .editorconfig [*.sh] - @# (goneat checks shell under the lint category; make fmt is the apply path). - @if command -v shfmt >/dev/null 2>&1; then \ - echo "[..] Formatting shell scripts (shfmt -i 4 -ci)..."; \ - shfmt -i 4 -ci -w scripts/*.sh; \ + @echo "[ok] Formatting complete" + +fmt-check: ## Verify canonical formatting without modifying files + @echo "Checking formatting..." + @if command -v goneat >/dev/null 2>&1; then \ + goneat assess --categories format --mode check --fail-on low --ci-summary; \ else \ - echo "[!!] shfmt not found, skipping shell formatting"; \ + echo "[!!] goneat not found, cannot verify formatting"; \ + exit 1; \ fi - @echo "[ok] Formatting complete" + @echo "[ok] Formatting checks passed" lint: lint-schemas lint-config ## Run linting checks @echo "Linting..." - @# Lint YAML with yamllint - @if command -v yamllint >/dev/null 2>&1; then \ - echo "[..] Linting YAML (yamllint)..."; \ - yamllint -c .yamllint . 2>&1 | grep -v "^$$" || true; \ + @if command -v goneat >/dev/null 2>&1; then \ + goneat assess --categories lint --mode check --fail-on low --ci-summary; \ else \ - echo "[!!] yamllint not found, skipping YAML linting"; \ + echo "[!!] goneat not found, cannot run lint assessment"; \ + exit 1; \ fi @echo "[ok] Linting complete" @@ -385,7 +355,7 @@ lint-coverage-attestation: ## Run coverage-attestation negative controls echo "[--] goneat not found, skipping coverage-attestation controls"; \ fi -build: ## Build artifacts (validation is the build for standards repo) +build: check ## Build artifacts (validation is the build for standards repo) @echo "Building..." @echo "[ok] Build complete (crucible is docs - validation is the build)" @@ -417,10 +387,10 @@ clean: ## Remove build artifacts precommit: ## Run pre-commit checks (goneat assess --fail-on critical + schema validation) @echo "Running pre-commit checks..." @if command -v goneat >/dev/null 2>&1; then \ - PATH="$(CURDIR)/node_modules/.bin:$$PATH" goneat assess --categories format,lint,security --fail-on critical --ci-summary; \ + goneat assess --categories format,lint,security --mode check --fail-on critical --ci-summary; \ else \ - echo "[!!] goneat not found, falling back to basic checks"; \ - $(MAKE) fmt lint; \ + echo "[!!] goneat not found; run make bootstrap"; \ + exit 1; \ fi @# Always run schema/config validation (goneat assess doesn't cover these) @$(MAKE) lint-schemas lint-config @@ -429,10 +399,10 @@ precommit: ## Run pre-commit checks (goneat assess --fail-on critical + schema v prepush: ## Run pre-push checks (goneat assess --fail-on low + schema validation) @echo "Running pre-push checks..." @if command -v goneat >/dev/null 2>&1; then \ - PATH="$(CURDIR)/node_modules/.bin:$$PATH" goneat assess --categories format,lint,security --fail-on low --ci-summary; \ + goneat assess --categories format,lint,security --mode check --fail-on low --ci-summary; \ else \ - echo "[!!] goneat not found, falling back to basic checks"; \ - $(MAKE) fmt lint; \ + echo "[!!] goneat not found; run make bootstrap"; \ + exit 1; \ fi @# Always run schema/config validation (goneat assess doesn't cover these) @$(MAKE) lint-schemas lint-config diff --git a/README.md b/README.md index 9af81db..d54f678 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 3leaps Crucible -![Version: 0.1.28](https://img.shields.io/badge/version-0.1.28-blue) +![Version: 0.1.29](https://img.shields.io/badge/version-0.1.29-blue) ![Lifecycle: Beta](https://img.shields.io/badge/lifecycle-beta-blue) ![License: MIT + CC0](https://img.shields.io/badge/license-MIT%20%2B%20CC0-blue) ![Check](https://github.com/3leaps/crucible/actions/workflows/check.yml/badge.svg) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 530aaed..2599472 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -8,6 +8,29 @@ For detailed release content, see [docs/releases/](docs/releases/). --- +## v0.1.29 (2026-08-24) + +**A portable project-work contract for exchanging ready work and project +projections, with executable controls and clearer local adoption guidance.** + +- **Portable project-work family** — `project-work/v0` defines source-neutral + ready packets, project state, control records, and progress events without + importing a board or runtime. +- **Explicit lifecycle and governance boundaries** — the draft contract + distinguishes work readiness from lifecycle class, uses typed subjects for + durable records, and keeps decision impact explicit through decision-owned + `affects` references. +- **Executable contract coverage** — positive examples, structural rejects, + classifier-key alignment checks, and the project-work manifest run through + the repository quality gates. +- **Org-qualified local fallback** — onboarding and adoption documentation now + clones `3leaps/crucible` as `../crucible/` from the consuming repository and + uses that path consistently in upstream-sync examples. + +See [docs/releases/v0.1.29.md](docs/releases/v0.1.29.md). + +--- + ## v0.1.28 (2026-08-20) **A bounded, cooperative presentation-priority hint for portable agent-wait diff --git a/VERSION b/VERSION index baec65a..5ef49d2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.28 +0.1.29 diff --git a/docs/releases/v0.1.29.md b/docs/releases/v0.1.29.md new file mode 100644 index 0000000..2831167 --- /dev/null +++ b/docs/releases/v0.1.29.md @@ -0,0 +1,72 @@ +# Release v0.1.29 + +**A portable project-work contract for exchanging ready work and project +projections, with executable controls and clearer local adoption guidance.** + +## Overview + +v0.1.29 adds the draft `project-work/v0` contract family. It provides +source-neutral JSON structures for moving ready work into execution, publishing +project projections, recording durable decisions and blockers, and emitting +ordered progress events. The contract does not import a board, workflow engine, +or runtime. + +This release also makes the local fallback instructions unambiguous: consumers +clone the org-qualified `3leaps/crucible` repository as a sibling and reference +it consistently through `../crucible/`. + +## Highlights + +### Portable project-work family + +The family contains four discriminated document types: + +- `ready-packet` carries bounded, execution-ready work and assignment state. +- `project-state` publishes a source projection with milestones and lifecycle + summaries. +- `control-record` records typed status, decision, and blocker statements. +- `progress-event` provides ordered, source-neutral lifecycle events. + +An entry manifest and family README expose the contract surfaces to consumers. +The accompanying standard documents the exchange model, frozen vocabulary, and +boundary between portable records and source-specific overlays. + +### Explicit lifecycle and governance boundaries + +Ready packets distinguish readiness from lifecycle class and use classifier +keys aligned with the public catalog. Control records use typed subjects; +decision records require non-empty, unique `affects` references, while status +and blocker records cannot claim decision impact. Milestone targets use full +calendar dates. + +### Executable contract coverage + +Positive examples cover every document type. Focused rejects exercise invalid +assignment, lifecycle, subject, transition, decision-impact, and milestone-date +shapes. The project-work control battery also checks classifier-key alignment, +and the contract manifest participates in repository validation. + +### Consistent local adoption guidance + +The README, getting-started guide, agentic adoption guide, and upstream-sync +guide now direct consumers to clone `https://github.com/3leaps/crucible.git` as +`../crucible/`. Copy and comparison examples use paths relative to the +consuming repository instead of assuming a machine-specific development root. + +## Compatibility + +`project-work/v0` is a new draft contract family and does not change existing +contract families. Consumers should pin the repository revision they adopt +while the family remains at `v0`. + +The documentation changes clarify the existing sibling-clone fallback. They do +not change the canonical GitHub source or require consumers to vendor guidance +that they only reference. + +## References + +- [CHANGELOG](../../CHANGELOG.md) +- [Project-work contract](../standards/project-work-contract.md) +- [Project-work v0 schema family](../../schemas/project-work/v0/) +- [Getting started](../getting-started.md) +- [Upstream sync guide](../operations/upstream-sync-guide.md) diff --git a/package.json b/package.json index 76678b4..9484569 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@3leaps/crucible", - "version": "0.1.28", + "version": "0.1.29", "private": true, "description": "Lightweight standards and specifications for 3leaps open source projects", "type": "module",