mandrel 2.90.0 → 2.92.0
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/.agents/README.md +47 -7
- package/.agents/agents/story-worker.md +20 -0
- package/.agents/audit-checklists/lean.md +26 -0
- package/.agents/docs/agentrc-reference.json +5 -6
- package/.agents/docs/configuration.md +31 -30
- package/.agents/docs/workflows.md +7 -1
- package/.agents/instructions.md +3 -1
- package/.agents/runtime-deps.json +0 -2
- package/.agents/schemas/agentrc.schema.json +46 -45
- package/.agents/schemas/audit-rules.json +19 -0
- package/.agents/scripts/acceptance-eval.js +2 -6
- package/.agents/scripts/audit-exceptions.js +2 -4
- package/.agents/scripts/check-arch-cycles.js +1 -5
- package/.agents/scripts/check-context-budget.js +1 -5
- package/.agents/scripts/check-cyclomatic.js +1 -5
- package/.agents/scripts/check-dead-exports.js +23 -14
- package/.agents/scripts/check-doc-links.js +4 -4
- package/.agents/scripts/check-test-temp-hygiene.js +29 -33
- package/.agents/scripts/coverage-capture.js +14 -6
- package/.agents/scripts/diagnose-friction.js +8 -10
- package/.agents/scripts/generate-workflows-doc.js +5 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
- package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
- package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
- package/.agents/scripts/lib/baselines/components.js +5 -5
- package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
- package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
- package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
- package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
- package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
- package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
- package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
- package/.agents/scripts/lib/baselines/writer.js +4 -4
- package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
- package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
- package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
- package/.agents/scripts/lib/child-exec.js +4 -4
- package/.agents/scripts/lib/claude/agents-projection.js +170 -0
- package/.agents/scripts/lib/claude/commands-projection.js +184 -0
- package/.agents/scripts/lib/close-validation/commands.js +28 -117
- package/.agents/scripts/lib/close-validation/gates.js +54 -48
- package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
- package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
- package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
- package/.agents/scripts/lib/config/commands.js +82 -7
- package/.agents/scripts/lib/config/explain.js +2 -1
- package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
- package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
- package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
- package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
- package/.agents/scripts/lib/config/gates/shared.js +2 -2
- package/.agents/scripts/lib/config/git-roots.js +120 -0
- package/.agents/scripts/lib/config/quality.js +46 -50
- package/.agents/scripts/lib/config/review-chain-default.js +4 -3
- package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
- package/.agents/scripts/lib/config/temp-paths.js +3 -37
- package/.agents/scripts/lib/config-resolver.js +5 -9
- package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
- package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
- package/.agents/scripts/lib/config-settings-schema.js +6 -7
- package/.agents/scripts/lib/coverage-baseline.js +2 -1
- package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
- package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
- package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
- package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
- package/.agents/scripts/lib/coverage-capture.js +31 -20
- package/.agents/scripts/lib/coverage-utils.js +34 -16
- package/.agents/scripts/lib/cpu-pool.js +2 -4
- package/.agents/scripts/lib/crap-engine.js +19 -1
- package/.agents/scripts/lib/crap-utils.js +2 -1
- package/.agents/scripts/lib/dead-exports-knip.js +29 -11
- package/.agents/scripts/lib/detect-package-manager.js +13 -0
- package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
- package/.agents/scripts/lib/full-suite-lock.js +25 -9
- package/.agents/scripts/lib/gates/baseline-store.js +2 -10
- package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
- package/.agents/scripts/lib/gh-env.js +72 -0
- package/.agents/scripts/lib/gh-exec.js +26 -1
- package/.agents/scripts/lib/maintainability-utils.js +8 -8
- package/.agents/scripts/lib/npm-scripts.js +1 -1
- package/.agents/scripts/lib/observability/signal-validator.js +2 -6
- package/.agents/scripts/lib/observability/terse-result.js +2 -6
- package/.agents/scripts/lib/orchestration/board-access-latch.js +19 -8
- package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
- package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
- package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
- package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
- package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
- package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
- package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
- package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
- package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
- package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
- package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
- package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
- package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
- package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
- package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
- package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
- package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +4 -1
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +49 -83
- package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
- package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
- package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
- package/.agents/scripts/lib/orchestration/story-handoff.js +13 -5
- package/.agents/scripts/lib/orchestration/story-init-result.js +11 -0
- package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
- package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
- package/.agents/scripts/lib/orchestration/ticketing/transition.js +47 -21
- package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
- package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
- package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
- package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
- package/.agents/scripts/lib/source-extensions.js +30 -15
- package/.agents/scripts/lib/test-run-credit.js +1 -9
- package/.agents/scripts/lib/test-temp.js +22 -21
- package/.agents/scripts/lib/util/ajv.js +111 -0
- package/.agents/scripts/lib/util/atomic-write.js +30 -0
- package/.agents/scripts/lib/util/paths.js +51 -0
- package/.agents/scripts/lib/util/sleep.js +6 -0
- package/.agents/scripts/lib/util/slug.js +12 -0
- package/.agents/scripts/lib/validation-evidence.js +19 -40
- package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
- package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
- package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
- package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
- package/.agents/scripts/lint-issue-body.js +2 -2
- package/.agents/scripts/plan-context.js +2 -7
- package/.agents/scripts/providers/github/auth.js +3 -3
- package/.agents/scripts/providers/github/errors.js +3 -1
- package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
- package/.agents/scripts/providers/github/issues.js +6 -2
- package/.agents/scripts/providers/github/mappers.js +1 -5
- package/.agents/scripts/providers/github/projects-v2-graphql.js +11 -3
- package/.agents/scripts/providers/github/search-budget.js +3 -1
- package/.agents/scripts/resolve-doc-tiers.js +7 -20
- package/.agents/scripts/single-story-init.js +18 -14
- package/.agents/scripts/sync-agentrc.js +5 -14
- package/.agents/scripts/sync-claude-agents.js +38 -150
- package/.agents/scripts/sync-claude-commands.js +35 -218
- package/.agents/scripts/update-coverage-baseline.js +1 -1
- package/.agents/scripts/update-crap-baseline.js +1 -1
- package/.agents/scripts/update-duplication-baseline.js +2 -16
- package/.agents/scripts/validate-skills.js +6 -10
- package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
- package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
- package/.agents/workflows/audit-exceptions.md +9 -0
- package/.agents/workflows/audit-lean.md +129 -0
- package/.agents/workflows/helpers/audit-lens-core.md +7 -0
- package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
- package/.agents/workflows/helpers/code-review.md +15 -1
- package/.agents/workflows/helpers/deliver-digest.md +1 -1
- package/.agents/workflows/helpers/deliver-reference.md +2 -2
- package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
- package/.agents/workflows/mandrel-plan.md +2 -2
- package/docs/CHANGELOG.md +42 -0
- package/lib/cli/doctor-checks/codex.js +6 -5
- package/lib/cli/doctor-checks/llm-review.js +102 -0
- package/lib/cli/doctor-checks/project-access.js +20 -10
- package/lib/cli/doctor-checks/sync-parity.js +65 -140
- package/lib/cli/doctor-checks/test-credit-path.js +69 -28
- package/lib/cli/doctor-checks/toolchain.js +5 -3
- package/lib/cli/registry.js +5 -0
- package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
- package/lib/migrations/index.js +6 -0
- package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
- package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
- package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
- package/package.json +1 -3
|
@@ -1,159 +1,47 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
|
-
/**
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
import { syncCodexAgents } from './lib/codex/agents-projection.js';
|
|
16
|
-
import { applyHeader } from './lib/command-header.js';
|
|
17
|
-
import { applyAgentModel, getAgentModels } from './lib/config/agent-models.js';
|
|
3
|
+
/** Project the role agents for Claude, then Codex, from `process.cwd()`. */
|
|
4
|
+
|
|
5
|
+
import {
|
|
6
|
+
CLAUDE_AGENTS_DIR,
|
|
7
|
+
syncClaudeAgents,
|
|
8
|
+
} from './lib/claude/agents-projection.js';
|
|
9
|
+
import { runAsCli } from './lib/cli-utils.js';
|
|
10
|
+
import {
|
|
11
|
+
CODEX_AGENTS_DIR,
|
|
12
|
+
syncCodexAgents,
|
|
13
|
+
} from './lib/codex/agents-projection.js';
|
|
14
|
+
import { getAgentModels } from './lib/config/agent-models.js';
|
|
18
15
|
import { resolveConfig } from './lib/config-resolver.js';
|
|
19
16
|
import { Logger } from './lib/Logger.js';
|
|
20
|
-
import { dirExists } from './lib/util/paths.js';
|
|
21
|
-
|
|
22
|
-
// cwd, never `__dirname/../..`, which lands inside node_modules when installed.
|
|
23
|
-
const PROJECT_ROOT = process.cwd();
|
|
24
|
-
|
|
25
|
-
// Test overrides; SYNC_CLAUDE_AGENTS_SRC replaces the payload source only.
|
|
26
|
-
const PAYLOAD_SRC =
|
|
27
|
-
process.env.SYNC_CLAUDE_AGENTS_SRC ??
|
|
28
|
-
path.join(PROJECT_ROOT, '.agents', 'agents');
|
|
29
|
-
const LOCAL_SRC = path.join(PROJECT_ROOT, '.agents', 'local', 'agents');
|
|
30
|
-
|
|
31
|
-
const DEST_DIR =
|
|
32
|
-
process.env.SYNC_CLAUDE_AGENTS_DEST ??
|
|
33
|
-
path.join(PROJECT_ROOT, '.claude', 'agents');
|
|
34
|
-
|
|
35
|
-
export const HEADER =
|
|
36
|
-
'<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
|
|
37
|
-
|
|
38
|
-
export const LOCAL_HEADER =
|
|
39
|
-
'<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
|
|
40
|
-
|
|
41
|
-
fs.mkdirSync(DEST_DIR, { recursive: true });
|
|
42
|
-
|
|
43
|
-
const isTopLevelAgent = (entry) => entry.isFile() && entry.name.endsWith('.md');
|
|
44
17
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
return fs
|
|
57
|
-
.readdirSync(dir, { withFileTypes: true })
|
|
58
|
-
.filter(isTopLevelAgent)
|
|
59
|
-
.map(function toAgentEntry(e) {
|
|
60
|
-
return { dir, name: e.name };
|
|
61
|
-
});
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
const entries = SRC_DIRS.flatMap(agentEntriesIn);
|
|
65
|
-
|
|
66
|
-
const byName = new Map();
|
|
67
|
-
for (const e of entries) {
|
|
68
|
-
if (byName.has(e.name)) {
|
|
69
|
-
Logger.warn(` shadowed ${e.name} (local copy ignored; payload wins)`);
|
|
70
|
-
continue;
|
|
71
|
-
}
|
|
72
|
-
byName.set(e.name, e);
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
// Any existing agent def not in this set is reaped.
|
|
76
|
-
const sourceSet = new Set(byName.keys());
|
|
77
|
-
|
|
78
|
-
/**
|
|
79
|
-
* @returns {string[]}
|
|
80
|
-
*/
|
|
81
|
-
function listExistingAgents() {
|
|
82
|
-
try {
|
|
83
|
-
return fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
|
|
84
|
-
} catch {
|
|
85
|
-
return [];
|
|
86
|
-
}
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
for (const name of listExistingAgents()) {
|
|
90
|
-
if (!sourceSet.has(name)) {
|
|
91
|
-
fs.unlinkSync(path.join(DEST_DIR, name));
|
|
92
|
-
Logger.info(` removed ${name} (no longer in .agents/agents)`);
|
|
93
|
-
}
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
// Resolved once: an invalid override (an unknown role) fails the sync here.
|
|
97
|
-
const agentModels = getAgentModels(resolveConfig({ cwd: PROJECT_ROOT }));
|
|
98
|
-
|
|
99
|
-
/**
|
|
100
|
-
* @param {string} name
|
|
101
|
-
* @param {string} content
|
|
102
|
-
* @returns {string}
|
|
103
|
-
*/
|
|
104
|
-
function withModelOverride(name, content) {
|
|
105
|
-
const model = agentModels[name.replace(/\.md$/, '')];
|
|
106
|
-
return model ? applyAgentModel(content, model) : content;
|
|
107
|
-
}
|
|
108
|
-
|
|
109
|
-
let synced = 0;
|
|
110
|
-
|
|
111
|
-
/**
|
|
112
|
-
* The header goes after any frontmatter, so `---` stays on line 1.
|
|
113
|
-
*
|
|
114
|
-
* @param {{ dir: string, name: string }} entry
|
|
115
|
-
* @returns {Promise<void>}
|
|
116
|
-
*/
|
|
117
|
-
async function syncEntry({ dir, name }) {
|
|
118
|
-
const isLocal = dir === LOCAL_SRC;
|
|
119
|
-
const header = isLocal ? LOCAL_HEADER : HEADER;
|
|
120
|
-
const content = await fs.promises.readFile(path.join(dir, name), 'utf8');
|
|
121
|
-
const dest = path.join(DEST_DIR, name);
|
|
122
|
-
const target = applyHeader(withModelOverride(name, content), header);
|
|
123
|
-
|
|
124
|
-
try {
|
|
125
|
-
const existingContent = await fs.promises.readFile(dest, 'utf8');
|
|
126
|
-
if (existingContent === target) return;
|
|
127
|
-
} catch (err) {
|
|
128
|
-
if (err.code !== 'ENOENT') throw err;
|
|
129
|
-
}
|
|
130
|
-
|
|
131
|
-
await fs.promises.writeFile(dest, target, 'utf8');
|
|
132
|
-
synced++;
|
|
133
|
-
Logger.info(` synced ${name}`);
|
|
134
|
-
}
|
|
135
|
-
|
|
136
|
-
await Promise.all(Array.from(byName.values()).map(syncEntry));
|
|
137
|
-
|
|
138
|
-
Logger.info(
|
|
139
|
-
`\n✔ ${synced} file(s) synced, ${sourceSet.size} total agents in .claude/agents/`,
|
|
140
|
-
);
|
|
141
|
-
|
|
142
|
-
// The Codex half: the same roles as `.codex/agents/mandrel-<role>.toml`. A
|
|
143
|
-
// fixture run (a DEST override) skips it unless SYNC_CODEX_AGENTS_DEST names
|
|
144
|
-
// its own target.
|
|
145
|
-
const codexAgentsDest =
|
|
146
|
-
process.env.SYNC_CODEX_AGENTS_DEST ??
|
|
147
|
-
(process.env.SYNC_CLAUDE_AGENTS_DEST ? null : undefined);
|
|
148
|
-
if (codexAgentsDest !== null) {
|
|
149
|
-
const codex = syncCodexAgents({
|
|
150
|
-
projectRoot: PROJECT_ROOT,
|
|
151
|
-
payloadSrc: PAYLOAD_SRC,
|
|
152
|
-
localSrc: LOCAL_SRC,
|
|
153
|
-
destDir: codexAgentsDest,
|
|
154
|
-
log: (line) => Logger.info(line),
|
|
18
|
+
/** @returns {Promise<void>} */
|
|
19
|
+
async function main() {
|
|
20
|
+
// cwd, never `__dirname/../..`, which lands inside node_modules.
|
|
21
|
+
const projectRoot = process.cwd();
|
|
22
|
+
const log = (line) => Logger.info(line);
|
|
23
|
+
const claude = syncClaudeAgents({
|
|
24
|
+
projectRoot,
|
|
25
|
+
// Validated: an unknown role fails the sync.
|
|
26
|
+
agentModels: getAgentModels(resolveConfig({ cwd: projectRoot })),
|
|
27
|
+
log,
|
|
28
|
+
warn: (line) => Logger.warn(line),
|
|
155
29
|
});
|
|
156
30
|
Logger.info(
|
|
157
|
-
|
|
31
|
+
`\n✔ ${claude.written.length} file(s) synced, ${claude.total} total agents in ${CLAUDE_AGENTS_DIR}/`,
|
|
32
|
+
);
|
|
33
|
+
const codex = syncCodexAgents({ projectRoot, log });
|
|
34
|
+
Logger.info(
|
|
35
|
+
`✔ ${codex.written.length} file(s) synced, ${codex.total} total Codex agents in ${CODEX_AGENTS_DIR}/`,
|
|
158
36
|
);
|
|
159
37
|
}
|
|
38
|
+
|
|
39
|
+
runAsCli(import.meta.url, main, {
|
|
40
|
+
source: 'sync-claude-agents',
|
|
41
|
+
usage: {
|
|
42
|
+
invocation: 'node .agents/scripts/sync-claude-agents.js',
|
|
43
|
+
summary:
|
|
44
|
+
'Regenerate the .claude/agents/ projection of .agents/agents/ (and .agents/local/agents/), then the Codex agents under .codex/agents/.',
|
|
45
|
+
flags: [],
|
|
46
|
+
},
|
|
47
|
+
});
|
|
@@ -1,226 +1,43 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
|
-
/**
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
import path from 'node:path';
|
|
15
|
-
|
|
16
|
-
import { syncCodexSkills } from './lib/codex/skills-projection.js';
|
|
17
|
-
import { applyHeader, isCommandExcluded } from './lib/command-header.js';
|
|
3
|
+
/** Project the workflow set for Claude, then Codex, from `process.cwd()`. */
|
|
4
|
+
|
|
5
|
+
import {
|
|
6
|
+
CLAUDE_COMMANDS_DIR,
|
|
7
|
+
syncClaudeCommands,
|
|
8
|
+
} from './lib/claude/commands-projection.js';
|
|
9
|
+
import { runAsCli } from './lib/cli-utils.js';
|
|
10
|
+
import {
|
|
11
|
+
CODEX_SKILLS_DIR,
|
|
12
|
+
syncCodexSkills,
|
|
13
|
+
} from './lib/codex/skills-projection.js';
|
|
18
14
|
import { Logger } from './lib/Logger.js';
|
|
19
|
-
import { dirExists } from './lib/util/paths.js';
|
|
20
|
-
|
|
21
|
-
// The root is cwd, never `__dirname/../..`: installed under node_modules that
|
|
22
|
-
// climb lands on the package dir and would write commands inside it.
|
|
23
|
-
const PROJECT_ROOT = process.cwd();
|
|
24
|
-
|
|
25
|
-
// Test overrides; SYNC_CLAUDE_COMMANDS_SRC replaces the payload source only.
|
|
26
|
-
const PAYLOAD_SRC =
|
|
27
|
-
process.env.SYNC_CLAUDE_COMMANDS_SRC ??
|
|
28
|
-
path.join(PROJECT_ROOT, '.agents', 'workflows');
|
|
29
|
-
const LOCAL_SRC = path.join(PROJECT_ROOT, '.agents', 'local', 'workflows');
|
|
30
|
-
|
|
31
|
-
const DEST_DIR =
|
|
32
|
-
process.env.SYNC_CLAUDE_COMMANDS_DEST ??
|
|
33
|
-
path.join(PROJECT_ROOT, '.claude', 'commands');
|
|
34
|
-
|
|
35
|
-
export const HEADER =
|
|
36
|
-
'<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/workflows/ -->\n<!-- Re-run: npm run sync:commands -->\n\n';
|
|
37
|
-
|
|
38
|
-
export const LOCAL_HEADER =
|
|
39
|
-
'<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/workflows/ -->\n<!-- Re-run: npm run sync:commands -->\n\n';
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* Remove any on-disk plugin projection and marketplace listing, which would
|
|
43
|
-
* shadow the flat commands. Idempotent; skipped for fixture runs.
|
|
44
|
-
*
|
|
45
|
-
* @returns {void}
|
|
46
|
-
*/
|
|
47
|
-
function reapPluginTree() {
|
|
48
|
-
if (process.env.SYNC_CLAUDE_COMMANDS_DEST) return;
|
|
49
|
-
const pluginRoot = path.join(PROJECT_ROOT, '.claude', 'plugins', 'mandrel');
|
|
50
|
-
const marketplace = path.join(
|
|
51
|
-
PROJECT_ROOT,
|
|
52
|
-
'.claude',
|
|
53
|
-
'.claude-plugin',
|
|
54
|
-
'marketplace.json',
|
|
55
|
-
);
|
|
56
|
-
for (const target of [pluginRoot, marketplace]) {
|
|
57
|
-
try {
|
|
58
|
-
fs.rmSync(target, { recursive: true, force: true });
|
|
59
|
-
} catch (err) {
|
|
60
|
-
Logger.warn(` skip reap ${target}: ${err.message}`);
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
|
-
try {
|
|
64
|
-
fs.rmdirSync(path.join(PROJECT_ROOT, '.claude', '.claude-plugin'));
|
|
65
|
-
} catch {
|
|
66
|
-
/* not empty or absent — leave it */
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
reapPluginTree();
|
|
71
|
-
fs.mkdirSync(DEST_DIR, { recursive: true });
|
|
72
|
-
|
|
73
|
-
// The only recursed subdirectory; helpers/ holds path-included modules.
|
|
74
|
-
const LOOPS_NS = 'loops';
|
|
75
|
-
|
|
76
|
-
const isTopLevelWorkflow = (entry) =>
|
|
77
|
-
entry.isFile() && entry.name.endsWith('.md');
|
|
78
|
-
|
|
79
|
-
/**
|
|
80
|
-
* `loops/README.md` is documentation, not a command.
|
|
81
|
-
*
|
|
82
|
-
* @param {import('node:fs').Dirent} entry
|
|
83
|
-
* @returns {boolean}
|
|
84
|
-
*/
|
|
85
|
-
const isLoopUnit = (entry) =>
|
|
86
|
-
isTopLevelWorkflow(entry) && entry.name.toLowerCase() !== 'readme.md';
|
|
87
|
-
|
|
88
|
-
/**
|
|
89
|
-
* Keyed by `loops/<name>.md` so a unit never collides with a flat command.
|
|
90
|
-
*
|
|
91
|
-
* @param {string} dir A workflows source root.
|
|
92
|
-
* @returns {Array<{dir: string, name: string, rel: string}>}
|
|
93
|
-
*/
|
|
94
|
-
function enumerateLoopUnits(dir) {
|
|
95
|
-
const loopsDir = path.join(dir, LOOPS_NS);
|
|
96
|
-
if (!dirExists(loopsDir)) return [];
|
|
97
|
-
return fs
|
|
98
|
-
.readdirSync(loopsDir, { withFileTypes: true })
|
|
99
|
-
.filter(isLoopUnit)
|
|
100
|
-
.map((e) => ({
|
|
101
|
-
dir,
|
|
102
|
-
name: e.name,
|
|
103
|
-
rel: `${LOOPS_NS}/${e.name}`,
|
|
104
|
-
}));
|
|
105
|
-
}
|
|
106
|
-
|
|
107
|
-
// Payload first, so it wins a collision.
|
|
108
|
-
const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
|
|
109
|
-
|
|
110
|
-
/**
|
|
111
|
-
* Named, not inline: an anonymous callback in this spawned-only script has no
|
|
112
|
-
* coverage coordinates for the CRAP seat to resolve.
|
|
113
|
-
*
|
|
114
|
-
* @param {string} dir A workflows source root.
|
|
115
|
-
* @returns {Array<{dir: string, name: string, rel: string}>}
|
|
116
|
-
*/
|
|
117
|
-
function workflowEntriesIn(dir) {
|
|
118
|
-
return [
|
|
119
|
-
...fs
|
|
120
|
-
.readdirSync(dir, { withFileTypes: true })
|
|
121
|
-
.filter(isTopLevelWorkflow)
|
|
122
|
-
.map(function toWorkflowEntry(e) {
|
|
123
|
-
return { dir, name: e.name, rel: e.name };
|
|
124
|
-
}),
|
|
125
|
-
...enumerateLoopUnits(dir),
|
|
126
|
-
];
|
|
127
|
-
}
|
|
128
15
|
|
|
129
|
-
/** @
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
const
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
}
|
|
139
|
-
if (isCommandExcluded(fs.readFileSync(path.join(e.dir, e.rel), 'utf8'))) {
|
|
140
|
-
Logger.info(` excluded ${e.rel} (frontmatter command: false)`);
|
|
141
|
-
continue;
|
|
142
|
-
}
|
|
143
|
-
byRel.set(e.rel, e);
|
|
144
|
-
}
|
|
145
|
-
|
|
146
|
-
// Any existing command not in this set is reaped.
|
|
147
|
-
const sourceSet = new Set(byRel.keys());
|
|
148
|
-
|
|
149
|
-
/**
|
|
150
|
-
* @returns {string[]}
|
|
151
|
-
*/
|
|
152
|
-
function listExistingCommands() {
|
|
153
|
-
const flat = fs
|
|
154
|
-
.readdirSync(DEST_DIR)
|
|
155
|
-
.filter((f) => f.endsWith('.md'))
|
|
156
|
-
.map((f) => f);
|
|
157
|
-
const loopsDest = path.join(DEST_DIR, LOOPS_NS);
|
|
158
|
-
const loops = dirExists(loopsDest)
|
|
159
|
-
? fs
|
|
160
|
-
.readdirSync(loopsDest)
|
|
161
|
-
.filter((f) => f.endsWith('.md'))
|
|
162
|
-
.map((f) => `${LOOPS_NS}/${f}`)
|
|
163
|
-
: [];
|
|
164
|
-
return [...flat, ...loops];
|
|
165
|
-
}
|
|
166
|
-
|
|
167
|
-
for (const rel of listExistingCommands()) {
|
|
168
|
-
if (!sourceSet.has(rel)) {
|
|
169
|
-
fs.unlinkSync(path.join(DEST_DIR, rel));
|
|
170
|
-
Logger.info(` removed ${rel} (no longer in workflows)`);
|
|
171
|
-
}
|
|
172
|
-
}
|
|
173
|
-
|
|
174
|
-
// The header goes after any frontmatter, so `---` stays on line 1.
|
|
175
|
-
let synced = 0;
|
|
176
|
-
const resolvedEntries = Array.from(byRel.values());
|
|
177
|
-
|
|
178
|
-
/**
|
|
179
|
-
* @param {{ dir: string, rel: string }} entry
|
|
180
|
-
* @returns {Promise<void>}
|
|
181
|
-
*/
|
|
182
|
-
async function syncEntry({ dir, rel }) {
|
|
183
|
-
const isLocal = dir === LOCAL_SRC;
|
|
184
|
-
const header = isLocal ? LOCAL_HEADER : HEADER;
|
|
185
|
-
const content = await fs.promises.readFile(path.join(dir, rel), 'utf8');
|
|
186
|
-
const dest = path.join(DEST_DIR, rel);
|
|
187
|
-
const target = applyHeader(content, header);
|
|
188
|
-
|
|
189
|
-
await fs.promises.mkdir(path.dirname(dest), { recursive: true });
|
|
190
|
-
|
|
191
|
-
// Skip identical content to avoid noisy git diffs.
|
|
192
|
-
try {
|
|
193
|
-
const existingContent = await fs.promises.readFile(dest, 'utf8');
|
|
194
|
-
if (existingContent === target) return;
|
|
195
|
-
} catch (err) {
|
|
196
|
-
if (err.code !== 'ENOENT') throw err;
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
await fs.promises.writeFile(dest, target, 'utf8');
|
|
200
|
-
synced++;
|
|
201
|
-
Logger.info(` synced ${rel}`);
|
|
202
|
-
}
|
|
203
|
-
|
|
204
|
-
await Promise.all(resolvedEntries.map(syncEntry));
|
|
205
|
-
|
|
206
|
-
Logger.info(
|
|
207
|
-
`\n✔ ${synced} file(s) synced, ${sourceSet.size} total commands in .claude/commands/`,
|
|
208
|
-
);
|
|
209
|
-
|
|
210
|
-
// The Codex half: the same source set as Codex skills. A fixture run (a
|
|
211
|
-
// DEST override) skips it unless SYNC_CODEX_SKILLS_DEST names its own target.
|
|
212
|
-
const codexSkillsDest =
|
|
213
|
-
process.env.SYNC_CODEX_SKILLS_DEST ??
|
|
214
|
-
(process.env.SYNC_CLAUDE_COMMANDS_DEST ? null : undefined);
|
|
215
|
-
if (codexSkillsDest !== null) {
|
|
216
|
-
const codex = syncCodexSkills({
|
|
217
|
-
projectRoot: PROJECT_ROOT,
|
|
218
|
-
payloadSrc: PAYLOAD_SRC,
|
|
219
|
-
localSrc: LOCAL_SRC,
|
|
220
|
-
destDir: codexSkillsDest,
|
|
221
|
-
log: (line) => Logger.info(line),
|
|
16
|
+
/** @returns {Promise<void>} */
|
|
17
|
+
async function main() {
|
|
18
|
+
// cwd, never `__dirname/../..`, which lands inside node_modules.
|
|
19
|
+
const projectRoot = process.cwd();
|
|
20
|
+
const log = (line) => Logger.info(line);
|
|
21
|
+
const claude = syncClaudeCommands({
|
|
22
|
+
projectRoot,
|
|
23
|
+
log,
|
|
24
|
+
warn: (line) => Logger.warn(line),
|
|
222
25
|
});
|
|
223
26
|
Logger.info(
|
|
224
|
-
|
|
27
|
+
`\n✔ ${claude.written.length} file(s) synced, ${claude.total} total commands in ${CLAUDE_COMMANDS_DIR}/`,
|
|
28
|
+
);
|
|
29
|
+
const codex = syncCodexSkills({ projectRoot, log });
|
|
30
|
+
Logger.info(
|
|
31
|
+
`✔ ${codex.written.length} file(s) synced, ${codex.total} total Codex skills in ${CODEX_SKILLS_DIR}/`,
|
|
225
32
|
);
|
|
226
33
|
}
|
|
34
|
+
|
|
35
|
+
runAsCli(import.meta.url, main, {
|
|
36
|
+
source: 'sync-claude-commands',
|
|
37
|
+
usage: {
|
|
38
|
+
invocation: 'node .agents/scripts/sync-claude-commands.js',
|
|
39
|
+
summary:
|
|
40
|
+
'Regenerate the .claude/commands/ projection of .agents/workflows/ (and .agents/local/workflows/), then the Codex skills under .agents/skills/workflows/.',
|
|
41
|
+
flags: [],
|
|
42
|
+
},
|
|
43
|
+
});
|
|
@@ -35,7 +35,7 @@ const USAGE = {
|
|
|
35
35
|
],
|
|
36
36
|
],
|
|
37
37
|
notes: [
|
|
38
|
-
|
|
38
|
+
"Run the coverage gate's `captureScript` first (`delivery.quality.gates.coverage.captureScript`) — this script never runs the suite itself.",
|
|
39
39
|
'Against an `affected`-stamped artifact only measured rows are rewritten; rows the scoped run skipped are kept.',
|
|
40
40
|
],
|
|
41
41
|
};
|
|
@@ -55,7 +55,7 @@ const USAGE = {
|
|
|
55
55
|
],
|
|
56
56
|
],
|
|
57
57
|
notes: [
|
|
58
|
-
|
|
58
|
+
"Run the CRAP capture script first — `<pm> run <delivery.quality.gates.crap.captureScript>`, default the coverage gate's `captureScript` — without a coverage artifact the refresh refuses (exit 1) and leaves the baseline untouched.",
|
|
59
59
|
],
|
|
60
60
|
};
|
|
61
61
|
|
|
@@ -11,6 +11,7 @@ import path from 'node:path';
|
|
|
11
11
|
import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
|
|
12
12
|
import { JSCPD_MISSING } from './lib/baselines/duplication-scanner.js';
|
|
13
13
|
import { refreshBaseline } from './lib/baselines/refresh-service.js';
|
|
14
|
+
import { parseGateArgv } from './lib/cli-args.js';
|
|
14
15
|
import { runAsCli } from './lib/cli-utils.js';
|
|
15
16
|
import { getBaselineEpsilon } from './lib/config/quality.js';
|
|
16
17
|
import { getQuality, resolveConfig } from './lib/config-resolver.js';
|
|
@@ -42,21 +43,6 @@ const USAGE = {
|
|
|
42
43
|
],
|
|
43
44
|
};
|
|
44
45
|
|
|
45
|
-
/**
|
|
46
|
-
* @param {string[]} argv
|
|
47
|
-
* @returns {{ baselinePath: string | undefined }}
|
|
48
|
-
*/
|
|
49
|
-
function parseCliArgs(argv = process.argv.slice(2)) {
|
|
50
|
-
const out = { baselinePath: undefined };
|
|
51
|
-
for (let i = 0; i < argv.length; i += 1) {
|
|
52
|
-
if (argv[i] === '--baseline' && argv[i + 1]) {
|
|
53
|
-
out.baselinePath = argv[i + 1];
|
|
54
|
-
i += 1;
|
|
55
|
-
}
|
|
56
|
-
}
|
|
57
|
-
return out;
|
|
58
|
-
}
|
|
59
|
-
|
|
60
46
|
/**
|
|
61
47
|
* @param {string[]} argv
|
|
62
48
|
* @returns {boolean}
|
|
@@ -100,7 +86,7 @@ function resolveScopeSelection(argv) {
|
|
|
100
86
|
*/
|
|
101
87
|
function resolveAbsBaselinePath(argv, gate) {
|
|
102
88
|
const baselinePath =
|
|
103
|
-
|
|
89
|
+
parseGateArgv(argv, { strings: ['baseline'] }).baseline ??
|
|
104
90
|
gate.baselinePath ??
|
|
105
91
|
'baselines/duplication.json';
|
|
106
92
|
return path.isAbsolute(baselinePath)
|
|
@@ -11,8 +11,6 @@
|
|
|
11
11
|
import fs from 'node:fs';
|
|
12
12
|
import path from 'node:path';
|
|
13
13
|
import { fileURLToPath } from 'node:url';
|
|
14
|
-
import Ajv from 'ajv';
|
|
15
|
-
import addFormats from 'ajv-formats';
|
|
16
14
|
import { parseStandardCliArgs } from './lib/cli/standard-args.js';
|
|
17
15
|
import { runAsCli } from './lib/cli-utils.js';
|
|
18
16
|
import { Logger } from './lib/Logger.js';
|
|
@@ -28,6 +26,7 @@ import {
|
|
|
28
26
|
LOCAL_SKILLS_SEGMENTS,
|
|
29
27
|
PAYLOAD_SKILLS_SEGMENTS,
|
|
30
28
|
} from './lib/skills/walk-skill-files.js';
|
|
29
|
+
import { createAjv } from './lib/util/ajv.js';
|
|
31
30
|
|
|
32
31
|
const MIN_CAPSULE_BULLETS = 5;
|
|
33
32
|
const MAX_CAPSULE_BULLETS = 12;
|
|
@@ -92,22 +91,19 @@ function loadManifestSchema(repoRoot) {
|
|
|
92
91
|
return JSON.parse(fs.readFileSync(fallback, 'utf8'));
|
|
93
92
|
}
|
|
94
93
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
const addFormatsFn = addFormats.default ?? addFormats;
|
|
99
|
-
addFormatsFn(ajv);
|
|
100
|
-
return ajv;
|
|
94
|
+
/** One option bag for both skill-schema validators. */
|
|
95
|
+
function createSkillsAjv() {
|
|
96
|
+
return createAjv({ allErrors: true, strict: false });
|
|
101
97
|
}
|
|
102
98
|
|
|
103
99
|
function buildValidator(repoRoot) {
|
|
104
|
-
const ajv =
|
|
100
|
+
const ajv = createSkillsAjv();
|
|
105
101
|
const schema = loadSkillSchema(repoRoot);
|
|
106
102
|
return ajv.compile(schema);
|
|
107
103
|
}
|
|
108
104
|
|
|
109
105
|
function buildManifestValidator(repoRoot) {
|
|
110
|
-
const ajv =
|
|
106
|
+
const ajv = createSkillsAjv();
|
|
111
107
|
const schema = loadManifestSchema(repoRoot);
|
|
112
108
|
return ajv.compile(schema);
|
|
113
109
|
}
|
|
@@ -23,28 +23,13 @@ description:
|
|
|
23
23
|
## Long-form reference — read on demand
|
|
24
24
|
|
|
25
25
|
The capsule above is the contract and the whole always-read surface of this
|
|
26
|
-
skill. The
|
|
27
|
-
|
|
26
|
+
skill. The project-specific material behind it — the finding-severity table and
|
|
27
|
+
the post-green refactor pass — lives in the on-demand sibling
|
|
28
28
|
[`reference.md`](reference.md), matching the split the always-on rules already
|
|
29
29
|
use ([`rules/git-conventions.md`](../../../rules/git-conventions.md) ⇄
|
|
30
30
|
[`git-conventions-reference.md`](../../../rules/git-conventions-reference.md)).
|
|
31
31
|
Activating this skill costs the capsule; open a section below only when the
|
|
32
32
|
task actually engages it.
|
|
33
33
|
|
|
34
|
-
- [
|
|
35
|
-
- [When to Use](reference.md#when-to-use)
|
|
36
|
-
- [The Five-Axis Review](reference.md#the-five-axis-review)
|
|
37
|
-
- [Change Sizing](reference.md#change-sizing)
|
|
38
|
-
- [Change Descriptions](reference.md#change-descriptions)
|
|
39
|
-
- [Review Process](reference.md#review-process)
|
|
40
|
-
- [Multi-Model Review Pattern](reference.md#multi-model-review-pattern)
|
|
41
|
-
- [Dead Code Hygiene](reference.md#dead-code-hygiene)
|
|
42
|
-
- [Review Speed](reference.md#review-speed)
|
|
43
|
-
- [Handling Disagreements](reference.md#handling-disagreements)
|
|
44
|
-
- [Honesty in Review](reference.md#honesty-in-review)
|
|
45
|
-
- [Dependency Discipline](reference.md#dependency-discipline)
|
|
46
|
-
- [The Review Checklist](reference.md#the-review-checklist)
|
|
47
|
-
- [Common Rationalizations](reference.md#common-rationalizations)
|
|
48
|
-
- [Red Flags](reference.md#red-flags)
|
|
34
|
+
- [Finding-Severity Table](reference.md#finding-severity-table)
|
|
49
35
|
- [Post-Green Refactor Pass](reference.md#post-green-refactor-pass)
|
|
50
|
-
- [Verification](reference.md#verification)
|
|
@@ -20,23 +20,13 @@ description:
|
|
|
20
20
|
## Long-form reference — read on demand
|
|
21
21
|
|
|
22
22
|
The capsule above is the contract and the whole always-read surface of this
|
|
23
|
-
skill. The
|
|
24
|
-
|
|
23
|
+
skill. The project-specific material behind it — the decisions-log layouts and
|
|
24
|
+
the prune/archive procedure — lives in the on-demand sibling
|
|
25
25
|
[`reference.md`](reference.md), matching the split the always-on rules already
|
|
26
26
|
use ([`rules/git-conventions.md`](../../../rules/git-conventions.md) ⇄
|
|
27
27
|
[`git-conventions-reference.md`](../../../rules/git-conventions-reference.md)).
|
|
28
28
|
Activating this skill costs the capsule; open a section below only when the
|
|
29
29
|
task actually engages it.
|
|
30
30
|
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
- [Architecture Decision Records (ADRs)](reference.md#architecture-decision-records-adrs)
|
|
34
|
-
- [Inline Documentation](reference.md#inline-documentation)
|
|
35
|
-
- [API Documentation](reference.md#api-documentation)
|
|
36
|
-
- [README Structure](reference.md#readme-structure)
|
|
37
|
-
- [Changelog Maintenance](reference.md#changelog-maintenance)
|
|
38
|
-
- [Pruning & Archiving](reference.md#pruning-archiving)
|
|
39
|
-
- [Documentation for Agents](reference.md#documentation-for-agents)
|
|
40
|
-
- [Common Rationalizations](reference.md#common-rationalizations)
|
|
41
|
-
- [Red Flags](reference.md#red-flags)
|
|
42
|
-
- [Verification](reference.md#verification)
|
|
31
|
+
- [Decisions-log layouts](reference.md#decisions-log-layouts)
|
|
32
|
+
- [Pruning & Archiving](reference.md#pruning--archiving)
|
|
@@ -81,6 +81,7 @@ sole evidence base. Cite its fields by name:
|
|
|
81
81
|
| `delegated[]` | `surface`, `lens`, `reason` |
|
|
82
82
|
| `clusters[]` | `adapter`, `category`, `rule`, `count`, `byVerdict`, `files` |
|
|
83
83
|
| `records[]` | `file`, `line`, `surface`, `target`, `rule`, `justification`, `ticketRefs`, `expires`, `addedAt`, `introduced`, `verdict`, `verdictBasis`, `probeBasis`, `permanentHint` |
|
|
84
|
+
| Shortcut markers | `adapter: shortcut-markers`, `surface: shortcut-marker`, `target` (the ceiling), `rule` (`has-trigger` / `no-trigger`), `justification` (the trigger) |
|
|
84
85
|
|
|
85
86
|
`verdict` is the engine's mechanical call, first match wins: `dead` (a probe
|
|
86
87
|
proved it exempts nothing), `expired` (its stated date is past), `orphaned`
|
|
@@ -150,6 +151,14 @@ judgment is the fifth, plus severity and routing.
|
|
|
150
151
|
justification that states a lasting reason is legitimately forever. Count
|
|
151
152
|
it in the inventory; never file it.
|
|
152
153
|
|
|
154
|
+
**Shortcut markers are the deferral ledger.** Each `shortcut: <ceiling>,
|
|
155
|
+
<trigger>` comment
|
|
156
|
+
([convention](helpers/code-quality-guardrails.md#deliberate-shortcuts)) is one
|
|
157
|
+
record, and its verdict is the action: `live` (basis `trigger-named`) is a
|
|
158
|
+
decision, so leave it; `expired` or `orphaned` means the trigger fired, so fix
|
|
159
|
+
the shortcut now; `unjustified` means no trigger, so add one or fix it. This
|
|
160
|
+
report is the ledger `/audit-to-stories` consumes.
|
|
161
|
+
|
|
153
162
|
**`unknown` is not `dead`.** An undecided probe is never evidence of
|
|
154
163
|
obsolescence. List `unknown` records under Undecided (below) and file one
|
|
155
164
|
only when you can show the answer from the code yourself.
|