Skip to content

Commit febca14

Browse files
SmartBrandStrategiesstackbilt-adminclaude
authored
feat: ADF metrics recalibration, CI hardening, and release workflow (#1)
* chore(misc): apply maintenance updates * docs(repo): update project documentation * feat(cli): apply logical updates * chore(misc): apply maintenance updates * chore(misc): apply maintenance updates * chore(repo): update repository configuration * docs(readme): add npm version badge Shows live release version from npm instead of stale GitHub Releases tag. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * ci(release): add workflow for tag-based GitHub releases Supports both automatic releases on v* tag push and manual workflow_dispatch backfill for historical tags. Extracts release notes from CHANGELOG.md automatically. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs(readme): remove ADF architecture image and update SDLC status Remove large ADF_1.png embed and update callout to reflect completion of the inaugural SDLC cycle with ongoing iterative improvement. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(ci): remove explicit pnpm version to resolve action-setup conflict pnpm/action-setup@v4 now errors when both `version` param and package.json `packageManager` field are set. Let the action auto-detect from packageManager instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(ci): reorder build before typecheck, add pnpm support to governance - CI: move `build` before `typecheck` so cross-package .d.ts files exist when tsc --noEmit runs against the root tsconfig. - Governance: detect pnpm-lock.yaml and use pnpm install when present, fixing workspace:^ protocol failures in this repo. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(ci): guard docs:check and drift scan on required files - CI: skip docs:check when .docsync.json is absent - charter-governance: skip drift scan when no pattern files exist, matching the guard already present in governance.yml Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Kurt Overmier <admin@stackbilt.dev> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 7f63324 commit febca14

16 files changed

Lines changed: 566 additions & 19 deletions

File tree

.ai/.adf.lock

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"core.adf": "74a53c306c131c1c"
2+
"core.adf": "9ea44032a909ed99"
33
}

.ai/core.adf

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ ADF: 0.1
2727
adf_commands_loc: 0 / 650 [lines]
2828
adf_bundle_loc: 0 / 200 [lines]
2929
adf_sync_loc: 0 / 250 [lines]
30-
adf_evidence_loc: 0 / 300 [lines]
30+
adf_evidence_loc: 0 / 380 [lines]
3131
adf_migrate_loc: 0 / 500 [lines]
3232
bundler_loc: 0 / 500 [lines]
3333
parser_loc: 0 / 300 [lines]

.github/workflows/charter-governance.yml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,6 @@ jobs:
1919
fetch-depth: 0
2020

2121
- uses: pnpm/action-setup@v4
22-
with:
23-
version: 9
2422

2523
- uses: actions/setup-node@v4
2624
with:
@@ -35,6 +33,7 @@ jobs:
3533

3634
- name: Drift Scan
3735
run: npx charter drift --ci --format text
36+
if: hashFiles('.charter/patterns/*.json') != ''
3837

3938
- name: ADF Wiring & Pointer Integrity
4039
run: npx charter doctor --adf-only --ci --format text

.github/workflows/ci.yml

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,17 @@ jobs:
1212
steps:
1313
- uses: actions/checkout@v4
1414
- uses: pnpm/action-setup@v4
15-
with:
16-
version: 9
1715
- uses: actions/setup-node@v4
1816
with:
1917
node-version: '20'
2018
cache: 'pnpm'
2119
- run: pnpm install --frozen-lockfile
20+
- run: pnpm run build
2221
- run: pnpm run typecheck
23-
- run: pnpm run build
24-
- run: pnpm run docs:check
25-
- run: pnpm run verify:adf
26-
- run: pnpm run test
27-
- run: node packages/cli/dist/bin.js --help
22+
- name: Docs sync check
23+
run: pnpm run docs:check
24+
if: hashFiles('.docsync.json') != ''
25+
- run: pnpm run verify:adf
26+
- run: pnpm run test
27+
- run: node packages/cli/dist/bin.js --help
2828

.github/workflows/governance.yml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,19 @@ jobs:
3030
with:
3131
fetch-depth: 0 # Full history needed for commit analysis
3232

33+
- uses: pnpm/action-setup@v4
34+
if: hashFiles('pnpm-lock.yaml') != ''
35+
3336
- uses: actions/setup-node@v4
3437
with:
3538
node-version: '20'
39+
cache: ${{ hashFiles('pnpm-lock.yaml') != '' && 'pnpm' || hashFiles('package-lock.json') != '' && 'npm' || '' }}
3640

3741
- name: Install dependencies
3842
run: |
39-
if [ -f package-lock.json ]; then
43+
if [ -f pnpm-lock.yaml ]; then
44+
pnpm install --frozen-lockfile
45+
elif [ -f package-lock.json ]; then
4046
npm ci
4147
else
4248
npm install

.github/workflows/release.yml

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
workflow_dispatch:
8+
inputs:
9+
tag:
10+
description: 'Existing tag to publish (for backfill), e.g. v0.4.2'
11+
required: true
12+
type: string
13+
14+
permissions:
15+
contents: write
16+
17+
jobs:
18+
publish-release:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
with:
23+
fetch-depth: 0
24+
25+
- name: Resolve tag
26+
id: tag
27+
shell: bash
28+
run: |
29+
if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
30+
TAG="${{ inputs.tag }}"
31+
else
32+
TAG="${GITHUB_REF_NAME}"
33+
fi
34+
35+
if [[ -z "${TAG}" ]]; then
36+
echo "Tag could not be resolved." >&2
37+
exit 1
38+
fi
39+
40+
echo "value=${TAG}" >> "$GITHUB_OUTPUT"
41+
42+
- name: Verify tag
43+
shell: bash
44+
run: |
45+
TAG="${{ steps.tag.outputs.value }}"
46+
if [[ ! "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
47+
echo "Invalid tag format: ${TAG}. Expected v<major>.<minor>.<patch>" >&2
48+
exit 1
49+
fi
50+
51+
if [[ "${GITHUB_EVENT_NAME}" == "push" ]]; then
52+
PKG_VERSION="$(node -p "require('./packages/cli/package.json').version")"
53+
EXPECTED_TAG="v${PKG_VERSION}"
54+
55+
if [[ "${TAG}" != "${EXPECTED_TAG}" ]]; then
56+
echo "Tag/version mismatch on push: got ${TAG}, expected ${EXPECTED_TAG}" >&2
57+
exit 1
58+
fi
59+
else
60+
if ! git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
61+
echo "Tag not found in repository: ${TAG}" >&2
62+
exit 1
63+
fi
64+
fi
65+
66+
- name: Build release notes from CHANGELOG
67+
shell: bash
68+
run: |
69+
TAG="${{ steps.tag.outputs.value }}"
70+
VERSION="${TAG#v}"
71+
72+
awk -v version="${VERSION}" '
73+
BEGIN { in_section=0 }
74+
$0 ~ "^## \\[" version "\\]" { in_section=1; print; next }
75+
in_section && $0 ~ "^## \\[" { exit }
76+
in_section { print }
77+
' CHANGELOG.md > release_notes.md
78+
79+
if [[ ! -s release_notes.md ]]; then
80+
echo "## ${TAG}" > release_notes.md
81+
echo >> release_notes.md
82+
echo "See CHANGELOG.md for release details." >> release_notes.md
83+
fi
84+
85+
- name: Create or update GitHub Release
86+
uses: softprops/action-gh-release@v2
87+
with:
88+
tag_name: ${{ steps.tag.outputs.value }}
89+
name: ${{ steps.tag.outputs.value }}
90+
body_path: release_notes.md
91+
generate_release_notes: true

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,6 @@ AGENTS.md
1313
CLAUDE.md
1414
plans/
1515
governance/
16+
17+
# local telemetry artifacts
18+
.charter/telemetry/

CHANGELOG.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,15 @@ All notable changes to this project are documented in this file.
44

55
The format is based on Keep a Changelog and follows Semantic Versioning.
66

7+
## [Unreleased]
8+
9+
### Added
10+
- **`charter adf metrics recalibrate`**: New subcommand to re-measure LOC from manifest metric sources, propose new ceilings with configurable headroom, and update metric baselines/ceilings with required rationale (`--reason` or `--auto-rationale`).
11+
- **Budget rationale trail**: Recalibration writes `BUDGET_RATIONALES` map entries so metric-cap changes carry explicit context for later review.
12+
13+
### Changed
14+
- **Stale baseline detection in evidence**: `charter adf evidence` now detects stale metric baselines (current vs baseline drift), emits structured `staleBaselines` warnings (baseline/current/delta/recommendedCeiling/rationaleRequired), and suggests recalibration actions.
15+
716
## [0.4.2] - 2026-02-27
817

918
### Added

README.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
# Charter Kit
22

3+
[![npm version](https://img.shields.io/npm/v/@stackbilt/cli?label=charter&color=5F7FFF&style=for-the-badge)](https://www.npmjs.com/package/@stackbilt/cli)
4+
35
![Charter Kit hero](./stackbilt-charter-2.png)
46

5-
> **ADF is currently running its inaugural full-SDLC cycle to gather real-world data for iterative improvement. Updates coming soon and regularly.**
7+
> **ADF has completed its inaugural full-SDLC cycle and is now in iterative improvement. Expect frequent updates as real-world feedback shapes the format.**
68
79
Charter is a local-first governance toolkit with a built-in AI context compiler. It ships **ADF (Attention-Directed Format)** -- a modular, AST-backed context system that replaces monolithic `.cursorrules` and `claude.md` files -- alongside offline governance checks for commit trailers, risk scoring, drift detection, and change classification.
810

9-
![ADF Architecture](./ADF_1.png)
10-
1111
## ADF: Attention-Directed Format
1212

1313
ADF treats LLM context as a compiled language. Instead of dumping flat markdown into a context window, ADF uses emoji-decorated semantic keys, a strict AST, and a module system with progressive disclosure -- so agents load only the context they need for the current task.
@@ -46,6 +46,7 @@ charter adf sync --check
4646

4747
# Validate metric constraints and produce a structured evidence report
4848
charter adf evidence --auto-measure --format json
49+
charter adf metrics recalibrate --headroom 15 --reason "Added new built modules after scope expansion" --dry-run
4950
charter telemetry report --period 24h --format json
5051
```
5152

@@ -225,6 +226,7 @@ Teams often score lower early due to missing governance trailers. Use this ramp:
225226
- `charter adf sync --check [--ai-dir <dir>]`: verify source .adf files match locked hashes (exit 1 on drift)
226227
- `charter adf sync --write [--ai-dir <dir>]`: update `.adf.lock` with current source hashes
227228
- `charter adf evidence [--task "<prompt>"] [--ai-dir <dir>] [--auto-measure] [--context '{"k":v}'] [--context-file <path>]`: validate metric constraints and produce structured evidence report
229+
- `charter adf metrics recalibrate [--headroom <percent>] [--reason "<text>"|--auto-rationale] [--dry-run]`: recalibrate metric baselines/ceilings from current LOC and record budget rationale
228230
- `charter adf migrate [--dry-run] [--source <file>] [--no-backup] [--merge-strategy append|dedupe|replace]`: ingest existing agent config files and migrate content into ADF modules
229231
- `charter telemetry report [--period <30m|24h|7d>]`: summarize passive local CLI telemetry from `.charter/telemetry/events.ndjson`
230232
- `charter why`: explain adoption rationale and expected payoff

docs-snippets/charter-cli-reference.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,19 @@ npx charter adf evidence --context-file metrics.json
195195
**CI mode:** exits 1 on any constraint failure. Warnings (at boundary) surface in the report but do not fail the build.
196196

197197
Output includes constraint results, weight summary (load-bearing / advisory / unweighted), sync status, advisory-only warnings, and a `nextActions` array.
198+
When stale baselines are detected, JSON output includes `staleBaselines` entries with `baseline`, `current`, `delta`, `recommendedCeiling`, and `rationaleRequired`.
199+
200+
### charter adf metrics recalibrate
201+
202+
Re-measures LOC from manifest metric sources and recalibrates metric values/ceilings using a configurable headroom policy.
203+
204+
```bash
205+
npx charter adf metrics recalibrate --headroom 15 --reason "Added new built modules after scope increase" --dry-run
206+
npx charter adf metrics recalibrate --headroom 20 --auto-rationale
207+
```
208+
209+
- Writes metric rationale entries into a `BUDGET_RATIONALES` section.
210+
- `--reason` (or `--auto-rationale`) is required for recalibration updates.
198211

199212
### ADF Automation Gate
200213

0 commit comments

Comments
 (0)