@aperant/framework 0.7.3 → 0.7.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +25 -0
- package/package.json +133 -133
- package/skills/apt-pr-review/SKILL.md +8 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,31 @@ All notable changes to `@aperant/framework` are documented here. See
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## 0.7.4 — 2026-05-18 — apt-pr-review context-budget skip prohibition
|
|
9
|
+
|
|
10
|
+
Docs-only patch release hardening the `apt-pr-review` "Fix Everything" contract against a live failure pattern where an orchestrator dropped confirmed minor findings mid-Phase-6 because its own context window felt heavy ("my orchestrator window was getting heavy after 6 specialist rounds + Round 1 work"). Pre-existing rule 5 in §Context Budget Rules already forbade skipping *phases*; this release closes the per-finding gap inside Phase 6.
|
|
11
|
+
|
|
12
|
+
### apt-pr-review SKILL.md
|
|
13
|
+
|
|
14
|
+
Three reading depths now carry the prohibition:
|
|
15
|
+
|
|
16
|
+
- **§Principle: Fix Everything (Phase 6)** — new "Hard rule" paragraph. Orchestrator context pressure, "many fixes already done," and marginal-value judgment are explicitly NOT valid skip reasons. Reminds the orchestrator that fix work runs in fixer windows, so orchestrator pressure does not justify cutting fixer inputs.
|
|
17
|
+
- **§Key Principles → 2. Fix Everything Found** — invalid-reason list extended to include "my context window is heavy" / "I've already done a lot this run."
|
|
18
|
+
- **§Common Mistakes → new 7a (Dropping Findings Because Orchestrator Context Feels Heavy)** — names the failure pattern verbatim, labels it an unauthorized policy deviation, prescribes spawning fixers in smallest batches possible (and filing a framework bug) rather than shipping a partial fix.
|
|
19
|
+
|
|
20
|
+
Only valid skip authorities remain the three in Key Principle #2: `fixable: false`, critical finding without user approval, file assigned to another fixer.
|
|
21
|
+
|
|
22
|
+
### Version
|
|
23
|
+
|
|
24
|
+
- `packages/framework/package.json`: 0.7.3 → 0.7.4
|
|
25
|
+
- `cli-baseline-version.txt` fixture bumped
|
|
26
|
+
|
|
27
|
+
### Commits
|
|
28
|
+
|
|
29
|
+
- chore(framework): forbid context-budget skips in apt-pr-review (a1eb033d)
|
|
30
|
+
- docs(framework): changelog entry for pr-review context-budget skip fix (43c98286)
|
|
31
|
+
- (this one) — chore(framework): 0.7.4 — apt-pr-review context-budget skip prohibition
|
|
32
|
+
|
|
8
33
|
## 0.7.3 — 2026-05-17 — C56 roadmap reconciliation + operator-blocked notes
|
|
9
34
|
|
|
10
35
|
Docs-only patch release reconciling the roadmap with reality. No code changes.
|
package/package.json
CHANGED
|
@@ -1,134 +1,134 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
}
|
|
2
|
+
"name": "@aperant/framework",
|
|
3
|
+
"version": "0.7.4",
|
|
4
|
+
"description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
|
|
5
|
+
"author": "Mikalsen AI <hello@mikalsen.ai>",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"bin": {
|
|
10
|
+
"framework": "./bin/apt-tools.mjs",
|
|
11
|
+
"apt-tools": "./bin/apt-tools.mjs",
|
|
12
|
+
"apt-proof-video": "./bin/apt-proof-video.mjs"
|
|
13
|
+
},
|
|
14
|
+
"exports": {
|
|
15
|
+
".": {
|
|
16
|
+
"types": "./dist/index.d.ts",
|
|
17
|
+
"import": "./dist/index.js"
|
|
18
|
+
},
|
|
19
|
+
"./types": {
|
|
20
|
+
"types": "./dist/types/index.d.ts",
|
|
21
|
+
"import": "./dist/types/index.js"
|
|
22
|
+
},
|
|
23
|
+
"./cost": {
|
|
24
|
+
"types": "./dist/cost/index.d.ts",
|
|
25
|
+
"import": "./dist/cost/index.js"
|
|
26
|
+
},
|
|
27
|
+
"./mappers": {
|
|
28
|
+
"types": "./dist/mappers/index.d.ts",
|
|
29
|
+
"import": "./dist/mappers/index.js"
|
|
30
|
+
},
|
|
31
|
+
"./schemas": {
|
|
32
|
+
"types": "./dist/schemas/index.d.ts",
|
|
33
|
+
"import": "./dist/schemas/index.js"
|
|
34
|
+
},
|
|
35
|
+
"./standalone": {
|
|
36
|
+
"types": "./dist/standalone/index.d.ts",
|
|
37
|
+
"import": "./dist/standalone/index.js"
|
|
38
|
+
},
|
|
39
|
+
"./coordination/event-schema": {
|
|
40
|
+
"types": "./src/cli/coordination/event-schema.d.ts",
|
|
41
|
+
"import": "./src/cli/coordination/event-schema.mjs"
|
|
42
|
+
},
|
|
43
|
+
"./roadmap/conductor-view": {
|
|
44
|
+
"types": "./src/cli/roadmap/conductor-view.d.ts",
|
|
45
|
+
"import": "./src/cli/roadmap/conductor-view.mjs"
|
|
46
|
+
},
|
|
47
|
+
"./design/scan": {
|
|
48
|
+
"import": "./src/cli/design/scan.mjs"
|
|
49
|
+
},
|
|
50
|
+
"./design/extract-repo": {
|
|
51
|
+
"import": "./src/cli/design/extract-repo.mjs"
|
|
52
|
+
},
|
|
53
|
+
"./design/synthesize": {
|
|
54
|
+
"import": "./src/cli/design/synthesize.mjs"
|
|
55
|
+
}
|
|
56
|
+
},
|
|
57
|
+
"files": [
|
|
58
|
+
"dist/",
|
|
59
|
+
"bin/",
|
|
60
|
+
"src/cli/",
|
|
61
|
+
"src/cost/",
|
|
62
|
+
"commands/",
|
|
63
|
+
"skills/",
|
|
64
|
+
"agents/",
|
|
65
|
+
"prompts/",
|
|
66
|
+
"templates/",
|
|
67
|
+
"context/",
|
|
68
|
+
"workflows/",
|
|
69
|
+
"examples/",
|
|
70
|
+
"LICENSE",
|
|
71
|
+
"README.md",
|
|
72
|
+
"CHANGELOG.md",
|
|
73
|
+
"!**/__tests__/**",
|
|
74
|
+
"!**/*.test.*",
|
|
75
|
+
"!**/*.spec.*",
|
|
76
|
+
"!**/*.test.d.ts.map",
|
|
77
|
+
"!**/*.test.js.map"
|
|
78
|
+
],
|
|
79
|
+
"keywords": [
|
|
80
|
+
"ai",
|
|
81
|
+
"framework",
|
|
82
|
+
"coding-assistant",
|
|
83
|
+
"claude-code",
|
|
84
|
+
"codex",
|
|
85
|
+
"aperant"
|
|
86
|
+
],
|
|
87
|
+
"license": "AGPL-3.0-only",
|
|
88
|
+
"homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
|
|
89
|
+
"bugs": {
|
|
90
|
+
"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
|
|
91
|
+
},
|
|
92
|
+
"repository": {
|
|
93
|
+
"type": "git",
|
|
94
|
+
"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
|
|
95
|
+
"directory": "packages/framework"
|
|
96
|
+
},
|
|
97
|
+
"engines": {
|
|
98
|
+
"node": ">=18.0.0"
|
|
99
|
+
},
|
|
100
|
+
"publishConfig": {
|
|
101
|
+
"access": "public"
|
|
102
|
+
},
|
|
103
|
+
"dependencies": {
|
|
104
|
+
"@clack/prompts": "^1.2.0",
|
|
105
|
+
"proper-lockfile": "^4.1.2",
|
|
106
|
+
"yaml": "^2.8.3",
|
|
107
|
+
"zod": "^4.3.6"
|
|
108
|
+
},
|
|
109
|
+
"optionalDependencies": {
|
|
110
|
+
"@babel/parser": "^7.29.2",
|
|
111
|
+
"@babel/traverse": "^7.29.0",
|
|
112
|
+
"@google/genai": "^1.50.1",
|
|
113
|
+
"css-tree": "^3.2.1",
|
|
114
|
+
"playwright": "^1.59.1"
|
|
115
|
+
},
|
|
116
|
+
"devDependencies": {
|
|
117
|
+
"@vitest/coverage-v8": "^4.1.5"
|
|
118
|
+
},
|
|
119
|
+
"scripts": {
|
|
120
|
+
"build": "tsc && node scripts/extract-personas-schema.mjs",
|
|
121
|
+
"dev": "tsc --watch --preserveWatchOutput",
|
|
122
|
+
"typecheck": "tsc --noEmit",
|
|
123
|
+
"lint": "biome check . --diagnostic-level=error",
|
|
124
|
+
"lint:fix": "biome check --write . --diagnostic-level=error",
|
|
125
|
+
"clean": "rm -rf dist",
|
|
126
|
+
"test": "vitest run",
|
|
127
|
+
"c28:cutover": "node scripts/c28-cutover.mjs",
|
|
128
|
+
"build-plugin": "node scripts/build-plugin.mjs",
|
|
129
|
+
"publish-plugin": "node scripts/publish-plugin.mjs",
|
|
130
|
+
"publish:verdaccio": "node scripts/publish-verdaccio.mjs",
|
|
131
|
+
"release:verdaccio": "pnpm build && pnpm publish:verdaccio",
|
|
132
|
+
"ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
|
|
133
|
+
}
|
|
134
|
+
}
|
|
@@ -1110,6 +1110,8 @@ For `AUTHORSHIP_MODE == "owned"`, continue normally.
|
|
|
1110
1110
|
|
|
1111
1111
|
AI agents have near-zero marginal cost per fix. The framework fixes **all** confirmed findings — critical, high, medium, and low — regardless of autonomy level. There is no severity gate and no "report for manual resolution" path. If a finding was confirmed by the validator, it gets fixed.
|
|
1112
1112
|
|
|
1113
|
+
**Hard rule — context budget is NOT a valid skip reason.** The orchestrator MAY NOT defer, drop, downgrade, or "punt for follow-up" any confirmed finding because its own context window feels heavy, because the run has already produced many fixes, or because it judges marginal value low. The query loop auto-compacts on its own — trust it. Per-finding fix work happens inside fix agents (separate context windows), so orchestrator pressure does not justify cutting their inputs. The only valid skip reasons are the ones enumerated in Key Principle #2 (`fixable: false`, critical finding without user approval, file assigned to another fixer). Any other skip is an unauthorized policy deviation — emit all confirmed findings to fixers, then let the audit gate adjudicate outcomes.
|
|
1114
|
+
|
|
1113
1115
|
| Autonomy | Action |
|
|
1114
1116
|
|----------|--------|
|
|
1115
1117
|
| `< 2` | Show findings summary before fixing. Then proceed with auto-fix. |
|
|
@@ -1647,7 +1649,7 @@ node packages/framework/bin/apt-tools.mjs workflow destroy . --id ${REVIEW_ID}
|
|
|
1647
1649
|
Agents do NOT assign confidence percentages. Either they have evidence (actual code snippet from Read tool) or they do not have a finding. The validator independently verifies every finding against real code.
|
|
1648
1650
|
|
|
1649
1651
|
### 2. Fix Everything Found
|
|
1650
|
-
If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
|
|
1652
|
+
If it was found and confirmed, fix it. ALL severities. "This is minor" is NOT a valid skip reason. **Neither is "my context window is heavy" or "I've already done a lot this run"** — orchestrator context pressure never authorizes dropping a confirmed finding (see Phase 6 → Principle: Fix Everything). The only valid skip reasons are: `fixable: false`, critical findings without user approval, or files assigned to another fixer.
|
|
1651
1653
|
|
|
1652
1654
|
### 3. Findings Flow Through Files
|
|
1653
1655
|
Agents write to `.aperant/pr-reviews/{review-id}/findings/`. The orchestrator reads with the Read tool. Fix agents read finding files directly. This keeps the orchestrator context under 30%.
|
|
@@ -1711,6 +1713,11 @@ Fix agents self-report their outcome via a status line (`FIXED: X | FAILED: Y |
|
|
|
1711
1713
|
**Wrong:** Skipping Phase 6 entirely when autonomy < 2.
|
|
1712
1714
|
**Right:** Always fix all confirmed findings. At autonomy < 2, show findings summary first, then proceed with auto-fix. The only difference is whether findings are displayed before fixing — not whether they get fixed.
|
|
1713
1715
|
|
|
1716
|
+
### Mistake 7a: Dropping Findings Because Orchestrator Context Feels Heavy
|
|
1717
|
+
|
|
1718
|
+
**Wrong:** Mid-Phase-6, the orchestrator decides "my window is getting heavy after 6 specialist rounds + Round 1 fixes — I'll skip the minor findings and report a partial fix." This is an unauthorized policy deviation, even when phrased as "judgment call" or "context-budget reasons."
|
|
1719
|
+
**Right:** Spawn fix agents for **every** confirmed finding regardless of orchestrator context state. Fix work happens in the fixer's window, not yours. The query loop auto-compacts when it needs to — trust it. If you genuinely cannot fit the spawn calls, that is a framework bug to file (not a license to ship a partial fix); emit all findings to fixers in the smallest batches possible and let the audit gate adjudicate. Severity, "diminishing returns," and your own token pressure are NOT skip authorities — only the three reasons in Key Principle #2 are.
|
|
1720
|
+
|
|
1714
1721
|
### Mistake 8: Forgetting to Update metadata.json
|
|
1715
1722
|
|
|
1716
1723
|
**Wrong:** Writing review.json but leaving metadata.json stuck at `"status": "in-progress"`.
|