Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

feat: add goal-audit npm package (publish from loop-engineering) (#53)

Cobus Greyling592b5bb2bed7
diff --git a/.github/workflows/release-goal-audit.yml b/.github/workflows/release-goal-audit.yml
new file mode 100644
index 0000000..9585b44
--- /dev/null
+++ b/.github/workflows/release-goal-audit.yml
@@ -0,0 +1,39 @@
+name: Release goal-audit
+
+on:
+ push:
+ tags:
+ - 'goal-audit-v*'
+
+permissions:
+ contents: read
+ id-token: write
+
+jobs:
+ test-and-publish:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v6
+
+ - uses: actions/setup-node@v6
+ with:
+ node-version: '22'
+ registry-url: 'https://registry.npmjs.org'
+ cache: 'npm'
+ cache-dependency-path: tools/goal-audit/package-lock.json
+
+ - name: Ensure npm supports trusted publishing (OIDC)
+ run: npm install -g npm@latest
+
+ - name: Install, build, test
+ working-directory: tools/goal-audit
+ run: |
+ npm ci
+ npm run build
+ npm test
+
+ - name: Publish to npm
+ working-directory: tools/goal-audit
+ run: npm publish --access public --provenance
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index cf827bd..aa5bd8a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,6 +29,7 @@ build/
**/node_modules/
!tools/loop-audit/dist/
!tools/loop-cost/dist/
+!tools/goal-audit/dist/
*.egg-info/
# State files that should not be committed in consumer projects (reference repo dogfoods STATE.md)
diff --git a/tools/goal-audit/README.md b/tools/goal-audit/README.md
new file mode 100644
index 0000000..5241064
--- /dev/null
+++ b/tools/goal-audit/README.md
@@ -0,0 +1,27 @@
+# goal-audit
+
+Goal Readiness Score CLI for Grok Build `/goal` workflows.
+
+## Install / run
+
+```bash
+npx @cobusgreyling/goal-audit .
+npx @cobusgreyling/goal-audit . --suggest
+npx @cobusgreyling/goal-audit . --json
+```
+
+## Levels
+
+| Level | Score | Meaning |
+|-------|-------|---------|
+| G0 | < 40 | Ad hoc `/goal` usage |
+| G1 | 40–59 | GOAL.md + assisted goals |
+| G2 | 60–79 | Verifier + test gates |
+| G3 | 80+ | CI, budget, run log |
+
+## Development
+
+```bash
+npm install
+npm test
+```
\ No newline at end of file
diff --git a/tools/goal-audit/dist/auditor.d.ts b/tools/goal-audit/dist/auditor.d.ts
new file mode 100644
index 0000000..cdf32d4
--- /dev/null
+++ b/tools/goal-audit/dist/auditor.d.ts
@@ -0,0 +1,54 @@
+export interface GoalSignals {
+ goalFile: {
+ present: boolean;
+ path?: string;
+ };
+ goalConfig: {
+ present: boolean;
+ };
+ skills: {
+ count: number;
+ goalSkills: string[];
+ };
+ verifier: {
+ present: boolean;
+ };
+ scoper: {
+ present: boolean;
+ };
+ agentsMd: {
+ present: boolean;
+ mentionsGoal: boolean;
+ };
+ patterns: {
+ documented: boolean;
+ };
+ safety: {
+ safetyDocPresent: boolean;
+ budgetDoc: boolean;
+ };
+ tests: {
+ present: boolean;
+ };
+ ci: {
+ present: boolean;
+ };
+ runLog: {
+ present: boolean;
+ };
+}
+export interface Finding {
+ level: 'ok' | 'warn' | 'fail';
+ message: string;
+}
+export interface AuditResult {
+ target: string;
+ score: number;
+ level: 'G0' | 'G1' | 'G2' | 'G3';
+ assessment: string;
+ signals: GoalSignals;
+ findings: Finding[];
+ recommendations: string[];
+}
+export declare function auditProject(target: string): Promise<AuditResult>;
+//# sourceMappingURL=auditor.d.ts.map
\ No newline at end of file
diff --git a/tools/goal-audit/dist/auditor.d.ts.map b/tools/goal-audit/dist/auditor.d.ts.map
new file mode 100644
index 0000000..79d9569
--- /dev/null
+++ b/tools/goal-audit/dist/auditor.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,UAAU,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACjC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/B,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7B,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;IACtD,QAAQ,EAAE;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IAClC,MAAM,EAAE;QAAE,gBAAgB,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1D,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5B,EAAE,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACzB,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9B;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AA2FD,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAsJvE"}
\ No newline at end of file
diff --git a/tools/goal-audit/dist/auditor.js b/tools/goal-audit/dist/auditor.js
new file mode 100644
index 0000000..1271ead
--- /dev/null
+++ b/tools/goal-audit/dist/auditor.js
@@ -0,0 +1,240 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+const GOAL_FILES = ['GOAL.md', 'goal.md', 'docs/GOAL.md'];
+const GOAL_SKILL_NAMES = [
+ 'goal-verifier',
+ 'goal-scoper',
+ 'goal-completion-check',
+];
+const SAFETY_FILES = ['docs/safety.md', 'SECURITY.md', 'safety.md'];
+const BUDGET_FILES = ['goal-budget.md', 'docs/goal-budget.md'];
+const RUN_LOG_FILES = ['goal-run-log.md', 'docs/goal-run-log.md'];
+async function fileExists(p) {
+ try {
+ await stat(p);
+ return true;
+ }
+ catch {
+ return false;
+ }
+}
+async function findSkills(root) {
+ const dirs = [
+ path.join(root, '.grok', 'skills'),
+ path.join(root, '.claude', 'skills'),
+ path.join(root, '.codex', 'skills'),
+ path.join(root, 'skills'),
+ ];
+ const found = [];
+ for (const dir of dirs) {
+ if (!(await fileExists(dir)))
+ continue;
+ const entries = await readdir(dir, { withFileTypes: true });
+ for (const e of entries) {
+ if (e.isDirectory())
+ found.push(e.name);
+ }
+ }
+ return found;
+}
+async function detectTests(root) {
+ const hints = [
+ 'package.json',
+ 'pyproject.toml',
+ 'go.mod',
+ 'Cargo.toml',
+ 'vitest.config.ts',
+ 'jest.config.js',
+ 'pytest.ini',
+ ];
+ for (const h of hints) {
+ if (await fileExists(path.join(root, h)))
+ return true;
+ }
+ const testDirs = ['tests', 'test', '__tests__'];
+ for (const d of testDirs) {
+ if (await fileExists(path.join(root, d)))
+ return true;
+ }
+ return false;
+}
+async function detectCi(root) {
+ const ciPaths = [
+ '.github/workflows',
+ '.gitlab-ci.yml',
+ 'Jenkinsfile',
+ ];
+ for (const p of ciPaths) {
+ if (await fileExists(path.join(root, p)))
+ return true;
+ }
+ return false;
+}
+function scoreLevel(score) {
+ if (score >= 80)
+ return 'G3';
+ if (score >= 60)
+ return 'G2';
+ if (score >= 40)
+ return 'G1';
+ return 'G0';
+}
+function assessmentFor(level) {
+ switch (level) {
+ case 'G3':
+ return 'production-ready goal workflows';
+ case 'G2':
+ return 'verified goals with checker split';
+ case 'G1':
+ return 'assisted goals — add verifier for G2';
+ default:
+ return 'ad hoc — scaffold GOAL.md and skills';
+ }
+}
+export async function auditProject(target) {
+ const root = path.resolve(target);
+ const findings = [];
+ const recommendations = [];
+ let score = 0;
+ const goalPaths = [];
+ for (const f of GOAL_FILES) {
+ if (await fileExists(path.join(root, f)))
+ goalPaths.push(f);
+ }
+ const goalFilePresent = goalPaths.length > 0;
+ if (goalFilePresent) {
+ score += 15;
+ findings.push({ level: 'ok', message: `GOAL file present (${goalPaths.join(', ')})` });
+ }
+ else {
+ findings.push({ level: 'fail', message: 'No GOAL.md — goals will not survive compaction' });
+ recommendations.push('cp templates/GOAL.md.template GOAL.md');
+ }
+ const goalConfigPresent = await fileExists(path.join(root, 'GOAL.md'));
+ if (goalConfigPresent)
+ score += 5;
+ const allSkills = await findSkills(root);
+ const goalSkills = allSkills.filter((s) => GOAL_SKILL_NAMES.includes(s));
+ if (goalSkills.length > 0) {
+ score += 10 + Math.min(goalSkills.length * 5, 15);
+ findings.push({ level: 'ok', message: `Goal skills: ${goalSkills.join(', ')}` });
+ }
+ else {
+ findings.push({ level: 'warn', message: 'No goal-verifier / goal-scoper skills found' });
+ recommendations.push('cp -r starters/minimal-goal/.grok/skills/goal-verifier .grok/skills/');
+ }
+ const verifierPresent = goalSkills.includes('goal-verifier') || allSkills.some((s) => s.includes('verifier'));
+ if (verifierPresent) {
+ score += 20;
+ findings.push({ level: 'ok', message: 'Verifier skill or agent present' });
+ }
+ else {
+ findings.push({ level: 'fail', message: 'No verifier — implementer may self-grade' });
+ recommendations.push('Add goal-verifier skill from skills/goal-verifier/');
+ }
+ const scoperPresent = goalSkills.includes('goal-scoper');
+ if (scoperPresent)
+ score += 5;
+ const agentsPath = path.join(root, 'AGENTS.md');
+ const agentsPresent = await fileExists(agentsPath);
+ let mentionsGoal = false;
+ if (agentsPresent) {
+ const content = await readFile(agentsPath, 'utf8');
+ mentionsGoal = /goal|update_goal|GOAL\.md/i.test(content);
+ score += mentionsGoal ? 10 : 5;
+ findings.push({
+ level: mentionsGoal ? 'ok' : 'warn',
+ message: mentionsGoal ? 'AGENTS.md mentions goal discipline' : 'AGENTS.md present but no goal rules',
+ });
+ if (!mentionsGoal) {
+ recommendations.push('Add goal rules to AGENTS.md: verifier before completed: true');
+ }
+ }
+ else {
+ findings.push({ level: 'warn', message: 'No AGENTS.md' });
+ recommendations.push('gbs scaffold agents-md --write (from grok-build-showcase) or write AGENTS.md');
+ }
+ const patternsPresent = (await fileExists(path.join(root, 'patterns'))) ||
+ (await fileExists(path.join(root, 'docs', 'api-reference.md')));
+ if (patternsPresent) {
+ score += 5;
+ findings.push({ level: 'ok', message: 'Goal patterns or API docs present' });
+ }
+ let safetyDocPresent = false;
+ for (const f of SAFETY_FILES) {
+ if (await fileExists(path.join(root, f))) {
+ safetyDocPresent = true;
+ break;
+ }
+ }
+ let budgetDoc = false;
+ for (const f of BUDGET_FILES) {
+ if (await fileExists(path.join(root, f))) {
+ budgetDoc = true;
+ break;
+ }
+ }
+ if (safetyDocPresent)
+ score += 5;
+ if (budgetDoc) {
+ score += 10;
+ findings.push({ level: 'ok', message: 'Goal budget documented' });
+ }
+ else {
+ recommendations.push('cp templates/goal-budget.md.template goal-budget.md');
+ }
+ const testsPresent = await detectTests(root);
+ if (testsPresent) {
+ score += 15;
+ findings.push({ level: 'ok', message: 'Test harness detected' });
+ }
+ else {
+ findings.push({ level: 'warn', message: 'No test harness — done conditions are subjective' });
+ }
+ const ciPresent = await detectCi(root);
+ if (ciPresent) {
+ score += 10;
+ findings.push({ level: 'ok', message: 'CI configuration present' });
+ }
+ let runLog = false;
+ for (const f of RUN_LOG_FILES) {
+ if (await fileExists(path.join(root, f))) {
+ runLog = true;
+ break;
+ }
+ }
+ if (runLog) {
+ score += 5;
+ findings.push({ level: 'ok', message: 'Goal run log present' });
+ }
+ score = Math.min(100, score);
+ const level = scoreLevel(score);
+ if (level === 'G0') {
+ recommendations.push('Read docs/goal-design-checklist.md and starters/minimal-goal/');
+ }
+ if (level === 'G1' && !verifierPresent) {
+ recommendations.push('Graduate to G2: add goal-verifier before unattended goals');
+ }
+ return {
+ target: root,
+ score,
+ level,
+ assessment: assessmentFor(level),
+ signals: {
+ goalFile: { present: goalFilePresent, path: goalPaths[0] },
+ goalConfig: { present: goalConfigPresent },
+ skills: { count: allSkills.length, goalSkills },
+ verifier: { present: verifierPresent },
+ scoper: { present: scoperPresent },
+ agentsMd: { present: agentsPresent, mentionsGoal },
+ patterns: { documented: patternsPresent },
+ safety: { safetyDocPresent, budgetDoc },
+ tests: { present: testsPresent },
+ ci: { present: ciPresent },
+ runLog: { present: runLog },
+ },
+ findings,
+ recommendations: [...new Set(recommendations)],
+ };
+}
+//# sourceMappingURL=auditor.js.map
\ No newline at end of file
diff --git a/tools/goal-audit/dist/auditor.js.map b/tools/goal-audit/dist/auditor.js.map
new file mode 100644
index 0000000..820da24
--- /dev/null
+++ b/tools/goal-audit/dist/auditor.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"auditor.js","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"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"}
\ No newline at end of file
diff --git a/tools/goal-audit/dist/cli.d.ts b/tools/goal-audit/dist/cli.d.ts
new file mode 100644
index 0000000..faaadd5
--- /dev/null
+++ b/tools/goal-audit/dist/cli.d.ts
@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map
\ No newline at end of file
diff --git a/tools/goal-audit/dist/cli.d.ts.map b/tools/goal-audit/dist/cli.d.ts.map
new file mode 100644
index 0000000..f022439
--- /dev/null
+++ b/tools/goal-audit/dist/cli.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
\ No newline at end of file
diff --git a/tools/goal-audit/dist/cli.js b/tools/goal-audit/dist/cli.js
new file mode 100644
index 0000000..ff65cbe
--- /dev/null
+++ b/tools/goal-audit/dist/cli.js
@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { auditProject } from './auditor.js';
+import { formatHuman, formatJson, formatMarkdown } from './reporter.js';
+const args = process.argv.slice(2);
+const target = args.find((a) => !a.startsWith('-')) || '.';
+const json = args.includes('--json');
+const md = args.includes('--md');
+const suggest = args.includes('--suggest') || args.includes('--fix');
+const help = args.includes('--help') || args.includes('-h');
+if (help) {
+ console.log(`goal-audit — Goal Readiness Score CLI (G0–G3)
+
+Usage:
+ goal-audit [path] [options]
+
+Options:
+ --json JSON output (for CI / scripting)
+ --md Markdown report
+ --suggest Show copy-from-template commands
+ --help, -h This help
+
+Scores goal readiness for Grok Build /goal:
+ GOAL.md, verifier skills, AGENTS.md, tests, CI, budget docs
+
+Exit codes:
+ 0 score >= 40
+ 2 score < 40
+
+Examples:
+ goal-audit .
+ goal-audit . --suggest
+ npx @cobusgreyling/goal-audit . --json
+`);
+ process.exit(0);
+}
+try {
+ const result = await auditProject(target);
+ if (json)
+ console.log(formatJson(result));
+ else if (md)
+ console.log(formatMarkdown(result));
+ else
+ console.log(formatHuman(result));
+ if (suggest) {
+ console.log('\n=== Suggested actions ===');
+ console.log('');
+ console.log(' cp templates/GOAL.md.template GOAL.md');
+ console.log(' cp -r starters/minimal-goal/.grok/skills/goal-verifier .grok/skills/');
+ console.log(' cp templates/goal-budget.md.template goal-budget.md');
+ console.log(' cp templates/goal-run-log.md.template goal-run-log.md');
+ console.log('');
+ console.log(' # Then in Grok Build:');
+ console.log(' /goal Read GOAL.md. Work the objective. goal-verifier before completed: true.');
+ console.log('');
+ console.log(' Docs: https://github.com/cobusgreyling/goal-engineering');
+ }
+ process.exit(result.score >= 40 ? 0 : 2);
+}
+catch (err) {
+ console.error('goal-audit error:', err instanceof Error ? err.message : err);
+ process.exit(1);
+}
+//# sourceMappingURL=cli.js.map
\ No newline at end of file
diff --git a/tools/goal-audit/dist/cli.js.map b/tools/goal-audit/dist/cli.js.map
new file mode 100644
index 0000000..5100a09
--- /dev/null
+++ b/tools/goal-audit/dist/cli.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAExE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;AAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACrC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACjC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACrE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAE5D,IAAI,IAAI,EAAE,CAAC;IACT,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;CAsBb,CAAC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,IAAI;QAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;SACrC,IAAI,EAAE;QAAE,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;;QAC5C,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAEtC,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;QACvD,OAAO,CAAC,GAAG,CAAC,wEAAwE,CAAC,CAAC;QACtF,OAAO,CAAC,GAAG,CAAC,uDAAuD,CAAC,CAAC;QACrE,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;QACvE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;QAC/F,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
\ No newline at end of file
diff --git a/tools/goal-audit/dist/reporter.d.ts b/tools/goal-audit/dist/reporter.d.ts
new file mode 100644
index 0000000..cfd90fb
--- /dev/null
+++ b/tools/goal-audit/dist/reporter.d.ts
@@ -0,0 +1,5 @@
+import type { AuditResult } from './auditor.js';
+export declare function formatHuman(result: AuditResult): string;
+export declare function formatJson(result: AuditResult): string;
+export declare function formatMarkdown(result: AuditResult): string;
+//# sourceMappingURL=reporter.d.ts.map
\ No newline at end of file
diff --git a/tools/goal-audit/dist/reporter.d.ts.map b/tools/goal-audit/dist/reporter.d.ts.map
new file mode 100644
index 0000000..a1e34b3
--- /dev/null
+++ b/tools/goal-audit/dist/reporter.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhD,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAgBvD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEtD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAwB1D"}
\ No newline at end of file
diff --git a/tools/goal-audit/dist/reporter.js b/tools/goal-audit/dist/reporter.js
new file mode 100644
index 0000000..befeaf7
--- /dev/null
+++ b/tools/goal-audit/dist/reporter.js
@@ -0,0 +1,47 @@
+const ICON = { ok: '✓', warn: '△', fail: '✗' };
+export function formatHuman(result) {
+ const lines = [];
+ lines.push(`Goal Readiness Score: ${result.score}/100 (${result.level} — ${result.assessment})`);
+ lines.push(`Target: ${result.target}`);
+ lines.push('');
+ for (const f of result.findings) {
+ lines.push(`${ICON[f.level]} ${f.message}`);
+ }
+ if (result.recommendations.length > 0) {
+ lines.push('');
+ lines.push('Recommendations:');
+ for (const r of result.recommendations) {
+ lines.push(` • ${r}`);
+ }
+ }
+ return lines.join('\n');
+}
+export function formatJson(result) {
+ return JSON.stringify(result, null, 2);
+}
+export function formatMarkdown(result) {
+ const lines = [];
+ lines.push('# Goal Readiness Audit');
+ lines.push('');
+ lines.push(`| Metric | Value |`);
+ lines.push(`|--------|-------|`);
+ lines.push(`| Score | ${result.score}/100 |`);
+ lines.push(`| Level | ${result.level} |`);
+ lines.push(`| Assessment | ${result.assessment} |`);
+ lines.push('');
+ lines.push('## Findings');
+ lines.push('');
+ for (const f of result.findings) {
+ lines.push(`- ${ICON[f.level]} ${f.message}`);
+ }
+ if (result.recommendations.length > 0) {
+ lines.push('');
+ lines.push('## Recommendations');
+ lines.push('');
+ for (const r of result.recommendations) {
+ lines.push(`- ${r}`);
+ }
+ }
+ return lines.join('\n');
+}
+//# sourceMappingURL=reporter.js.map
\ No newline at end of file
diff --git a/tools/goal-audit/dist/reporter.js.map b/tools/goal-audit/dist/reporter.js.map
new file mode 100644
index 0000000..f5a5b91
--- /dev/null
+++ b/tools/goal-audit/dist/reporter.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"reporter.js","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAEA,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAW,CAAC;AAExD,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,yBAAyB,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAK,MAAM,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;IAClG,KAAK,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAmB;IAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;IACrC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC;IAC9C,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,kBAAkB,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}
\ No newline at end of file
diff --git a/tools/goal-audit/package-lock.json b/tools/goal-audit/package-lock.json
new file mode 100644
index 0000000..f070c2f
--- /dev/null
+++ b/tools/goal-audit/package-lock.json
@@ -0,0 +1,54 @@
+{
+ "name": "@cobusgreyling/goal-audit",
+ "version": "1.0.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "@cobusgreyling/goal-audit",
+ "version": "1.0.0",
+ "license": "MIT",
+ "bin": {
+ "goal-audit": "dist/cli.js"
+ },
+ "devDependencies": {
+ "@types/node": "^25.9.3",
+ "typescript": "^5.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@types/node": {
+ "version": "25.9.4",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.4.tgz",
+ "integrity": "sha512-dszCsrKb5U7ZsVZBWiHFklTloVl0mSEnWH/iZXfZUlI4rzCUnsvGmgqfuVRHL54ugE7/wRuxEIXRa2iMZ+BG6g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": ">=7.24.0 <7.24.7"
+ }
+ },
+ "node_modules/typescript": {
+ "version": "5.9.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ },
+ "node_modules/undici-types": {
+ "version": "7.24.6",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
+ "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
+ "dev": true,
+ "license": "MIT"
+ }
+ }
+}
diff --git a/tools/goal-audit/package.json b/tools/goal-audit/package.json
new file mode 100644
index 0000000..5c6cb51
--- /dev/null
+++ b/tools/goal-audit/package.json
@@ -0,0 +1,49 @@
+{
+ "name": "@cobusgreyling/goal-audit",
+ "version": "1.0.0",
+ "description": "Goal engineering readiness auditor for Grok Build /goal. Compute Goal Readiness Score (G0-G3). npx @cobusgreyling/goal-audit . --suggest",
+ "type": "module",
+ "bin": {
+ "goal-audit": "./dist/cli.js"
+ },
+ "files": [
+ "dist",
+ "README.md"
+ ],
+ "scripts": {
+ "build": "tsc",
+ "test": "npm run build && node --test test/auditor.test.mjs",
+ "prepublishOnly": "npm test",
+ "start": "node dist/cli.js"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "keywords": [
+ "goal-engineering",
+ "grok-build",
+ "grok",
+ "ai-agents",
+ "coding-agents",
+ "readiness",
+ "audit"
+ ],
+ "author": "Cobus Greyling",
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/cobusgreyling/goal-engineering.git",
+ "directory": "tools/goal-audit"
+ },
+ "homepage": "https://github.com/cobusgreyling/goal-engineering",
+ "bugs": {
+ "url": "https://github.com/cobusgreyling/goal-engineering/issues"
+ },
+ "publishConfig": {
+ "access": "public"
+ },
+ "devDependencies": {
+ "@types/node": "^25.9.3",
+ "typescript": "^5.0.0"
+ }
+}
\ No newline at end of file
diff --git a/tools/goal-audit/src/auditor.ts b/tools/goal-audit/src/auditor.ts
new file mode 100644
index 0000000..c8b81fa
--- /dev/null
+++ b/tools/goal-audit/src/auditor.ts
@@ -0,0 +1,272 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+export interface GoalSignals {
+ goalFile: { present: boolean; path?: string };
+ goalConfig: { present: boolean };
+ skills: { count: number; goalSkills: string[] };
+ verifier: { present: boolean };
+ scoper: { present: boolean };
+ agentsMd: { present: boolean; mentionsGoal: boolean };
+ patterns: { documented: boolean };
+ safety: { safetyDocPresent: boolean; budgetDoc: boolean };
+ tests: { present: boolean };
+ ci: { present: boolean };
+ runLog: { present: boolean };
+}
+
+export interface Finding {
+ level: 'ok' | 'warn' | 'fail';
+ message: string;
+}
+
+export interface AuditResult {
+ target: string;
+ score: number;
+ level: 'G0' | 'G1' | 'G2' | 'G3';
+ assessment: string;
+ signals: GoalSignals;
+ findings: Finding[];
+ recommendations: string[];
+}
+
+const GOAL_FILES = ['GOAL.md', 'goal.md', 'docs/GOAL.md'];
+const GOAL_SKILL_NAMES = [
+ 'goal-verifier',
+ 'goal-scoper',
+ 'goal-completion-check',
+];
+const SAFETY_FILES = ['docs/safety.md', 'SECURITY.md', 'safety.md'];
+const BUDGET_FILES = ['goal-budget.md', 'docs/goal-budget.md'];
+const RUN_LOG_FILES = ['goal-run-log.md', 'docs/goal-run-log.md'];
+
+async function fileExists(p: string): Promise<boolean> {
+ try {
+ await stat(p);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function findSkills(root: string): Promise<string[]> {
+ const dirs = [
+ path.join(root, '.grok', 'skills'),
+ path.join(root, '.claude', 'skills'),
+ path.join(root, '.codex', 'skills'),
+ path.join(root, 'skills'),
+ ];
+ const found: string[] = [];
+ for (const dir of dirs) {
+ if (!(await fileExists(dir))) continue;
+ const entries = await readdir(dir, { withFileTypes: true });
+ for (const e of entries) {
+ if (e.isDirectory()) found.push(e.name);
+ }
+ }
+ return found;
+}
+
+async function detectTests(root: string): Promise<boolean> {
+ const hints = [
+ 'package.json',
+ 'pyproject.toml',
+ 'go.mod',
+ 'Cargo.toml',
+ 'vitest.config.ts',
+ 'jest.config.js',
+ 'pytest.ini',
+ ];
+ for (const h of hints) {
+ if (await fileExists(path.join(root, h))) return true;
+ }
+ const testDirs = ['tests', 'test', '__tests__'];
+ for (const d of testDirs) {
+ if (await fileExists(path.join(root, d))) return true;
+ }
+ return false;
+}
+
+async function detectCi(root: string): Promise<boolean> {
+ const ciPaths = [
+ '.github/workflows',
+ '.gitlab-ci.yml',
+ 'Jenkinsfile',
+ ];
+ for (const p of ciPaths) {
+ if (await fileExists(path.join(root, p))) return true;
+ }
+ return false;
+}
+
+function scoreLevel(score: number): AuditResult['level'] {
+ if (score >= 80) return 'G3';
+ if (score >= 60) return 'G2';
+ if (score >= 40) return 'G1';
+ return 'G0';
+}
+
+function assessmentFor(level: AuditResult['level']): string {
+ switch (level) {
+ case 'G3':
+ return 'production-ready goal workflows';
+ case 'G2':
+ return 'verified goals with checker split';
+ case 'G1':
+ return 'assisted goals — add verifier for G2';
+ default:
+ return 'ad hoc — scaffold GOAL.md and skills';
+ }
+}
+
+export async function auditProject(target: string): Promise<AuditResult> {
+ const root = path.resolve(target);
+ const findings: Finding[] = [];
+ const recommendations: string[] = [];
+ let score = 0;
+
+ const goalPaths: string[] = [];
+ for (const f of GOAL_FILES) {
+ if (await fileExists(path.join(root, f))) goalPaths.push(f);
+ }
+ const goalFilePresent = goalPaths.length > 0;
+ if (goalFilePresent) {
+ score += 15;
+ findings.push({ level: 'ok', message: `GOAL file present (${goalPaths.join(', ')})` });
+ } else {
+ findings.push({ level: 'fail', message: 'No GOAL.md — goals will not survive compaction' });
+ recommendations.push('cp templates/GOAL.md.template GOAL.md');
+ }
+
+ const goalConfigPresent = await fileExists(path.join(root, 'GOAL.md'));
+ if (goalConfigPresent) score += 5;
+
+ const allSkills = await findSkills(root);
+ const goalSkills = allSkills.filter((s) => GOAL_SKILL_NAMES.includes(s));
+ if (goalSkills.length > 0) {
+ score += 10 + Math.min(goalSkills.length * 5, 15);
+ findings.push({ level: 'ok', message: `Goal skills: ${goalSkills.join(', ')}` });
+ } else {
+ findings.push({ level: 'warn', message: 'No goal-verifier / goal-scoper skills found' });
+ recommendations.push('cp -r starters/minimal-goal/.grok/skills/goal-verifier .grok/skills/');
+ }
+
+ const verifierPresent = goalSkills.includes('goal-verifier') || allSkills.some((s) => s.includes('verifier'));
+ if (verifierPresent) {
+ score += 20;
+ findings.push({ level: 'ok', message: 'Verifier skill or agent present' });
+ } else {
+ findings.push({ level: 'fail', message: 'No verifier — implementer may self-grade' });
+ recommendations.push('Add goal-verifier skill from skills/goal-verifier/');
+ }
+
+ const scoperPresent = goalSkills.includes('goal-scoper');
+ if (scoperPresent) score += 5;
+
+ const agentsPath = path.join(root, 'AGENTS.md');
+ const agentsPresent = await fileExists(agentsPath);
+ let mentionsGoal = false;
+ if (agentsPresent) {
+ const content = await readFile(agentsPath, 'utf8');
+ mentionsGoal = /goal|update_goal|GOAL\.md/i.test(content);
+ score += mentionsGoal ? 10 : 5;
+ findings.push({
+ level: mentionsGoal ? 'ok' : 'warn',
+ message: mentionsGoal ? 'AGENTS.md mentions goal discipline' : 'AGENTS.md present but no goal rules',
+ });
+ if (!mentionsGoal) {
+ recommendations.push('Add goal rules to AGENTS.md: verifier before completed: true');
+ }
+ } else {
+ findings.push({ level: 'warn', message: 'No AGENTS.md' });
+ recommendations.push('gbs scaffold agents-md --write (from grok-build-showcase) or write AGENTS.md');
+ }
+
+ const patternsPresent =
+ (await fileExists(path.join(root, 'patterns'))) ||
+ (await fileExists(path.join(root, 'docs', 'api-reference.md')));
+ if (patternsPresent) {
+ score += 5;
+ findings.push({ level: 'ok', message: 'Goal patterns or API docs present' });
+ }
+
+ let safetyDocPresent = false;
+ for (const f of SAFETY_FILES) {
+ if (await fileExists(path.join(root, f))) {
+ safetyDocPresent = true;
+ break;
+ }
+ }
+ let budgetDoc = false;
+ for (const f of BUDGET_FILES) {
+ if (await fileExists(path.join(root, f))) {
+ budgetDoc = true;
+ break;
+ }
+ }
+ if (safetyDocPresent) score += 5;
+ if (budgetDoc) {
+ score += 10;
+ findings.push({ level: 'ok', message: 'Goal budget documented' });
+ } else {
+ recommendations.push('cp templates/goal-budget.md.template goal-budget.md');
+ }
+
+ const testsPresent = await detectTests(root);
+ if (testsPresent) {
+ score += 15;
+ findings.push({ level: 'ok', message: 'Test harness detected' });
+ } else {
+ findings.push({ level: 'warn', message: 'No test harness — done conditions are subjective' });
+ }
+
+ const ciPresent = await detectCi(root);
+ if (ciPresent) {
+ score += 10;
+ findings.push({ level: 'ok', message: 'CI configuration present' });
+ }
+
+ let runLog = false;
+ for (const f of RUN_LOG_FILES) {
+ if (await fileExists(path.join(root, f))) {
+ runLog = true;
+ break;
+ }
+ }
+ if (runLog) {
+ score += 5;
+ findings.push({ level: 'ok', message: 'Goal run log present' });
+ }
+
+ score = Math.min(100, score);
+ const level = scoreLevel(score);
+
+ if (level === 'G0') {
+ recommendations.push('Read docs/goal-design-checklist.md and starters/minimal-goal/');
+ }
+ if (level === 'G1' && !verifierPresent) {
+ recommendations.push('Graduate to G2: add goal-verifier before unattended goals');
+ }
+
+ return {
+ target: root,
+ score,
+ level,
+ assessment: assessmentFor(level),
+ signals: {
+ goalFile: { present: goalFilePresent, path: goalPaths[0] },
+ goalConfig: { present: goalConfigPresent },
+ skills: { count: allSkills.length, goalSkills },
+ verifier: { present: verifierPresent },
+ scoper: { present: scoperPresent },
+ agentsMd: { present: agentsPresent, mentionsGoal },
+ patterns: { documented: patternsPresent },
+ safety: { safetyDocPresent, budgetDoc },
+ tests: { present: testsPresent },
+ ci: { present: ciPresent },
+ runLog: { present: runLog },
+ },
+ findings,
+ recommendations: [...new Set(recommendations)],
+ };
+}
\ No newline at end of file
diff --git a/tools/goal-audit/src/cli.ts b/tools/goal-audit/src/cli.ts
new file mode 100644
index 0000000..23a02a5
--- /dev/null
+++ b/tools/goal-audit/src/cli.ts
@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { auditProject } from './auditor.js';
+import { formatHuman, formatJson, formatMarkdown } from './reporter.js';
+
+const args = process.argv.slice(2);
+const target = args.find((a) => !a.startsWith('-')) || '.';
+const json = args.includes('--json');
+const md = args.includes('--md');
+const suggest = args.includes('--suggest') || args.includes('--fix');
+const help = args.includes('--help') || args.includes('-h');
+
+if (help) {
+ console.log(`goal-audit — Goal Readiness Score CLI (G0–G3)
+
+Usage:
+ goal-audit [path] [options]
+
+Options:
+ --json JSON output (for CI / scripting)
+ --md Markdown report
+ --suggest Show copy-from-template commands
+ --help, -h This help
+
+Scores goal readiness for Grok Build /goal:
+ GOAL.md, verifier skills, AGENTS.md, tests, CI, budget docs
+
+Exit codes:
+ 0 score >= 40
+ 2 score < 40
+
+Examples:
+ goal-audit .
+ goal-audit . --suggest
+ npx @cobusgreyling/goal-audit . --json
+`);
+ process.exit(0);
+}
+
+try {
+ const result = await auditProject(target);
+ if (json) console.log(formatJson(result));
+ else if (md) console.log(formatMarkdown(result));
+ else console.log(formatHuman(result));
+
+ if (suggest) {
+ console.log('\n=== Suggested actions ===');
+ console.log('');
+ console.log(' cp templates/GOAL.md.template GOAL.md');
+ console.log(' cp -r starters/minimal-goal/.grok/skills/goal-verifier .grok/skills/');
+ console.log(' cp templates/goal-budget.md.template goal-budget.md');
+ console.log(' cp templates/goal-run-log.md.template goal-run-log.md');
+ console.log('');
+ console.log(' # Then in Grok Build:');
+ console.log(' /goal Read GOAL.md. Work the objective. goal-verifier before completed: true.');
+ console.log('');
+ console.log(' Docs: https://github.com/cobusgreyling/goal-engineering');
+ }
+
+ process.exit(result.score >= 40 ? 0 : 2);
+} catch (err) {
+ console.error('goal-audit error:', err instanceof Error ? err.message : err);
+ process.exit(1);
+}
\ No newline at end of file
diff --git a/tools/goal-audit/src/reporter.ts b/tools/goal-audit/src/reporter.ts
new file mode 100644
index 0000000..39149bb
--- /dev/null
+++ b/tools/goal-audit/src/reporter.ts
@@ -0,0 +1,51 @@
+import type { AuditResult } from './auditor.js';
+
+const ICON = { ok: '✓', warn: '△', fail: '✗' } as const;
+
+export function formatHuman(result: AuditResult): string {
+ const lines: string[] = [];
+ lines.push(`Goal Readiness Score: ${result.score}/100 (${result.level} — ${result.assessment})`);
+ lines.push(`Target: ${result.target}`);
+ lines.push('');
+ for (const f of result.findings) {
+ lines.push(`${ICON[f.level]} ${f.message}`);
+ }
+ if (result.recommendations.length > 0) {
+ lines.push('');
+ lines.push('Recommendations:');
+ for (const r of result.recommendations) {
+ lines.push(` • ${r}`);
+ }
+ }
+ return lines.join('\n');
+}
+
+export function formatJson(result: AuditResult): string {
+ return JSON.stringify(result, null, 2);
+}
+
+export function formatMarkdown(result: AuditResult): string {
+ const lines: string[] = [];
+ lines.push('# Goal Readiness Audit');
+ lines.push('');
+ lines.push(`| Metric | Value |`);
+ lines.push(`|--------|-------|`);
+ lines.push(`| Score | ${result.score}/100 |`);
+ lines.push(`| Level | ${result.level} |`);
+ lines.push(`| Assessment | ${result.assessment} |`);
+ lines.push('');
+ lines.push('## Findings');
+ lines.push('');
+ for (const f of result.findings) {
+ lines.push(`- ${ICON[f.level]} ${f.message}`);
+ }
+ if (result.recommendations.length > 0) {
+ lines.push('');
+ lines.push('## Recommendations');
+ lines.push('');
+ for (const r of result.recommendations) {
+ lines.push(`- ${r}`);
+ }
+ }
+ return lines.join('\n');
+}
\ No newline at end of file
diff --git a/tools/goal-audit/test/auditor.test.mjs b/tools/goal-audit/test/auditor.test.mjs
new file mode 100644
index 0000000..bfbfc6c
--- /dev/null
+++ b/tools/goal-audit/test/auditor.test.mjs
@@ -0,0 +1,22 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { auditProject } from '../dist/auditor.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '../../..');
+
+test('goal-engineering repo scores G2+', async () => {
+ const result = await auditProject(repoRoot);
+ assert.ok(result.score >= 60, `expected G2+, got ${result.score} (${result.level})`);
+ assert.equal(result.signals.verifier.present, true);
+ assert.equal(result.signals.goalFile.present, true);
+});
+
+test('empty temp dir scores low', async () => {
+ const tmp = path.join(repoRoot, 'tools/goal-audit/test/fixtures-empty');
+ const result = await auditProject(tmp);
+ assert.ok(result.score < 40);
+ assert.equal(result.level, 'G0');
+});
\ No newline at end of file
diff --git a/tools/goal-audit/tsconfig.json b/tools/goal-audit/tsconfig.json
new file mode 100644
index 0000000..479a610
--- /dev/null
+++ b/tools/goal-audit/tsconfig.json
@@ -0,0 +1,15 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "outDir": "dist",
+ "rootDir": "src",
+ "strict": true,
+ "declaration": true,
+ "declarationMap": true,
+ "sourceMap": true,
+ "skipLibCheck": true
+ },
+ "include": ["src/**/*"]
+}
\ No newline at end of file