@anhlp/alp-core 0.0.0-beta.2 → 0.0.1-beta.10
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/dist/backup.js +106 -4
- package/dist/bridges.d.ts +26 -0
- package/dist/bridges.js +96 -0
- package/dist/gate-ledger.d.ts +30 -0
- package/dist/gate-ledger.js +99 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2 -0
- package/dist/library-edit.d.ts +57 -5
- package/dist/library-edit.js +216 -11
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/migrations.js +1 -1
- package/dist/models.d.ts +74 -0
- package/dist/models.js +67 -1
- package/dist/packaged.d.ts +122 -0
- package/dist/packaged.js +125 -0
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +6 -6
- package/dist/providers.d.ts +4 -5
- package/dist/providers.js +26 -5
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/task-rows.d.ts +5 -0
- package/dist/task-rows.js +1 -1
- package/dist/tasks.d.ts +23 -4
- package/dist/tasks.js +103 -9
- package/dist/types.d.ts +3 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/user-settings.d.ts +2 -0
- package/dist/user-settings.js +40 -1
- package/dist/user-worktree.d.ts +29 -0
- package/dist/user-worktree.js +242 -0
- package/dist/validation.d.ts +1 -0
- package/dist/validation.js +35 -13
- package/package.json +34 -2
- package/src/backup.js +106 -5
- package/src/bridges.js +113 -0
- package/src/gate-ledger.js +125 -0
- package/src/index.js +1 -0
- package/src/library-edit.js +227 -12
- package/src/library.js +96 -6
- package/src/migrations.js +1 -1
- package/src/models.js +87 -1
- package/src/packaged.js +207 -0
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +7 -7
- package/src/providers.js +23 -7
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/task-rows.js +1 -1
- package/src/tasks.d.ts +23 -4
- package/src/tasks.js +137 -10
- package/src/types.d.ts +3 -0
- package/src/upgrade.js +54 -6
- package/src/user-settings.d.ts +2 -0
- package/src/user-settings.js +51 -1
- package/src/user-worktree.js +259 -0
- package/src/validation.d.ts +1 -0
- package/src/validation.js +43 -14
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -141
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +34 -0
- package/templates/skills/curate/SKILL.md +36 -0
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// check-boundaries: checks a JavaScript/TypeScript repository's imports against its architecture
|
|
3
|
+
// contract (docs/architecture/contract.json by default). No dependencies, reads only, runs nothing.
|
|
4
|
+
//
|
|
5
|
+
// node check-boundaries.mjs [--root DIR] [--contract FILE] [--base GIT-REF [--approved-by NAME]] [--json]
|
|
6
|
+
//
|
|
7
|
+
// Its help, usage and error strings stay ENGLISH on purpose (t-d11c item 3, decided by the user
|
|
8
|
+
// 2026-11-06), even though the documentation around it is Vietnamese: this output is what the
|
|
9
|
+
// Blueprint house rules tell a peer to attach to a handoff, so a project's CI may match on it.
|
|
10
|
+
// Translating it would be a behaviour change for user projects, not a documentation fix.
|
|
11
|
+
//
|
|
12
|
+
// Exit 0: no violations. Exit 1: violations (each printed as file:line), or with --base a change to
|
|
13
|
+
// the contract that loosens it (an added exception, a wider allow list, a removed denied package, a
|
|
14
|
+
// new ignore, a changed module) not acknowledged with --approved-by. Exit 2: the contract or the
|
|
15
|
+
// arguments are invalid. The contract format is in ../references/architecture-contract.md.
|
|
16
|
+
import { execFile } from 'node:child_process';
|
|
17
|
+
import { readFile, readdir, stat } from 'node:fs/promises';
|
|
18
|
+
import { promisify } from 'node:util';
|
|
19
|
+
import path from 'node:path';
|
|
20
|
+
|
|
21
|
+
const SOURCE = /\.(?:[cm]?[jt]sx?)$/;
|
|
22
|
+
const EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
|
|
23
|
+
const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.alp']);
|
|
24
|
+
const KEYS = ['modules', 'allow', 'denyPackages', 'ignore', 'exceptions', '$schema', 'description'];
|
|
25
|
+
|
|
26
|
+
class ContractError extends Error {}
|
|
27
|
+
const toPosix = file => file.split(path.sep).join('/');
|
|
28
|
+
|
|
29
|
+
/** A glob (`**`, `*`, `?`) as a RegExp over POSIX paths relative to the root. */
|
|
30
|
+
export function globRegExp(glob) {
|
|
31
|
+
let out = '';
|
|
32
|
+
for (let i = 0; i < glob.length; i++) {
|
|
33
|
+
const c = glob[i];
|
|
34
|
+
if (c === '*' && glob[i + 1] === '*') { out += glob[i + 2] === '/' ? '(?:.*/)?' : '.*'; i += glob[i + 2] === '/' ? 2 : 1; }
|
|
35
|
+
else if (c === '*') out += '[^/]*';
|
|
36
|
+
else if (c === '?') out += '[^/]';
|
|
37
|
+
else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
|
|
38
|
+
}
|
|
39
|
+
return new RegExp(`^${out}$`);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Checks the contract's shape; returns it with compiled globs. */
|
|
43
|
+
export function parseContract(value, source = 'contract') {
|
|
44
|
+
const fail = message => { throw new ContractError(`${source}: ${message}`); };
|
|
45
|
+
const list = (v, where) => { if (!Array.isArray(v) || !v.every(x => typeof x === 'string' && x.trim())) fail(`${where} must be a list of strings`); return v; };
|
|
46
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) fail('expected a JSON object');
|
|
47
|
+
for (const key of Object.keys(value)) if (!KEYS.includes(key)) fail(`unknown key '${key}'; expected ${KEYS.join(', ')}`);
|
|
48
|
+
if (!value.modules || typeof value.modules !== 'object' || !Object.keys(value.modules).length) fail('modules must name at least one module and its globs');
|
|
49
|
+
const modules = Object.entries(value.modules).map(([name, globs]) => ({ name, globs: list(globs, `modules.${name}`).map(globRegExp) }));
|
|
50
|
+
const names = new Set(modules.map(m => m.name));
|
|
51
|
+
const allow = value.allow ?? {};
|
|
52
|
+
if (typeof allow !== 'object' || Array.isArray(allow)) fail('allow must map a module to the modules it may import');
|
|
53
|
+
for (const [from, targets] of Object.entries(allow)) {
|
|
54
|
+
if (!names.has(from)) fail(`allow names unknown module '${from}'`);
|
|
55
|
+
for (const target of list(targets, `allow.${from}`)) if (!names.has(target)) fail(`allow.${from} names unknown module '${target}'`);
|
|
56
|
+
}
|
|
57
|
+
const denyPackages = value.denyPackages ?? {};
|
|
58
|
+
for (const [from, packages] of Object.entries(denyPackages)) { if (!names.has(from)) fail(`denyPackages names unknown module '${from}'`); list(packages, `denyPackages.${from}`); }
|
|
59
|
+
const ignore = list(value.ignore ?? [], 'ignore').map(globRegExp);
|
|
60
|
+
const exceptions = (value.exceptions ?? []).map((exception, index) => {
|
|
61
|
+
const at = `exceptions[${index}]`;
|
|
62
|
+
if (!exception || typeof exception !== 'object') fail(`${at} must be an object`);
|
|
63
|
+
for (const key of ['file', 'import', 'reason', 'approvedBy']) if (typeof exception[key] !== 'string' || !exception[key].trim()) fail(`${at}.${key} is required: an exception records what it allows, why, and who approved it`);
|
|
64
|
+
for (const key of Object.keys(exception)) if (!['file', 'import', 'reason', 'approvedBy', 'expires'].includes(key)) fail(`${at}: unknown key '${key}'; expected file, import, reason, approvedBy, expires`);
|
|
65
|
+
// An exception is narrow: one file, and not every import.
|
|
66
|
+
if (/[*?]/.test(exception.file)) fail(`${at}.file must name one file, not a pattern: an exception covers a single file`);
|
|
67
|
+
if (/^\*\*?(\/\*\*?)*$/.test(exception.import.trim())) fail(`${at}.import must name what may be imported, not everything`);
|
|
68
|
+
if (exception.expires !== undefined && (typeof exception.expires !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(exception.expires) || Number.isNaN(Date.parse(exception.expires)))) fail(`${at}.expires must be a date, YYYY-MM-DD`);
|
|
69
|
+
return { ...exception, fileRe: globRegExp(exception.file), importRe: globRegExp(exception.import) };
|
|
70
|
+
});
|
|
71
|
+
return { modules, allow, denyPackages, ignore, exceptions };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* The source with comments as spaces and every string's contents as `x`, newlines kept, so
|
|
76
|
+
* positions match the original: imports are found in this mask (an import inside a string or a
|
|
77
|
+
* comment is not one) and their specifiers read back from the original at the same offsets.
|
|
78
|
+
*/
|
|
79
|
+
export function maskSource(text) {
|
|
80
|
+
let out = '';
|
|
81
|
+
let i = 0;
|
|
82
|
+
while (i < text.length) {
|
|
83
|
+
const c = text[i], n = text[i + 1];
|
|
84
|
+
if (c === '/' && n === '/') { while (i < text.length && text[i] !== '\n') { out += ' '; i++; } continue; }
|
|
85
|
+
if (c === '/' && n === '*') { out += ' '; i += 2; while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) { out += text[i] === '\n' ? '\n' : ' '; i++; } if (i < text.length) { out += ' '; i += 2; } continue; }
|
|
86
|
+
if (c === '"' || c === "'" || c === '`') {
|
|
87
|
+
out += c; i++;
|
|
88
|
+
while (i < text.length && text[i] !== c && !(c !== '`' && text[i] === '\n')) {
|
|
89
|
+
if (text[i] === '\\' && i + 1 < text.length) { out += 'xx'; i += 2; continue; }
|
|
90
|
+
out += text[i] === '\n' ? '\n' : 'x'; i++;
|
|
91
|
+
}
|
|
92
|
+
if (i < text.length) { out += text[i]; i++; }
|
|
93
|
+
continue;
|
|
94
|
+
}
|
|
95
|
+
out += c; i++;
|
|
96
|
+
}
|
|
97
|
+
return out;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Every module specifier a source file imports, with its line: import/export from, import(), require(). */
|
|
101
|
+
export function importsOf(text) {
|
|
102
|
+
const masked = maskSource(text);
|
|
103
|
+
const found = [];
|
|
104
|
+
const patterns = [/(?<![.\w$])from\s*(['"])(x+)\1/g, /(?<![.\w$])import\s*(['"])(x+)\1/g, /(?<![.\w$])import\s*\(\s*(['"])(x+)\1\s*\)/g, /(?<![.\w$])require\s*\(\s*(['"])(x+)\1\s*\)/g];
|
|
105
|
+
for (const pattern of patterns) {
|
|
106
|
+
for (const match of masked.matchAll(pattern)) {
|
|
107
|
+
const at = match.index + match[0].lastIndexOf(match[2]);
|
|
108
|
+
found.push({ specifier: text.slice(at, at + match[2].length), line: masked.slice(0, at).split('\n').length });
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
return found.sort((a, b) => a.line - b.line);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** The package a bare specifier names: `@scope/name`, `name`, or `node:x`. */
|
|
115
|
+
const packageOf = specifier => specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
|
|
116
|
+
|
|
117
|
+
async function exists(file) { return stat(file).then(info => info.isFile(), () => false); }
|
|
118
|
+
|
|
119
|
+
/** A relative specifier resolved to a repository file, as TypeScript and Node would find it. */
|
|
120
|
+
async function resolveRelative(root, fromFile, specifier) {
|
|
121
|
+
const base = path.resolve(root, path.dirname(fromFile), specifier);
|
|
122
|
+
const candidates = [base, ...EXTENSIONS.map(ext => base + ext), ...EXTENSIONS.map(ext => path.join(base, `index${ext}`))];
|
|
123
|
+
// TypeScript's ESM style imports ./x.js for ./x.ts.
|
|
124
|
+
if (/\.[cm]?js$/.test(base)) candidates.push(...['.ts', '.tsx', '.mts', '.cts'].map(ext => base.replace(/\.[cm]?js$/, ext)));
|
|
125
|
+
for (const candidate of candidates) if (await exists(candidate)) return toPosix(path.relative(root, candidate));
|
|
126
|
+
return toPosix(path.relative(root, base));
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
async function sourceFiles(root, ignore) {
|
|
130
|
+
const files = [];
|
|
131
|
+
const walk = async relative => {
|
|
132
|
+
for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
|
|
133
|
+
const rel = relative ? `${relative}/${entry.name}` : entry.name;
|
|
134
|
+
if (entry.isDirectory()) { if (!SKIP_DIRS.has(entry.name)) await walk(rel); }
|
|
135
|
+
else if (entry.isFile() && SOURCE.test(entry.name) && !entry.name.endsWith('.d.ts') && !ignore.some(re => re.test(rel))) files.push(rel);
|
|
136
|
+
}
|
|
137
|
+
};
|
|
138
|
+
await walk('');
|
|
139
|
+
return files.sort();
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Checks `root` against its contract.
|
|
144
|
+
* @returns {Promise<{ files: number, violations: Array<{ file: string, line: number, from: string, to: string, specifier: string, rule: string }>, excepted: Array<object> }>}
|
|
145
|
+
*/
|
|
146
|
+
export async function checkBoundaries(root, contractValue, { today = new Date() } = {}) {
|
|
147
|
+
const contract = parseContract(contractValue);
|
|
148
|
+
const day = today.toISOString().slice(0, 10);
|
|
149
|
+
const used = new Set();
|
|
150
|
+
const moduleOf = file => contract.modules.find(m => m.globs.some(re => re.test(file)))?.name;
|
|
151
|
+
const violations = [];
|
|
152
|
+
const excepted = [];
|
|
153
|
+
let checked = 0;
|
|
154
|
+
for (const file of await sourceFiles(root, contract.ignore)) {
|
|
155
|
+
const from = moduleOf(file);
|
|
156
|
+
if (!from) continue;
|
|
157
|
+
checked++;
|
|
158
|
+
const text = await readFile(path.join(root, file), 'utf8');
|
|
159
|
+
for (const { specifier, line } of importsOf(text)) {
|
|
160
|
+
let finding;
|
|
161
|
+
if (specifier.startsWith('.') || specifier.startsWith('/')) {
|
|
162
|
+
const target = await resolveRelative(root, file, specifier);
|
|
163
|
+
const to = moduleOf(target);
|
|
164
|
+
const allowed = contract.allow[from];
|
|
165
|
+
if (to && to !== from && allowed && !allowed.includes(to)) finding = { file, line, from, to, specifier, target, rule: `${from} may import only ${allowed.length ? allowed.join(', ') : 'itself'}` };
|
|
166
|
+
} else {
|
|
167
|
+
const pkg = packageOf(specifier);
|
|
168
|
+
const denied = contract.denyPackages[from] ?? [];
|
|
169
|
+
if (denied.includes(pkg) || denied.includes(specifier)) finding = { file, line, from, to: pkg, specifier, target: pkg, rule: `${from} must not import package ${pkg}` };
|
|
170
|
+
}
|
|
171
|
+
if (!finding) continue;
|
|
172
|
+
const exception = contract.exceptions.find(e => e.fileRe.test(file) && e.importRe.test(finding.target));
|
|
173
|
+
if (exception) used.add(exception);
|
|
174
|
+
// An exception that has expired excuses nothing: the decision is to be made again.
|
|
175
|
+
if (exception && exception.expires && exception.expires < day) violations.push({ ...finding, rule: `${finding.rule} (its exception expired on ${exception.expires}; approved by ${exception.approvedBy})` });
|
|
176
|
+
else if (exception) excepted.push({ ...finding, reason: exception.reason, approvedBy: exception.approvedBy, ...(exception.expires ? { expires: exception.expires } : {}) });
|
|
177
|
+
else violations.push(finding);
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
// An exception nothing needs any more: listed for review, so stale permissions do not pile up.
|
|
181
|
+
const unused = contract.exceptions.filter(e => !used.has(e)).map(({ fileRe, importRe, ...e }) => e);
|
|
182
|
+
return { files: checked, violations, excepted, unusedExceptions: unused };
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
const key = exception => `${exception.file} -> ${exception.import}`;
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* The ways `current` loosens `base` (both contract objects): what a reviewer must approve. Tightening
|
|
189
|
+
* (a new denied package, a narrower allow list, a removed exception) is not listed.
|
|
190
|
+
* @returns {string[]}
|
|
191
|
+
*/
|
|
192
|
+
export function contractLoosening(base, current) {
|
|
193
|
+
const changes = [];
|
|
194
|
+
const modules = new Set([...Object.keys(base.modules ?? {}), ...Object.keys(current.modules ?? {})]);
|
|
195
|
+
for (const name of modules) {
|
|
196
|
+
const before = JSON.stringify([...(base.modules?.[name] ?? [])].sort());
|
|
197
|
+
const after = JSON.stringify([...(current.modules?.[name] ?? [])].sort());
|
|
198
|
+
if (base.modules?.[name] && before !== after) changes.push(`modules.${name} changed from ${before} to ${after}: files may have left the module`);
|
|
199
|
+
}
|
|
200
|
+
for (const [name, targets] of Object.entries(base.allow ?? {})) {
|
|
201
|
+
if (!Object.hasOwn(current.allow ?? {}, name)) { changes.push(`allow.${name} was removed: ${name} may now import any module`); continue; }
|
|
202
|
+
for (const target of current.allow[name]) if (!targets.includes(target)) changes.push(`allow.${name} adds ${target}`);
|
|
203
|
+
}
|
|
204
|
+
for (const [name, packages] of Object.entries(base.denyPackages ?? {})) {
|
|
205
|
+
for (const pkg of packages) if (!(current.denyPackages?.[name] ?? []).includes(pkg)) changes.push(`denyPackages.${name} no longer denies ${pkg}`);
|
|
206
|
+
}
|
|
207
|
+
for (const glob of current.ignore ?? []) if (!(base.ignore ?? []).includes(glob)) changes.push(`ignore adds ${glob}`);
|
|
208
|
+
const before = new Map((base.exceptions ?? []).map(e => [key(e), e]));
|
|
209
|
+
for (const exception of current.exceptions ?? []) {
|
|
210
|
+
const old = before.get(key(exception));
|
|
211
|
+
if (!old) changes.push(`exception added: ${key(exception)} (${exception.reason}; approved by ${exception.approvedBy}${exception.expires ? `; expires ${exception.expires}` : ''})`);
|
|
212
|
+
else if (old.reason !== exception.reason || old.approvedBy !== exception.approvedBy || (old.expires ?? '') !== (exception.expires ?? '')) changes.push(`exception changed: ${key(exception)} (now ${exception.reason}; approved by ${exception.approvedBy}${exception.expires ? `; expires ${exception.expires}` : '; no expiry'})`);
|
|
213
|
+
}
|
|
214
|
+
return changes;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** The contract as git has it at `ref`, or undefined when it did not exist there. */
|
|
218
|
+
async function contractAt(root, ref, relative) {
|
|
219
|
+
try {
|
|
220
|
+
const { stdout } = await promisify(execFile)('git', ['-C', root, 'show', `${ref}:${relative}`], { maxBuffer: 4 * 1024 * 1024 });
|
|
221
|
+
try { return JSON.parse(stdout); } catch (error) { throw new ContractError(`${relative} at ${ref}: ${error.message}`); }
|
|
222
|
+
} catch (error) {
|
|
223
|
+
if (error instanceof ContractError) throw error;
|
|
224
|
+
if (/exists on disk, but not in|does not exist in|path .* does not exist/.test(String(error.stderr ?? ''))) return undefined;
|
|
225
|
+
throw new ContractError(`cannot read ${relative} at ${ref}: ${String(error.stderr ?? error.message).trim()}`);
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
async function main(argv) {
|
|
230
|
+
const VALUED = ['--root', '--contract', '--base', '--approved-by'];
|
|
231
|
+
const arg = name => { const at = argv.indexOf(name); if (at < 0) return undefined; const value = argv[at + 1]; if (value === undefined || value.startsWith('--')) throw new ContractError(`${name} needs a value`); return value; };
|
|
232
|
+
const unknown = argv.filter((a, i) => (a.startsWith('--') && !['--json', ...VALUED].includes(a)) || (!a.startsWith('--') && !VALUED.includes(argv[i - 1])));
|
|
233
|
+
if (unknown.length) throw new ContractError(`unknown argument ${unknown[0]}; use --root DIR, --contract FILE, --base GIT-REF, --approved-by NAME, --json`);
|
|
234
|
+
if (argv.includes('--approved-by') && !argv.includes('--base')) throw new ContractError('--approved-by acknowledges contract changes found with --base');
|
|
235
|
+
const root = path.resolve(arg('--root') ?? process.cwd());
|
|
236
|
+
const contractFile = path.resolve(root, arg('--contract') ?? 'docs/architecture/contract.json');
|
|
237
|
+
let text;
|
|
238
|
+
try { text = await readFile(contractFile, 'utf8'); }
|
|
239
|
+
catch { throw new ContractError(`no contract at ${contractFile}; write one (see references/architecture-contract.md) or pass --contract`); }
|
|
240
|
+
let value;
|
|
241
|
+
try { value = JSON.parse(text); } catch (error) { throw new ContractError(`${contractFile}: ${error.message}`); }
|
|
242
|
+
const result = await checkBoundaries(root, value);
|
|
243
|
+
const relative = toPosix(path.relative(root, contractFile));
|
|
244
|
+
// A weaker contract makes the check pass too: with --base, loosening it needs an acknowledged review.
|
|
245
|
+
const base = arg('--base');
|
|
246
|
+
const approvedBy = arg('--approved-by');
|
|
247
|
+
let contractChanges = [];
|
|
248
|
+
if (base) {
|
|
249
|
+
const before = await contractAt(root, base, relative);
|
|
250
|
+
contractChanges = before === undefined ? [] : contractLoosening(before, value);
|
|
251
|
+
}
|
|
252
|
+
const unreviewed = contractChanges.length && !approvedBy;
|
|
253
|
+
if (argv.includes('--json')) console.log(JSON.stringify({ contract: relative, ...result, ...(base ? { base, contractChanges, ...(approvedBy ? { approvedBy } : {}) } : {}) }, null, 2));
|
|
254
|
+
else {
|
|
255
|
+
for (const v of result.violations) console.log(`${v.file}:${v.line} ${v.from} -> ${v.to} (${v.specifier}): ${v.rule}`);
|
|
256
|
+
for (const e of result.excepted) console.log(`${e.file}:${e.line} ${e.from} -> ${e.to}: allowed by exception (${e.reason}; approved by ${e.approvedBy}${e.expires ? `; expires ${e.expires}` : ''})`);
|
|
257
|
+
for (const e of result.unusedExceptions) console.log(`unused exception: ${key(e)} (${e.reason}; approved by ${e.approvedBy}): nothing needs it; remove it`);
|
|
258
|
+
for (const change of contractChanges) console.log(`contract change since ${base}${approvedBy ? `, approved by ${approvedBy}` : ', needs review'}: ${change}`);
|
|
259
|
+
console.log(`${result.files} file(s) checked against ${relative}: ${result.violations.length} violation(s), ${result.excepted.length} by exception${base ? `, ${contractChanges.length} contract change(s) since ${base}${unreviewed ? ' not reviewed' : ''}` : ''}`);
|
|
260
|
+
if (unreviewed) console.log('A loosened contract is a decision for the owner of these rules: get it reviewed, then run with --approved-by NAME to record who approved it. Do not edit the contract to make a check pass.');
|
|
261
|
+
}
|
|
262
|
+
return result.violations.length || unreviewed ? 1 : 0;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('check-boundaries.mjs')) {
|
|
266
|
+
main(process.argv.slice(2)).then(code => { process.exitCode = code; }, error => {
|
|
267
|
+
console.error(error instanceof ContractError ? `check-boundaries: ${error.message}` : error);
|
|
268
|
+
process.exitCode = 2;
|
|
269
|
+
});
|
|
270
|
+
}
|
|
@@ -1,36 +1,36 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: goal-griller
|
|
3
|
-
description:
|
|
3
|
+
description: Biến một yêu cầu chưa đủ rõ của người dùng thành một task contract kiểm chứng được. Dùng khi main tiếp nhận yêu cầu mà việc thiếu kết quả mong muốn, phạm vi hay bằng chứng nghiệm thu sẽ làm đổi cách thực thi một cách đáng kể; bỏ qua khi yêu cầu đã rõ.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Làm rõ kết quả cần đạt
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
lead
|
|
10
|
-
|
|
8
|
+
Skill này phục vụ người sở hữu đầu tiếp xúc với người dùng. Trong quy trình khởi đầu đó
|
|
9
|
+
là main; lead và peer trả các quyết định còn thiếu về cho agent giao việc chứ không tự mở
|
|
10
|
+
một cuộc trao đổi riêng với người dùng.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
12
|
+
Đọc yêu cầu, các quyết định đã có, ALP.md, và vài artifact cục bộ liên quan. Tách kết quả
|
|
13
|
+
mong muốn ra khỏi implementation được gợi ý. Hãy xác lập:
|
|
14
14
|
|
|
15
|
-
- Outcome:
|
|
16
|
-
- Evidence:
|
|
17
|
-
- Scope:
|
|
18
|
-
- Context:
|
|
19
|
-
- Verification:
|
|
20
|
-
- Completion/blockers:
|
|
15
|
+
- Outcome: trạng thái quan sát được mà người dùng muốn.
|
|
16
|
+
- Evidence: một phép kiểm, artifact hay phép đo cho thấy kết quả đó.
|
|
17
|
+
- Scope: cái gì được phép đổi và cái gì người dùng yêu cầu giữ nguyên.
|
|
18
|
+
- Context: các nguồn cần có để ra quyết định đầu tiên.
|
|
19
|
+
- Verification: một vòng phản hồi nhanh và các phép kiểm cuối nếu có.
|
|
20
|
+
- Completion/blockers: khi nào công việc xong và cái gì cần một quyết định của người dùng.
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
22
|
+
Hãy suy ra các chi tiết thường lệ từ repository và từ thẩm quy���n đã có. Chỉ hỏi những câu
|
|
23
|
+
mà câu trả lời làm đổi phạm vi, hành vi, chi phí, hay một quyết định có hệ quả.
|
|
24
|
+
Gộp các câu hỏi độc lập lại cho gọn và đưa ra một mặc định hợp lý ở chỗ hữu ích.
|
|
25
|
+
Vẫn tiếp tục công việc độc lập đã được cấp quyền trong lúc chờ; thời gian trôi qua không
|
|
26
|
+
sinh ra câu trả lời bắt buộc.
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
"production
|
|
30
|
-
|
|
31
|
-
|
|
28
|
+
Đừng cử một người đi nghiên cứu để tự bịa ra nghĩa của những chữ như "tốt hơn" hay
|
|
29
|
+
"sẵn sàng cho production" khi chính kết quả cần đạt phải do người dùng phán xét. Ngược lại,
|
|
30
|
+
đừng bắt người dùng chỉ ra một câu lệnh build hay một đường dẫn file mà bằng chứng cục bộ
|
|
31
|
+
xác lập được.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
Hãy làm ra một contract tương xứng, ví dụ:
|
|
34
34
|
|
|
35
35
|
```text
|
|
36
36
|
Outcome: observable result
|
|
@@ -43,7 +43,7 @@ Done: completion condition
|
|
|
43
43
|
Blocked if: material missing decision or prerequisite
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
46
|
+
Với một task đã được cấp quyền, một contract rõ ràng là đủ để tiến hành; skill này không
|
|
47
|
+
thêm cổng duyệt nào. Nếu chỉ được yêu cầu soạn một contract, hãy trả nó về mà không bắt
|
|
48
|
+
đầu hiện thực. Chuyển một task nhiều mục sang sequence-execution-plan, hoặc một việc được
|
|
49
|
+
giao đơn lẻ sang prompt-leverage, và chỉ đọc skill kế tiếp khi cần.
|
|
@@ -1,37 +1,39 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: prompt-leverage
|
|
3
|
-
description:
|
|
3
|
+
description: Chuyển một task thành một brief giao việc tự chứa, không làm đổi ý định của người dùng và không định sẵn giải pháp. Dùng trước khi main giao cho lead hoặc lead giao cho peer, hoặc khi được yêu cầu làm tốt hơn một prompt thực thi.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Soạn một brief làm được việc
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
Xác định kết quả được yêu cầu và trách nhiệm của người nhận. Giữ nguyên các ràng buộc thật
|
|
9
|
+
sự của người dùng, nhưng phân biệt chúng với các lựa chọn thiết kế hiện tại mà người nhận
|
|
10
|
+
có quyền chất vấn. Đừng gieo trước verdict cho một reviewer, và đừng biến một implementation
|
|
11
|
+
mình thích thành một yêu cầu bịa ra.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
13
|
+
Một brief hữu ích cung cấp root, kết quả cần đạt, context liên quan, đường dẫn sở hữu/bị loại,
|
|
14
|
+
thẩm quyền, các phụ thuộc quan trọng, tài nguyên, kiểm chứng, và handoff mong đợi.
|
|
15
|
+
Dùng [định dạng brief](references/brief-template.md) cho các việc được giao có khối lượng đáng kể;
|
|
16
|
+
gộp các field lại với một task nhỏ. Một base SHA thật thì hữu ích trong một repository Git
|
|
17
|
+
nhưng không bắt buộc với một project chỉ gồm file thường. Đừng bao giờ bịa ra một cái.
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
Phần kiểm chứng phải mô tả hành vi quan sát được và, khi đã biết, cả phép kiểm chạy được của
|
|
20
|
+
nó. Nếu còn phải đi tìm câu lệnh, hãy nói rõ nên xác lập nó từ repository bằng cách nào. Đừng
|
|
21
|
+
bịa ra một câu lệnh test chỉ để điền cho đủ field.
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
smart-commits.
|
|
26
|
-
|
|
23
|
+
Chọn skill đã cài phù hợp theo loại việc và nêu tên nó trong brief:
|
|
24
|
+
nghiên cứu -> xia; chẩn đoán/regression -> bug-loop; một handoff có quyền commit ->
|
|
25
|
+
smart-commits. Đừng đòi những skill không có trong gói của người nhận. Một reviewer có thể
|
|
26
|
+
xem xét một bản ứng viên đang có mà không cần thêm nghi thức skill nào.
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
28
|
+
Gửi toàn bộ brief qua tool giao việc mà runtime của bạn thật sự cung cấp, cho một agent đã được
|
|
29
|
+
cấp quyền. Cách chọn model và effort cho người nhận, và việc có phải chọn hay không, lấy từ
|
|
30
|
+
instruction runtime của bạn (model profile của người nhận, catalog của runtime); đừng giả định
|
|
31
|
+
người nhận chạy trên model của bạn. Yêu cầu chỉ đọc cho việc nghiên cứu/review ở chỗ phù hợp.
|
|
32
|
+
Việc hiện thực cần workspace-write ở cả cha và con. Việc giao có thể chạy nền và trả kết quả
|
|
33
|
+
về sau; người nhận có thể hỏi lại hoặc không, tuỳ kênh mà runtime có. Vì vậy hãy đưa vào brief
|
|
34
|
+
mọi thứ cần thiết để làm xong việc mà không phải hỏi lại.
|
|
33
35
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
36
|
+
Skill này không cấp thẩm quyền mới nào và không bao giờ lách đồ thị định tuyến đã cấu hình. Nếu
|
|
37
|
+
chỉ được yêu cầu làm tốt hơn một prompt, hãy trả prompt về. Nếu việc giao đã được cấp quyền,
|
|
38
|
+
hãy gửi nó bằng tool thật của runtime sau khi soạn xong. Những năng lực còn thiếu phải được báo
|
|
39
|
+
cáo, không phải giả lập ra.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Định dạng brief và handoff
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Dùng đủ chi tiết để một người làm độc lập có thể làm việc hiệu quả, mà không áp đặt một giải
|
|
4
|
+
pháp chưa được kiểm chứng. Context có sẵn gồm ALP.md và hướng dẫn riêng của agent được chọn;
|
|
5
|
+
toàn bộ transcript của agent cha thì không tự động có.
|
|
6
6
|
|
|
7
7
|
```text
|
|
8
8
|
Task and recipient:
|
|
@@ -20,8 +20,8 @@ Candidate/base revision, if applicable:
|
|
|
20
20
|
Return: outcome, artifact, scope, actual checks/results, risks, ownership status.
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
23
|
+
Với review chỉ đọc, hãy cấp bản ứng viên/artifact và các tiêu chí nghiệm thu độc lập. Với một
|
|
24
|
+
bản sửa, hãy đưa kèm phát hiện cụ thể và bằng chứng trước đó. Với một việc được giao làm tiếp,
|
|
25
|
+
hãy đưa kèm các phát hiện cần thiết từ handoff trước, vì agent con kế tiếp là một phiên mới.
|
|
26
|
+
Người nhận bị chặn thì nên trả về chỗ chặn của mình cùng phần việc độc lập đã làm xong, chứ
|
|
27
|
+
đừng ngồi chờ một hộp thư không tồn tại.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: release-readiness
|
|
3
|
+
description: "Đánh giá xem một build hay version cụ thể đã sẵn sàng phát hành chưa và trả về verdict GO, CONDITIONAL hay NO-GO kèm bằng chứng cho từng tiêu chí: CI, test, artifact, bảo mật, tương thích, migration, rollback, vận hành. Dùng khi được hỏi một version có phát hành được không. Không dùng để tag hay publish, để review một thay đổi đơn lẻ (security-review), hay để sửa lỗi (bug-loop)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Mức sẵn sàng phát hành
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
|
|
10
|
+
- Có người hỏi liệu một commit, build hay version có phát hành được không.
|
|
11
|
+
- Một bản ứng viên phát hành cần một quyết định go/no-go được ghi lại trước khi người dùng cho
|
|
12
|
+
phép xuất bản.
|
|
13
|
+
- Một reviewer được yêu cầu soát lại một checklist phát hành hoặc một tuyên bố đã có.
|
|
14
|
+
|
|
15
|
+
## Không dùng cho
|
|
16
|
+
|
|
17
|
+
- Tag, publish, push hay deploy: những việc đó cần người dùng cho phép rõ ràng và
|
|
18
|
+
nằm ngoài skill này.
|
|
19
|
+
- Một lượt soát bảo mật cho một thay đổi: dùng security-review, rồi đưa các phát hiện của nó
|
|
20
|
+
vào đây.
|
|
21
|
+
- Sửa một test hay build đang fail: dùng bug-loop.
|
|
22
|
+
|
|
23
|
+
## Điều kiện tiên quyết
|
|
24
|
+
|
|
25
|
+
- Bản ứng viên chính xác: commit SHA (và tag hay chuỗi version nếu đã chọn).
|
|
26
|
+
- Đọc ALP.md và hướng dẫn của project để biết quy trình phát hành, CI, câu lệnh build
|
|
27
|
+
và test, cùng mọi checklist phát hành đang có.
|
|
28
|
+
|
|
29
|
+
## Quy trình
|
|
30
|
+
|
|
31
|
+
1. Ghim bản ứng viên: ghi lại commit SHA, nhánh, chuỗi version, và cây làm việc có sạch
|
|
32
|
+
hay không. Mọi phép kiểm sau đó đều quy về SHA này.
|
|
33
|
+
2. Trạng thái CI: xác nhận các check bắt buộc đã pass trên đúng commit đó, không phải một
|
|
34
|
+
commit lân cận hay một đầu nhánh đã dịch chuyển. Ghi lại tên check và link hoặc output.
|
|
35
|
+
3. Test: chạy hoặc tìm kết quả của bộ test phát hành của project trên SHA đó. Ghi lại câu
|
|
36
|
+
lệnh, số pass/fail, test bị skip, và các test đã biết là chập chờn.
|
|
37
|
+
4. Artifact build: xác nhận chúng được build từ SHA đó, mang đúng dấu version, và khớp các
|
|
38
|
+
checksum đã ghi. Ghi lại mọi artifact chưa xem xét.
|
|
39
|
+
5. Bảo mật: liệt kê các phát hiện còn mở ảnh hưởng tới bản ứng viên (từ security-review, từ
|
|
40
|
+
các công cụ audit mà phiên cho phép, từ issue tracker) kèm mức nghiêm trọng và trạng thái.
|
|
41
|
+
6. Tương thích: các thay đổi về protocol, public API, CLI, config và định dạng dữ liệu kể từ
|
|
42
|
+
bản phát hành trước, kèm việc bên tiêu thụ buộc phải làm gì.
|
|
43
|
+
7. Migration: các migration về dữ liệu hay config, từng cái đã được test chưa, và có đảo ngược
|
|
44
|
+
được không; nếu không đảo ngược được thì bản backup hay bản sửa tiến nào phủ cho nó.
|
|
45
|
+
8. Kế hoạch rollback: các bước cụ thể và ai thực thi được; rollback đã được diễn thử chưa.
|
|
46
|
+
9. Mức sẵn sàng vận hành: release note, tài liệu, monitoring và cảnh báo cho hành vi mới,
|
|
47
|
+
người on-call hay người sở hữu đã biết chưa.
|
|
48
|
+
10. Quyết định verdict và viết nó bằng mẫu verdict.
|
|
49
|
+
|
|
50
|
+
## Ràng buộc
|
|
51
|
+
|
|
52
|
+
- Mọi tiêu chí đều có bằng chứng (câu lệnh và kết quả, link, hay đường dẫn file) hoặc được
|
|
53
|
+
đánh dấu "not verified" kèm lý do. Đừng bao giờ ghi PASS cho thứ chưa chạy
|
|
54
|
+
hoặc chưa xem xét.
|
|
55
|
+
- Bằng chứng phải thuộc về SHA đã ghim. Kết quả từ một commit khác là "not
|
|
56
|
+
verified".
|
|
57
|
+
- Đừng tag, publish, push, deploy hay nâng version. Hãy báo verdict; main
|
|
58
|
+
xin phép người dùng cho mọi hành động phát hành.
|
|
59
|
+
- Đừng cài công cụ hay sửa config CI để một phép kiểm pass.
|
|
60
|
+
- Các agent chỉ đọc chỉ đánh giá và báo cáo.
|
|
61
|
+
|
|
62
|
+
## Kiểm chứng
|
|
63
|
+
|
|
64
|
+
- Verdict tuân theo đúng quy tắc: bất kỳ tiêu chí chặn nào fail thì là NO-GO; các mục không
|
|
65
|
+
chặn mà chưa kiểm chứng hoặc fail, nếu có người sở hữu và hạn chót, thì có thể là
|
|
66
|
+
CONDITIONAL; chỉ GO khi mọi tiêu chí chặn đều pass kèm bằng chứng.
|
|
67
|
+
- Mỗi điều kiện của CONDITIONAL nêu rõ một người sở hữu và cái gì đóng được nó.
|
|
68
|
+
- Handoff bản báo cáo verdict cho agent giao việc (peer -> lead -> main).
|
|
69
|
+
|
|
70
|
+
## Xử lý khi thất bại
|
|
71
|
+
|
|
72
|
+
- CI hay artifact không tới được từ phiên này: đánh dấu "not verified", nêu tên người
|
|
73
|
+
xác nhận được, và đừng ra verdict GO.
|
|
74
|
+
- SHA ứng viên đổi giữa lúc đang đánh giá: bắt đầu lại từ bước 1 với SHA mới.
|
|
75
|
+
- Tìm thấy một lỗi chặn: ra verdict NO-GO kèm bằng chứng; đề xuất các việc tiếp theo bằng
|
|
76
|
+
bug-loop hay security-review như những task riêng.
|
|
77
|
+
- Project không có đường rollback: đó là một khoảng trống chặn, trừ khi người dùng chấp nhận
|
|
78
|
+
rủi ro một cách rõ ràng; hãy ghi lại ai đã chấp nhận.
|
|
79
|
+
|
|
80
|
+
## Tài liệu tham chiếu
|
|
81
|
+
|
|
82
|
+
- [references/checklist.md](references/checklist.md) — đọc khi đánh giá từng tiêu chí (bước 2-9).
|
|
83
|
+
- [references/verdict-template.md](references/verdict-template.md) — đọc khi quyết định và viết verdict (bước 10).
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Tiêu chí sẵn sàng phát hành
|
|
2
|
+
|
|
3
|
+
Đọc khi đánh giá từng tiêu chí phát hành và khi quyết định tiêu chí nào là chặn.
|
|
4
|
+
|
|
5
|
+
Dưới đây là mặc định; checklist phát hành của chính project hoặc ALP.md ghi đè trạng thái
|
|
6
|
+
chặn. Các giá trị trạng thái: PASS, FAIL, NOT VERIFIED, N/A (kèm lý do).
|
|
7
|
+
|
|
8
|
+
| # | Tiêu chí | Chặn | Bằng chứng được tính | Bẫy thường gặp |
|
|
9
|
+
| --- | --- | --- | --- | --- |
|
|
10
|
+
| 1 | Bản ứng viên đã ghim | có | SHA, chuỗi version, cây sạch (`git status`, `git rev-parse HEAD`) | Đánh giá một tên nhánh thay vì một SHA |
|
|
11
|
+
| 2 | CI xanh trên đúng SHA | có | Tên các check bắt buộc kèm trạng thái cho SHA đó | Xanh trên head của PR, không phải trên merge commit; một check bắt buộc bị skip |
|
|
12
|
+
| 3 | Bộ test phát hành | có | Câu lệnh, số pass/fail/skip, chạy trên SHA đó | Test bị skip giấu trong tổng số; test chập chờn chạy lại tới khi xanh mà không ghi chú |
|
|
13
|
+
| 4 | Artifact từ SHA | có | Log build hay provenance nêu tên SHA; dấu version trong artifact; checksum khớp | Artifact build lại cục bộ từ một cây bẩn; artifact cache cũ |
|
|
14
|
+
| 5 | Phát hiện bảo mật | có, với critical/high | Danh sách phát hiện còn mở kèm mức nghiêm trọng và trạng thái | Phát hiện theo dõi ở nơi khác mà không kiểm; chưa chạy audit mà đã gọi là sạch |
|
|
15
|
+
| 6 | Tương thích protocol/API | có, nếu phá vỡ mà chưa thông báo | Diff của bề mặt public kể từ bản phát hành trước; mục changelog | Bỏ sót thay đổi về config hay cờ CLI |
|
|
16
|
+
| 7 | Migration đã test | có, nếu có migration | Migration chạy trên dữ liệu tiêu biểu; kết quả | Chỉ test trên dữ liệu rỗng |
|
|
17
|
+
| 8 | Migration đảo ngược được | có, nếu không đảo ngược được mà không có backup | Test migration xuống, hoặc kế hoạch backup và sửa tiến | Cho rằng đảo ngược được mà không chạy thử |
|
|
18
|
+
| 9 | Kế hoạch rollback | có | Các bước đã viết ra, ai chạy chúng, kết quả diễn thử nếu có | Rollback bị một migration không đảo ngược được chặn lại |
|
|
19
|
+
| 10 | Release note | không | Đường dẫn hay link; phủ các thay đổi phá vỡ và các migration | Note sinh từ commit, thiếu phần ảnh hưởng tới người dùng |
|
|
20
|
+
| 11 | Tài liệu đã cập nhật | không | Các đường dẫn tài liệu đã đổi | Tài liệu mô tả hành vi chưa phát hành |
|
|
21
|
+
| 12 | Monitoring và cảnh báo | không, có với thay đổi nhiều rủi ro | Tên dashboard hay cảnh báo phủ hành vi mới | Một kiểu lỗi mới mà không có tín hiệu nào |
|
|
22
|
+
| 13 | On-call / người sở hữu đã biết | không | Người sở hữu được nêu tên và đã xác nhận | Khung giờ phát hành nằm ngoài lúc người sở hữu có mặt |
|
|
23
|
+
|
|
24
|
+
## Thu bằng chứng
|
|
25
|
+
|
|
26
|
+
- Ưu tiên các câu lệnh có output tái lập được: ghi lại dòng lệnh và các dòng output liên quan,
|
|
27
|
+
không phải một bản diễn giải.
|
|
28
|
+
- Khi CI hay nơi lưu artifact không tới được từ phiên này, hãy xin agent giao việc một link
|
|
29
|
+
hoặc một bản xuất; tới lúc đó tiêu chí vẫn là NOT VERIFIED.
|
|
30
|
+
- Dùng lại output của security-review cho tiêu chí 5 nếu nó đã phủ SHA ứng viên;
|
|
31
|
+
nếu không thì nêu rõ khoảng trống về độ phủ của nó.
|
|
32
|
+
- N/A cần một lý do ("không có migration: không có thay đổi schema hay định dạng config kể từ
|
|
33
|
+
v1.4.0, đã kiểm bằng diff của migrations/ và schema config").
|
|
34
|
+
|
|
35
|
+
## Ghi đè trạng thái chặn
|
|
36
|
+
|
|
37
|
+
- Một quy tắc của project có thể biến một mục không chặn thành chặn (ví dụ release note bị
|
|
38
|
+
chính sách yêu cầu). Hãy dẫn quy tắc đó.
|
|
39
|
+
- Hạ một mục chặn xuống không chặn thì cần một quyết định rõ ràng từ người dùng hoặc từ một
|
|
40
|
+
người sở hữu mà người dùng nêu tên; hãy ghi lại ai đã quyết.
|