vouchington-tooling 0.67.0 → 0.69.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/README.md +55 -0
- package/dist/cli/commands/coverage-scope-check.d.mts +7 -0
- package/dist/cli/commands/coverage-scope-check.mjs +69 -0
- package/dist/cli/commands/docker-image-mirror.d.mts +13 -0
- package/dist/cli/commands/docker-image-mirror.mjs +39 -0
- package/dist/cli/commands/trivy-policy.d.mts +12 -0
- package/dist/cli/commands/trivy-policy.mjs +76 -0
- package/dist/cli/index.mjs +6 -0
- package/dist/cli/parse-forwarded-commands.d.mts +7 -69
- package/dist/cli/parse-forwarded-commands.mjs +30 -47
- package/dist/cli/parse.d.mts +9 -0
- package/dist/cli/usage-text-coverage-scope.d.mts +1 -0
- package/dist/cli/usage-text-coverage-scope.mjs +7 -0
- package/dist/cli/usage-text-policy.d.mts +2 -0
- package/dist/cli/usage-text-policy.mjs +25 -0
- package/dist/cli/usage-text.d.mts +1 -1
- package/dist/cli/usage-text.mjs +3 -3
- package/dist/coverage-scope/check.d.mts +16 -0
- package/dist/coverage-scope/check.mjs +26 -0
- package/dist/coverage-scope/coverage-scope.test-helpers.d.mts +4 -0
- package/dist/coverage-scope/coverage-scope.test-helpers.mjs +38 -0
- package/dist/coverage-scope/index.d.mts +3 -0
- package/dist/coverage-scope/index.mjs +2 -0
- package/dist/coverage-scope/mismatches.d.mts +3 -0
- package/dist/coverage-scope/mismatches.mjs +17 -0
- package/dist/docker-image-mirror/images.d.mts +25 -0
- package/dist/docker-image-mirror/images.mjs +108 -0
- package/dist/docker-image-mirror/index.d.mts +16 -0
- package/dist/docker-image-mirror/index.mjs +39 -0
- package/dist/index.d.mts +4 -0
- package/dist/index.mjs +2 -0
- package/dist/trivy-policy/background.d.mts +1 -0
- package/dist/trivy-policy/background.mjs +24 -0
- package/dist/trivy-policy/gate.d.mts +5 -0
- package/dist/trivy-policy/gate.mjs +92 -0
- package/dist/trivy-policy/index.d.mts +15 -0
- package/dist/trivy-policy/index.mjs +48 -0
- package/dist/trivy-policy/invocations.d.mts +4 -0
- package/dist/trivy-policy/invocations.mjs +76 -0
- package/dist/trivy-policy/options.d.mts +26 -0
- package/dist/trivy-policy/options.mjs +17 -0
- package/dist/trivy-policy/registry.d.mts +7 -0
- package/dist/trivy-policy/registry.mjs +48 -0
- package/dist/trivy-policy/scan.d.mts +5 -0
- package/dist/trivy-policy/scan.mjs +59 -0
- package/dist/trivy-policy/shell.d.mts +2 -0
- package/dist/trivy-policy/shell.mjs +62 -0
- package/package.json +17 -1
- package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
- package/skills/agent-workflow/references/implementation.md +5 -0
- package/skills/manifest.json +20 -20
- package/skills/pr-description/SKILL.md +26 -11
- package/skills/pr-description/references/examples.md +53 -0
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { type TrivyPolicyOptions } from './options.mts';
|
|
2
|
+
export type Ignore = Partial<Record<'expired_at' | 'id' | 'purls' | 'statement', unknown>>;
|
|
3
|
+
export type IgnoreRegistry = {
|
|
4
|
+
vulnerabilities?: Ignore[];
|
|
5
|
+
};
|
|
6
|
+
export declare function parseIgnoreRegistry(source: string): IgnoreRegistry;
|
|
7
|
+
export declare function validateIgnoreRegistry(registry: IgnoreRegistry, options?: TrivyPolicyOptions): void;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { parse } from 'yaml';
|
|
2
|
+
import { resolveOptions } from "./options.mjs";
|
|
3
|
+
const PART = String.raw `(?:[A-Za-z0-9._~+-]|%[0-9A-Fa-f]{2})+`;
|
|
4
|
+
const VALUE = String.raw `(?:[A-Za-z0-9._~+:-]|%[0-9A-Fa-f]{2})+`;
|
|
5
|
+
const QUALIFIER = String.raw `${PART}=${VALUE}`;
|
|
6
|
+
const OS_PURL = new RegExp(String.raw `^pkg:(deb|apk|rpm)\/${PART}\/${PART}@${VALUE}(?:\?${QUALIFIER}(?:&${QUALIFIER})*)?$`);
|
|
7
|
+
// The registry's fields are all re-validated below with an explicit `typeof` check plus a regex,
|
|
8
|
+
// so the default YAML core schema is safe: a value it coerces to a non-string still fails.
|
|
9
|
+
export function parseIgnoreRegistry(source) {
|
|
10
|
+
return parse(source);
|
|
11
|
+
}
|
|
12
|
+
function isCalendarDate(value) {
|
|
13
|
+
if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
|
|
14
|
+
return false;
|
|
15
|
+
const date = new Date(`${value}T00:00:00Z`);
|
|
16
|
+
return !Number.isNaN(date.valueOf()) && date.toISOString().slice(0, 10) === value;
|
|
17
|
+
}
|
|
18
|
+
function validateExpiry(expiredAt, prefix, options) {
|
|
19
|
+
const { now, maxExpiryDays } = resolveOptions(options);
|
|
20
|
+
if (typeof expiredAt !== 'string' || !isCalendarDate(expiredAt))
|
|
21
|
+
throw new Error(`${prefix}.expired_at must be a UTC calendar date`);
|
|
22
|
+
const today = now.toISOString().slice(0, 10);
|
|
23
|
+
if (expiredAt <= today)
|
|
24
|
+
throw new Error(`${prefix}.expired_at must be after today`);
|
|
25
|
+
const latest = new Date(`${today}T00:00:00Z`);
|
|
26
|
+
latest.setUTCDate(latest.getUTCDate() + maxExpiryDays);
|
|
27
|
+
if (expiredAt > latest.toISOString().slice(0, 10))
|
|
28
|
+
throw new Error(`${prefix}.expired_at must be no more than ${maxExpiryDays} days away`);
|
|
29
|
+
}
|
|
30
|
+
export function validateIgnoreRegistry(registry, options = {}) {
|
|
31
|
+
const vulnerabilities = registry?.vulnerabilities;
|
|
32
|
+
if (!Array.isArray(vulnerabilities))
|
|
33
|
+
throw new Error('vulnerabilities must be an array');
|
|
34
|
+
const { cleanupUrlPattern } = resolveOptions(options);
|
|
35
|
+
const statement = new RegExp(String.raw `^Not exploitable:\s*(?=\S).+?\.\s*Cleanup:\s*${cleanupUrlPattern}[1-9]\d*$`, 'i');
|
|
36
|
+
for (const [index, ignore] of vulnerabilities.entries()) {
|
|
37
|
+
const prefix = `vulnerabilities[${index}]`;
|
|
38
|
+
if (typeof ignore.id !== 'string' || ignore.id.trim() === '')
|
|
39
|
+
throw new Error(`${prefix}.id must be a vulnerability identifier`);
|
|
40
|
+
if (!Array.isArray(ignore.purls) ||
|
|
41
|
+
ignore.purls.length === 0 ||
|
|
42
|
+
ignore.purls.some((purl) => typeof purl !== 'string' || !OS_PURL.test(purl)))
|
|
43
|
+
throw new Error(`${prefix}.purls must contain exact versioned package purls`);
|
|
44
|
+
if (typeof ignore.statement !== 'string' || !statement.test(ignore.statement))
|
|
45
|
+
throw new Error(`${prefix}.statement must give exploitability rationale and cleanup issue URL`);
|
|
46
|
+
validateExpiry(ignore.expired_at, prefix, options);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export declare function isShellPolicySource(path: string): boolean;
|
|
2
|
+
export declare function assertNoUnsupportedTrivyAction(uses: unknown, path?: string): void;
|
|
3
|
+
export declare function assertNoUnsupportedTrivyShellSource(source: string, path?: string): void;
|
|
4
|
+
/** Every Trivy package-scan command in tracked workflows and composite actions. */
|
|
5
|
+
export declare function trivyPackageScanCommands(repositoryFiles: readonly string[], root: string): string[];
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { existsSync, readFileSync, statSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { parse } from 'yaml';
|
|
4
|
+
import { isDownloadDatabaseOnly } from "./gate.mjs";
|
|
5
|
+
import { trivyPackageScanCommandSegments } from "./invocations.mjs";
|
|
6
|
+
export function isShellPolicySource(path) {
|
|
7
|
+
if (/\.(bash|sh|zsh)$/.test(path))
|
|
8
|
+
return true;
|
|
9
|
+
try {
|
|
10
|
+
if ((statSync(path).mode & 0o111) === 0)
|
|
11
|
+
return false;
|
|
12
|
+
const firstLine = readFileSync(path, 'utf8').split('\n', 1)[0];
|
|
13
|
+
return /^#!\s*(?:\/usr\/bin\/env(?:\s+-S)?\s+|\/(?:usr\/)?bin\/)(?:ba|z)?sh(?:\s|$)/.test(firstLine);
|
|
14
|
+
}
|
|
15
|
+
catch {
|
|
16
|
+
return false;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
function workflowSteps(path) {
|
|
20
|
+
const document = parse(readFileSync(path, 'utf8'));
|
|
21
|
+
return [
|
|
22
|
+
...Object.values(document?.jobs ?? {}).flatMap((job) => job.steps ?? []),
|
|
23
|
+
...(document?.runs?.steps ?? []),
|
|
24
|
+
];
|
|
25
|
+
}
|
|
26
|
+
export function assertNoUnsupportedTrivyAction(uses, path = 'fixture') {
|
|
27
|
+
if (typeof uses === 'string' && /trivy/i.test(uses)) {
|
|
28
|
+
throw new Error(`${path}: unsupported Trivy action ${uses}; use an auditable CLI run block`);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
function assertSupportedWorkflowSteps(paths) {
|
|
32
|
+
const commands = [];
|
|
33
|
+
for (const path of paths) {
|
|
34
|
+
for (const step of workflowSteps(path)) {
|
|
35
|
+
assertNoUnsupportedTrivyAction(step.uses, path);
|
|
36
|
+
if (typeof step.run !== 'string')
|
|
37
|
+
continue;
|
|
38
|
+
commands.push(...trivyPackageScanCommandSegments(step.run));
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
return commands;
|
|
42
|
+
}
|
|
43
|
+
export function assertNoUnsupportedTrivyShellSource(source, path = 'fixture') {
|
|
44
|
+
if (trivyPackageScanCommandSegments(source).some((command) => !isDownloadDatabaseOnly(command))) {
|
|
45
|
+
throw new Error(`${path}: unsupported Trivy shell-script scan; use an auditable workflow run block`);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
/** Every Trivy package-scan command in tracked workflows and composite actions. */
|
|
49
|
+
export function trivyPackageScanCommands(repositoryFiles, root) {
|
|
50
|
+
const present = repositoryFiles.filter((path) => existsSync(join(root, path)));
|
|
51
|
+
for (const path of present.filter((path) => isShellPolicySource(join(root, path)))) {
|
|
52
|
+
assertNoUnsupportedTrivyShellSource(readFileSync(join(root, path), 'utf8'), path);
|
|
53
|
+
}
|
|
54
|
+
const yamlPaths = [
|
|
55
|
+
...present.filter((path) => /^\.github\/workflows\/[^/]+\.ya?ml$/.test(path)),
|
|
56
|
+
...present.filter((path) => /^\.github\/actions\/.+\.ya?ml$/.test(path)),
|
|
57
|
+
];
|
|
58
|
+
return assertSupportedWorkflowSteps(yamlPaths.map((path) => join(root, path)));
|
|
59
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
export function withoutShellComment(command) {
|
|
2
|
+
return command
|
|
3
|
+
.replace(/\\\r?\n/g, '')
|
|
4
|
+
.split('\n')
|
|
5
|
+
.map(withoutShellCommentLine)
|
|
6
|
+
.join('\n');
|
|
7
|
+
}
|
|
8
|
+
function withoutShellCommentLine(command) {
|
|
9
|
+
let quote = '';
|
|
10
|
+
for (let index = 0; index < command.length; index++) {
|
|
11
|
+
const character = command[index];
|
|
12
|
+
if (character === '\\' && quote !== "'") {
|
|
13
|
+
index++;
|
|
14
|
+
continue;
|
|
15
|
+
}
|
|
16
|
+
if (quote !== '') {
|
|
17
|
+
if (character === quote)
|
|
18
|
+
quote = '';
|
|
19
|
+
}
|
|
20
|
+
else if (character === '"' || character === "'")
|
|
21
|
+
quote = character;
|
|
22
|
+
else if (character === '#' && (index === 0 || /\s/.test(command[index - 1])))
|
|
23
|
+
return command.slice(0, index);
|
|
24
|
+
}
|
|
25
|
+
return command;
|
|
26
|
+
}
|
|
27
|
+
export function shellSegments(command) {
|
|
28
|
+
const segments = [];
|
|
29
|
+
let quote = '';
|
|
30
|
+
let start = 0;
|
|
31
|
+
for (let index = 0; index < command.length; index++) {
|
|
32
|
+
const character = command[index];
|
|
33
|
+
if (character === '\\' && quote !== "'") {
|
|
34
|
+
index++;
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
if (quote !== '') {
|
|
38
|
+
if (character === quote)
|
|
39
|
+
quote = '';
|
|
40
|
+
continue;
|
|
41
|
+
}
|
|
42
|
+
if (character === '"' || character === "'") {
|
|
43
|
+
quote = character;
|
|
44
|
+
continue;
|
|
45
|
+
}
|
|
46
|
+
const operatorLength = character === ';' ||
|
|
47
|
+
character === '\n' ||
|
|
48
|
+
character === '|' ||
|
|
49
|
+
(character === '&' && command[index + 1] === '&')
|
|
50
|
+
? command[index + 1] === character && character !== ';'
|
|
51
|
+
? 2
|
|
52
|
+
: 1
|
|
53
|
+
: 0;
|
|
54
|
+
if (operatorLength === 0)
|
|
55
|
+
continue;
|
|
56
|
+
segments.push(command.slice(start, index));
|
|
57
|
+
index += operatorLength - 1;
|
|
58
|
+
start = index + 1;
|
|
59
|
+
}
|
|
60
|
+
segments.push(command.slice(start));
|
|
61
|
+
return segments;
|
|
62
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vouchington-tooling",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.69.0",
|
|
4
4
|
"description": "Vouchington CLI and extractable tooling libraries.",
|
|
5
5
|
"homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -321,6 +321,16 @@
|
|
|
321
321
|
"import": "./dist/dead-code/index.mjs",
|
|
322
322
|
"default": "./dist/dead-code/index.mjs"
|
|
323
323
|
},
|
|
324
|
+
"./trivy-policy": {
|
|
325
|
+
"types": "./dist/trivy-policy/index.d.mts",
|
|
326
|
+
"import": "./dist/trivy-policy/index.mjs",
|
|
327
|
+
"default": "./dist/trivy-policy/index.mjs"
|
|
328
|
+
},
|
|
329
|
+
"./docker-image-mirror": {
|
|
330
|
+
"types": "./dist/docker-image-mirror/index.d.mts",
|
|
331
|
+
"import": "./dist/docker-image-mirror/index.mjs",
|
|
332
|
+
"default": "./dist/docker-image-mirror/index.mjs"
|
|
333
|
+
},
|
|
324
334
|
"./cloc": {
|
|
325
335
|
"types": "./dist/cloc/index.d.mts",
|
|
326
336
|
"import": "./dist/cloc/index.mjs",
|
|
@@ -426,6 +436,11 @@
|
|
|
426
436
|
"import": "./dist/request-query-profile/index.mjs",
|
|
427
437
|
"default": "./dist/request-query-profile/index.mjs"
|
|
428
438
|
},
|
|
439
|
+
"./coverage-scope": {
|
|
440
|
+
"types": "./dist/coverage-scope/index.d.mts",
|
|
441
|
+
"import": "./dist/coverage-scope/index.mjs",
|
|
442
|
+
"default": "./dist/coverage-scope/index.mjs"
|
|
443
|
+
},
|
|
429
444
|
"./package.json": "./package.json",
|
|
430
445
|
"./basic-auth-doc-sync": {
|
|
431
446
|
"types": "./dist/basic-auth-doc-sync/index.d.mts",
|
|
@@ -476,6 +491,7 @@
|
|
|
476
491
|
"@types/unist": "3.0.3",
|
|
477
492
|
"@typescript-eslint/parser": "^8.71.2",
|
|
478
493
|
"agent-blackboard": "^0.7.0",
|
|
494
|
+
"coverage-check": "0.18.0",
|
|
479
495
|
"csv-parse": "7.0.3",
|
|
480
496
|
"csv-stringify": "6.9.0",
|
|
481
497
|
"dockerfile-ast": "0.7.1",
|
|
Binary file
|
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Implementation
|
|
2
2
|
|
|
3
|
+
Before fixing an issue, find out why the affected code exists: read its history, callers, tests,
|
|
4
|
+
and linked issues. A fix that ignores the code's original purpose often breaks it or patches a
|
|
5
|
+
symptom. If the code no longer serves a purpose, or its job is done elsewhere, delete it instead of
|
|
6
|
+
fixing it, along with its tests, configuration, and documentation.
|
|
7
|
+
|
|
3
8
|
For cross-cutting work, track accepted interface, data, validation, and ownership decisions that
|
|
4
9
|
could otherwise be lost during coding. Start from a failing behavioral test when practical and
|
|
5
10
|
complete the real path rather than adding placeholders or compatibility shims without a requirement.
|
package/skills/manifest.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
{
|
|
5
5
|
"name": "agent-workflow",
|
|
6
6
|
"plugin": "vouchington-workflow",
|
|
7
|
-
"pluginVersion": "0.14.
|
|
7
|
+
"pluginVersion": "0.14.2",
|
|
8
8
|
"path": "agent-workflow/SKILL.md",
|
|
9
9
|
"prerequisites": [
|
|
10
10
|
"blackboard",
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
{
|
|
25
25
|
"name": "blackboard",
|
|
26
26
|
"plugin": "vouchington-workflow",
|
|
27
|
-
"pluginVersion": "0.14.
|
|
27
|
+
"pluginVersion": "0.14.2",
|
|
28
28
|
"path": "blackboard/SKILL.md"
|
|
29
29
|
},
|
|
30
30
|
{
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
{
|
|
37
37
|
"name": "dependabot",
|
|
38
38
|
"plugin": "vouchington-workflow",
|
|
39
|
-
"pluginVersion": "0.14.
|
|
39
|
+
"pluginVersion": "0.14.2",
|
|
40
40
|
"path": "dependabot/SKILL.md",
|
|
41
41
|
"prerequisites": ["github-actions-checklist"]
|
|
42
42
|
},
|
|
@@ -50,26 +50,26 @@
|
|
|
50
50
|
{
|
|
51
51
|
"name": "git-commit-checklist",
|
|
52
52
|
"plugin": "vouchington-workflow",
|
|
53
|
-
"pluginVersion": "0.14.
|
|
53
|
+
"pluginVersion": "0.14.2",
|
|
54
54
|
"path": "git-commit-checklist/SKILL.md"
|
|
55
55
|
},
|
|
56
56
|
{
|
|
57
57
|
"name": "github-actions-authoring",
|
|
58
58
|
"plugin": "vouchington-workflow",
|
|
59
|
-
"pluginVersion": "0.14.
|
|
59
|
+
"pluginVersion": "0.14.2",
|
|
60
60
|
"path": "github-actions-authoring/SKILL.md",
|
|
61
61
|
"prerequisites": ["github-actions-checklist"]
|
|
62
62
|
},
|
|
63
63
|
{
|
|
64
64
|
"name": "github-actions-checklist",
|
|
65
65
|
"plugin": "vouchington-workflow",
|
|
66
|
-
"pluginVersion": "0.14.
|
|
66
|
+
"pluginVersion": "0.14.2",
|
|
67
67
|
"path": "github-actions-checklist/SKILL.md"
|
|
68
68
|
},
|
|
69
69
|
{
|
|
70
70
|
"name": "github-issue",
|
|
71
71
|
"plugin": "vouchington-workflow",
|
|
72
|
-
"pluginVersion": "0.14.
|
|
72
|
+
"pluginVersion": "0.14.2",
|
|
73
73
|
"path": "github-issue/SKILL.md"
|
|
74
74
|
},
|
|
75
75
|
{
|
|
@@ -82,26 +82,26 @@
|
|
|
82
82
|
{
|
|
83
83
|
"name": "npm-publishing",
|
|
84
84
|
"plugin": "vouchington-workflow",
|
|
85
|
-
"pluginVersion": "0.14.
|
|
85
|
+
"pluginVersion": "0.14.2",
|
|
86
86
|
"path": "npm-publishing/SKILL.md"
|
|
87
87
|
},
|
|
88
88
|
{
|
|
89
89
|
"name": "organize-github-issues",
|
|
90
90
|
"plugin": "vouchington-workflow",
|
|
91
|
-
"pluginVersion": "0.14.
|
|
91
|
+
"pluginVersion": "0.14.2",
|
|
92
92
|
"path": "organize-github-issues/SKILL.md",
|
|
93
93
|
"prerequisites": ["github-issue"]
|
|
94
94
|
},
|
|
95
95
|
{
|
|
96
96
|
"name": "package-json-checklist",
|
|
97
97
|
"plugin": "vouchington-workflow",
|
|
98
|
-
"pluginVersion": "0.14.
|
|
98
|
+
"pluginVersion": "0.14.2",
|
|
99
99
|
"path": "package-json-checklist/SKILL.md"
|
|
100
100
|
},
|
|
101
101
|
{
|
|
102
102
|
"name": "planning",
|
|
103
103
|
"plugin": "vouchington-workflow",
|
|
104
|
-
"pluginVersion": "0.14.
|
|
104
|
+
"pluginVersion": "0.14.2",
|
|
105
105
|
"path": "planning/SKILL.md",
|
|
106
106
|
"prerequisites": ["github-issue"]
|
|
107
107
|
},
|
|
@@ -133,53 +133,53 @@
|
|
|
133
133
|
{
|
|
134
134
|
"name": "pr-description",
|
|
135
135
|
"plugin": "vouchington-workflow",
|
|
136
|
-
"pluginVersion": "0.14.
|
|
136
|
+
"pluginVersion": "0.14.2",
|
|
137
137
|
"path": "pr-description/SKILL.md"
|
|
138
138
|
},
|
|
139
139
|
{
|
|
140
140
|
"name": "retrospective",
|
|
141
141
|
"plugin": "vouchington-workflow",
|
|
142
|
-
"pluginVersion": "0.14.
|
|
142
|
+
"pluginVersion": "0.14.2",
|
|
143
143
|
"path": "retrospective/SKILL.md"
|
|
144
144
|
},
|
|
145
145
|
{
|
|
146
146
|
"name": "retrospective-distill",
|
|
147
147
|
"plugin": "vouchington-workflow",
|
|
148
|
-
"pluginVersion": "0.14.
|
|
148
|
+
"pluginVersion": "0.14.2",
|
|
149
149
|
"path": "retrospective-distill/SKILL.md",
|
|
150
150
|
"prerequisites": ["github-issue"]
|
|
151
151
|
},
|
|
152
152
|
{
|
|
153
153
|
"name": "review-ci-logs",
|
|
154
154
|
"plugin": "vouchington-workflow",
|
|
155
|
-
"pluginVersion": "0.14.
|
|
155
|
+
"pluginVersion": "0.14.2",
|
|
156
156
|
"path": "review-ci-logs/SKILL.md",
|
|
157
157
|
"prerequisites": ["github-actions-checklist", "pr-description"]
|
|
158
158
|
},
|
|
159
159
|
{
|
|
160
160
|
"name": "review-github-issue-taxonomy",
|
|
161
161
|
"plugin": "vouchington-workflow",
|
|
162
|
-
"pluginVersion": "0.14.
|
|
162
|
+
"pluginVersion": "0.14.2",
|
|
163
163
|
"path": "review-github-issue-taxonomy/SKILL.md",
|
|
164
164
|
"prerequisites": ["github-issue"]
|
|
165
165
|
},
|
|
166
166
|
{
|
|
167
167
|
"name": "revisit-followups",
|
|
168
168
|
"plugin": "vouchington-workflow",
|
|
169
|
-
"pluginVersion": "0.14.
|
|
169
|
+
"pluginVersion": "0.14.2",
|
|
170
170
|
"path": "revisit-followups/SKILL.md",
|
|
171
171
|
"prerequisites": ["github-issue"]
|
|
172
172
|
},
|
|
173
173
|
{
|
|
174
174
|
"name": "stacked-prs",
|
|
175
175
|
"plugin": "vouchington-workflow",
|
|
176
|
-
"pluginVersion": "0.14.
|
|
176
|
+
"pluginVersion": "0.14.2",
|
|
177
177
|
"path": "stacked-prs/SKILL.md"
|
|
178
178
|
},
|
|
179
179
|
{
|
|
180
180
|
"name": "static-analysis-checklist",
|
|
181
181
|
"plugin": "vouchington-workflow",
|
|
182
|
-
"pluginVersion": "0.14.
|
|
182
|
+
"pluginVersion": "0.14.2",
|
|
183
183
|
"path": "static-analysis-checklist/SKILL.md",
|
|
184
184
|
"prerequisites": ["github-actions-checklist"]
|
|
185
185
|
},
|
|
@@ -206,7 +206,7 @@
|
|
|
206
206
|
{
|
|
207
207
|
"name": "triage-prs",
|
|
208
208
|
"plugin": "vouchington-workflow",
|
|
209
|
-
"pluginVersion": "0.14.
|
|
209
|
+
"pluginVersion": "0.14.2",
|
|
210
210
|
"path": "triage-prs/SKILL.md",
|
|
211
211
|
"prerequisites": [
|
|
212
212
|
"pr-description",
|
|
@@ -12,14 +12,29 @@ Local policy overrides these defaults; do not reload an already-read adapter or
|
|
|
12
12
|
Use before opening or updating a pull request, after diagnosing a CI failure, or at handoff. Read local
|
|
13
13
|
`AGENTS.md`, pull-request template, and issue-linking policy first.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Write for a reviewer who has not seen the conversation or the code. Use plain language and short
|
|
16
|
+
bullets, not dense paragraphs of internal terms. Its visible core explains:
|
|
16
17
|
|
|
17
|
-
- **Summary:**
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- **
|
|
21
|
-
such as
|
|
22
|
-
|
|
18
|
+
- **Summary:** open with one or two sentences on the outcome in plain terms. Then give a
|
|
19
|
+
**Why:** that names the concrete problem or risk, such as who could do what before this change.
|
|
20
|
+
For a fix, give the root cause as well as the symptom.
|
|
21
|
+
- **Before/after table:** for any behavior change, add a visible table whose rows are concrete
|
|
22
|
+
scenarios, such as requests, configurations, environments, inputs, or user actions. Its columns
|
|
23
|
+
are the situation, the behavior before, and the behavior after. Include the unchanged cases a
|
|
24
|
+
reviewer would worry about, and the error or status each failure case returns.
|
|
25
|
+
- **Diagram:** when a request or event crosses components, add a Mermaid `sequenceDiagram` of the
|
|
26
|
+
new flow. Use a `flowchart` for decision logic or changed architecture. Keep the main diagram
|
|
27
|
+
visible.
|
|
28
|
+
- **Impact:** one bullet per affected audience, such as end users, staff, native or API clients,
|
|
29
|
+
operators, or contributors, saying what each one sees. Say when the change is active: what
|
|
30
|
+
enables it, such as a plan tier, feature flag, environment, configuration value, or rollout
|
|
31
|
+
step, and whether current deployments already satisfy it. Name the configuration it reads and
|
|
32
|
+
its defaults. Keep risks, limitations, and dependent follow-ups visible.
|
|
33
|
+
|
|
34
|
+
Put implementation detail under **Details**, grouped by subsystem with short headings. Name the
|
|
35
|
+
files and functions that carry each part, so a reviewer can find them. Leave CI history, rebase
|
|
36
|
+
narrative, and local test lists out of the body; the Shepherd Journal and evidence record hold
|
|
37
|
+
them.
|
|
23
38
|
|
|
24
39
|
Add detail only where the change warrants it:
|
|
25
40
|
|
|
@@ -32,11 +47,11 @@ Add detail only where the change warrants it:
|
|
|
32
47
|
producer/consumer changes and any justified exceptions. Link the policy and concrete evidence.
|
|
33
48
|
- For API, workflow, or independently deployed changes, explain the affected contract, lifecycle,
|
|
34
49
|
or operational safety. Follow the consumer's compatibility and deployment policy.
|
|
35
|
-
-
|
|
36
|
-
workflow topology, or lifecycle easier to understand. Prose is sufficient for a simple change.
|
|
50
|
+
- A one-line fix with no new scenarios needs only prose. Skip the table and diagram there.
|
|
37
51
|
|
|
38
|
-
Put long
|
|
39
|
-
`<details>` sections. Keep the
|
|
52
|
+
Put long inventories, secondary diagrams, calculations, and failure evidence in collapsed
|
|
53
|
+
`<details>` sections. Keep the summary, the main before/after table, the main diagram, and
|
|
54
|
+
material risks outside them. Keep the
|
|
40
55
|
consumer's required visible core headings outside disclosure containers. Put opening/closing tags
|
|
41
56
|
on separate lines, with a blank line after `</summary>` and before `</details>` so Markdown renders.
|
|
42
57
|
Read [description examples](references/examples.md) when choosing a comparison, diagram, or failure
|
|
@@ -20,6 +20,59 @@ clears the old selection after the exit animation.
|
|
|
20
20
|
|
|
21
21
|
No diagram, cost calculation, database inventory, or local successful-test list is needed.
|
|
22
22
|
|
|
23
|
+
## Request-flow change with activation conditions
|
|
24
|
+
|
|
25
|
+
````markdown
|
|
26
|
+
## Summary
|
|
27
|
+
|
|
28
|
+
Writes from sessions the edge flags as likely automated must now pass a challenge first. The web
|
|
29
|
+
app shows the challenge and retries the request on its own.
|
|
30
|
+
|
|
31
|
+
**Why:** the plan limit applies only to the agent API. A script holding a copied session cookie
|
|
32
|
+
could use the REST API to do what the agent API refuses.
|
|
33
|
+
|
|
34
|
+
| Request | Before | After |
|
|
35
|
+
| ------------------------------------- | ------- | ------------------------------------------------------------ |
|
|
36
|
+
| Cookie-session write, bot score 30–99 | Allowed | Allowed, unchanged |
|
|
37
|
+
| Cookie-session write, bot score 1–29 | Allowed | `403 CHALLENGE_REQUIRED`, then one retry after the challenge |
|
|
38
|
+
| Any read | Allowed | Allowed, never challenged |
|
|
39
|
+
| OAuth or API-key request | Allowed | Allowed; keeps its own admission path |
|
|
40
|
+
| No score supplied | Allowed | Allowed; check skipped |
|
|
41
|
+
|
|
42
|
+
```mermaid
|
|
43
|
+
sequenceDiagram
|
|
44
|
+
participant B as Browser
|
|
45
|
+
participant E as Edge proxy
|
|
46
|
+
participant A as API
|
|
47
|
+
B->>E: POST (session cookie)
|
|
48
|
+
E->>A: forward + score header (only if the edge supplied one)
|
|
49
|
+
alt score missing or 30–99
|
|
50
|
+
A-->>B: normal response
|
|
51
|
+
else score 1–29
|
|
52
|
+
A-->>B: 403 CHALLENGE_REQUIRED
|
|
53
|
+
B->>E: same request + challenge token
|
|
54
|
+
E->>A: forward
|
|
55
|
+
A-->>B: normal response, or 400 if the token fails
|
|
56
|
+
end
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Impact
|
|
60
|
+
|
|
61
|
+
**Not active yet.** The score comes from a paid edge plan, and every check is skipped without it.
|
|
62
|
+
It switches on with no code change once the score is available.
|
|
63
|
+
|
|
64
|
+
- **Normal users:** nothing changes.
|
|
65
|
+
- **Flagged users:** a short, usually invisible challenge before each write.
|
|
66
|
+
- **Scripts with a copied cookie:** writes fail.
|
|
67
|
+
- **OAuth and API-key clients:** unaffected.
|
|
68
|
+
- **Limitation:** automation driving a real browser can often pass the challenge. Session binding
|
|
69
|
+
remains the main defense.
|
|
70
|
+
````
|
|
71
|
+
|
|
72
|
+
The table covers the unchanged paths a reviewer would worry about. The Impact opens by saying
|
|
73
|
+
when the change takes effect. A real description adds Details grouped by subsystem, naming the
|
|
74
|
+
files and functions involved.
|
|
75
|
+
|
|
23
76
|
## Database relationship change
|
|
24
77
|
|
|
25
78
|
```markdown
|