chore(release): prepare v0.1.29

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

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,78 +185,48 @@ 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
 	@./scripts/test-release-guard-tag-ruleset.sh
 	@./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

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)

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

VERSION

@@ -1 +1 @@
-0.1.28
+0.1.29

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)

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",