The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs+chore: add README Security section; fix lint regressions on main
Affaan Mustafa351ccc5a3c4f
diff --git a/README.md b/README.mdindex 5f6692dd0..723f360bc 100644--- a/README.md+++ b/README.md@@ -20,7 +20,7 @@> [!WARNING]> **Official sources only.** Install ECC only from verified channels: the GitHub repository [github.com/affaan-m/ECC](https://github.com/affaan-m/ECC), the npm packages [`ecc-universal`](https://www.npmjs.com/package/ecc-universal) and [`ecc-agentshield`](https://www.npmjs.com/package/ecc-agentshield), the [GitHub App](https://github.com/apps/ecc-tools), the plugin slug `ecc@ecc`, and the project website [ecc.tools](https://ecc.tools). Third-party re-uploads and unofficial mirrors are not maintained or reviewed by the project and may contain malware.-> **211.9K+ stars** | **32.5K+ forks** | **230+ contributors** | **12+ language ecosystems** | **Cross-harness agent workflows**+**211.9K+ stars** | **32.5K+ forks** | **230+ contributors** | **12+ language ecosystems** | **Cross-harness agent workflows**---@@ -1808,6 +1808,17 @@ These configs work for my workflow. You should:---+## Security++ECC takes supply-chain and agent safety seriously.++- **Official sources only.** Install ECC only from the verified channels listed in the banner at the top of this README — the [GitHub repo](https://github.com/affaan-m/ECC), the `ecc-universal` / `ecc-agentshield` npm packages, the [GitHub App](https://github.com/apps/ecc-tools), the plugin slug `ecc@ecc`, and [ecc.tools](https://ecc.tools). Third-party re-uploads and mirrors are unreviewed and may ship malware.+- **Report a vulnerability.** Use the private process in [SECURITY.md](SECURITY.md) (GitHub private vulnerability reporting). Please do not open public issues for security reports.+- **Built-in guardrails.** GateGuard gates destructive shell commands (including `rm`, force/path `git checkout`, and destructive `find -exec`) before they run; the supply-chain IOC scanner runs in CI; and [AgentShield](#agentshield--security-auditor) audits your own agent, hook, MCP, permission, and secret surfaces (`/security-scan`).+- **Deep dive.** See the [Security Guide](./the-security-guide.md).++---+## SponsorsFeatured sponsors are at the top of this README — full list and tiers in [SPONSORS.md](SPONSORS.md). [Become a sponsor](https://github.com/sponsors/affaan-m).diff --git a/rules/vue/coding-style.md b/rules/vue/coding-style.mdindex f6c0e31b0..fbef678a7 100644--- a/rules/vue/coding-style.md+++ b/rules/vue/coding-style.md@@ -51,4 +51,4 @@ const open = defineModel<boolean>('open', { default: false })## Reference- ECC skills: `frontend-patterns`, `vite-patterns`.-- Docs: https://vuejs.org/api/sfc-script-setup.html · https://vuejs.org/guide/essentials/reactivity-fundamentals.html · https://eslint.vuejs.org/+- Docs: <https://vuejs.org/api/sfc-script-setup.html> · <https://vuejs.org/guide/essentials/reactivity-fundamentals.html> · <https://eslint.vuejs.org/>diff --git a/rules/vue/hooks.md b/rules/vue/hooks.mdindex b0c8d916f..16c92ca41 100644--- a/rules/vue/hooks.md+++ b/rules/vue/hooks.md@@ -42,4 +42,4 @@ vue-tsc --noEmit## Reference- ECC skills: `frontend-patterns`, `vite-patterns`.-- Docs: https://github.com/vuejs/language-tools (vue-tsc) · https://eslint.vuejs.org/ · https://github.com/feature-sliced/steiger+- Docs: <https://github.com/vuejs/language-tools> (vue-tsc) · <https://eslint.vuejs.org/> · <https://github.com/feature-sliced/steiger>diff --git a/rules/vue/patterns.md b/rules/vue/patterns.mdindex 35059f0f7..e5eb354de 100644--- a/rules/vue/patterns.md+++ b/rules/vue/patterns.md@@ -53,4 +53,4 @@ queryClient.invalidateQueries({ queryKey: ['auction', id] })## Reference- ECC skills: `frontend-patterns`, `vite-patterns`.-- Docs: https://pinia.vuejs.org/ · https://router.vuejs.org/ · https://tanstack.com/query/latest/docs/framework/vue/overview · https://vuejs.org/guide/reusability/composables.html+- Docs: <https://pinia.vuejs.org/> · <https://router.vuejs.org/> · <https://tanstack.com/query/latest/docs/framework/vue/overview> · <https://vuejs.org/guide/reusability/composables.html>diff --git a/rules/vue/security.md b/rules/vue/security.mdindex 6a04d333d..8f21953f7 100644--- a/rules/vue/security.md+++ b/rules/vue/security.md@@ -43,4 +43,4 @@ paths:## Reference- ECC skills: `frontend-patterns`, `vite-patterns`.-- Docs: https://vuejs.org/guide/best-practices/security.html · https://github.com/cure53/DOMPurify · https://github.com/braintree/sanitize-url+- Docs: <https://vuejs.org/guide/best-practices/security.html> · <https://github.com/cure53/DOMPurify> · <https://github.com/braintree/sanitize-url>diff --git a/rules/vue/testing.md b/rules/vue/testing.mdindex 7dbf9f07a..951712f82 100644--- a/rules/vue/testing.md+++ b/rules/vue/testing.md@@ -50,4 +50,4 @@ expect(wrapper.emitted('bid')).toBeTruthy()## Reference- ECC skills: `frontend-patterns`, `vite-patterns`.-- Docs: https://test-utils.vuejs.org/api/ · https://pinia.vuejs.org/cookbook/testing.html · https://vitest.dev/+- Docs: <https://test-utils.vuejs.org/api/> · <https://pinia.vuejs.org/cookbook/testing.html> · <https://vitest.dev/>diff --git a/scripts/hooks/run-with-flags.js b/scripts/hooks/run-with-flags.jsindex 41ff14623..37a10f38f 100755--- a/scripts/hooks/run-with-flags.js+++ b/scripts/hooks/run-with-flags.js@@ -100,9 +100,8 @@ function getPluginRoot() {return path.resolve(__dirname, '..', '..');}-//Safely extract target context from hook stdin JSON for dry-run preview.-+function extractTargetContext(raw) {const result = { tool: '', filePath: '', command: '' };if (!raw || typeof raw !== 'string') return result;@@ -118,18 +117,16 @@ function extractTargetContext(raw) {}}} catch {+ // best-effort field extraction; ignore malformed input}return result;}// Build the [DryRun] preview line for stderr.-+function buildDryRunPreview(hookId, relScriptPath, profilesCsv, raw) {const ctx = extractTargetContext(raw);- const parts = [- `[DryRun] Hook "${hookId}" would execute: ${relScriptPath}`,- `(enabled=true, profiles=${profilesCsv || 'default'})`,- ];+ const parts = [`[DryRun] Hook "${hookId}" would execute: ${relScriptPath}`, `(enabled=true, profiles=${profilesCsv || 'default'})`];if (ctx.tool) {parts.push(`tool=${ctx.tool}`);diff --git a/scripts/lib/github-coordination/parsing.js b/scripts/lib/github-coordination/parsing.jsindex 08bc3b54e..987067c16 100644--- a/scripts/lib/github-coordination/parsing.js+++ b/scripts/lib/github-coordination/parsing.js@@ -7,17 +7,12 @@ function escapeRegExp(str) {}function normalizeBodyForComparison(body) {- return (body || '').replace(/"lastSyncAt"\s*:\s*[^,\}\n]+/g, '"lastSyncAt": NORMALIZED');+ return (body || '').replace(/"lastSyncAt"\s*:\s*[^,}\n]+/g, '"lastSyncAt": NORMALIZED');}function extractCoordinationState(body, policy = DEFAULT_POLICY) {const marker = escapeRegExp(policy.sectionMarker || DEFAULT_SECTION_MARKER);- const regex = new RegExp(- `<!--\\s*${marker}:start\\s*-->\\s*` +- '```json\\s*([\\s\\S]*?)\\s*```' +- `\\s*<!--\\s*${marker}:end\\s*-->`,- 'm'- );+ const regex = new RegExp(`<!--\\s*${marker}:start\\s*-->\\s*` + '```json\\s*([\\s\\S]*?)\\s*```' + `\\s*<!--\\s*${marker}:end\\s*-->`, 'm');const match = String(body || '').match(regex);if (!match) {@@ -28,9 +23,7 @@ function extractCoordinationState(body, policy = DEFAULT_POLICY) {const parsed = JSON.parse(match[1]);return parsed && typeof parsed === 'object' ? parsed : null;} catch (error) {- throw new SyntaxError(- `Malformed coordination JSON in body: ${error.message} — raw: ${match[1].slice(0, 120)}`- );+ throw new SyntaxError(`Malformed coordination JSON in body: ${error.message} — raw: ${match[1].slice(0, 120)}`);}}@@ -40,7 +33,9 @@ function extractIssueReferences(text) {for (const match of source.matchAll(/(?:^|[^\d])#(\d+)\b/g)) {refs.add(Number.parseInt(match[1], 10));}- return Array.from(refs).filter(Number.isFinite).sort((a, b) => a - b);+ return Array.from(refs)+ .filter(Number.isFinite)+ .sort((a, b) => a - b);}function extractTasks(body) {@@ -62,7 +57,7 @@ function extractTasks(body) {if (taskMatch) {tasks.push({title: taskMatch[2].trim(),- done: taskMatch[1].toLowerCase() === 'x',+ done: taskMatch[1].toLowerCase() === 'x'});}}@@ -98,26 +93,17 @@ function renderCoordinationState(state, policy = DEFAULT_POLICY) {lastAction: state.lastAction || 'sync',lastActionAt: state.lastActionAt || new Date().toISOString(),lastSyncAt: state.lastSyncAt || new Date().toISOString(),- notes: state.notes || null,+ notes: state.notes || null};- return [- `<!-- ${marker}:start -->`,- '```json',- JSON.stringify(payload, null, 2),- '```',- `<!-- ${marker}:end -->`,- ].join('\n');+ return [`<!-- ${marker}:start -->`, '```json', JSON.stringify(payload, null, 2), '```', `<!-- ${marker}:end -->`].join('\n');}function mergeIssueBody(issue, nextState, policy = DEFAULT_POLICY) {const body = String(issue.body || '');const markerEscaped = escapeRegExp(policy.sectionMarker || DEFAULT_SECTION_MARKER);const rendered = renderCoordinationState(nextState, policy);- const regex = new RegExp(- `\\n?<!--\\s*${markerEscaped}:start\\s*-->[\\s\\S]*?<!--\\s*${markerEscaped}:end\\s*-->\\n?`,- 'm'- );+ const regex = new RegExp(`\\n?<!--\\s*${markerEscaped}:start\\s*-->[\\s\\S]*?<!--\\s*${markerEscaped}:end\\s*-->\\n?`, 'm');if (regex.test(body)) {return body.replace(regex, `\n${rendered}\n`).trim() + '\n';@@ -139,5 +125,5 @@ module.exports = {mergeIssueBody,normalizeBodyForComparison,parseStringList,- renderCoordinationState,+ renderCoordinationState};diff --git a/tests/scripts/github-coordination.test.js b/tests/scripts/github-coordination.test.jsindex aca4edbfb..158fc7c91 100644--- a/tests/scripts/github-coordination.test.js+++ b/tests/scripts/github-coordination.test.js@@ -6,7 +6,7 @@ const assert = require('assert');const fs = require('fs');const os = require('os');const path = require('path');-const { execFileSync, spawnSync } = require('child_process');+const { spawnSync } = require('child_process');const { createStateStore } = require('../../scripts/lib/state-store');@@ -23,7 +23,9 @@ function cleanup(dirPath) {function writeGhShim(rootDir, responses) {const shimPath = path.join(rootDir, 'gh-shim.js');const logPath = path.join(rootDir, 'gh-calls.jsonl');- fs.writeFileSync(shimPath, `+ fs.writeFileSync(+ shimPath,+ `const fs = require('fs');const responses = ${JSON.stringify(responses)};const args = process.argv.slice(2);@@ -42,7 +44,8 @@ if (args[0] === 'issue' && (args[1] === 'edit' || args[1] === 'comment')) {}console.error('Unexpected gh args: ' + key);process.exit(3);-`);+`+ );return { shimPath, logPath };}@@ -51,11 +54,11 @@ function run(args = [], options = {}) {cwd: options.cwd || path.join(__dirname, '..', '..'),env: {...process.env,- ...(options.env || {}),+ ...(options.env || {})},encoding: 'utf8',stdio: ['pipe', 'pipe', 'pipe'],- timeout: 10000,+ timeout: 10000});}@@ -90,143 +93,155 @@ async function runTests() {let passed = 0;let failed = 0;- if (await test('claims an epic issue, updates GitHub state, and caches a work item', async () => {- const rootDir = createTempDir('github-coordination-claim-');- const dbPath = path.join(rootDir, 'state.db');-- try {- const epicBody = [- '# Ship GitHub-native coordination',- '',- 'We want deterministic epic state.',- '',- '## Tasks',- '- [ ] Claim the epic',- '- [ ] Validate the epic',- ].join('\n');- const issueView = {- number: 12,- title: 'Ship GitHub-native coordination',- body: epicBody,- url: 'https://github.com/affaan-m/ECC/issues/12',- state: 'OPEN',- labels: [{ name: 'epic' }],- author: { login: 'maintainer' },- updatedAt: '2026-06-01T12:00:00Z',- };- const shim = writeGhShim(rootDir, {- 'issue view 12 --repo affaan-m/ECC --json number,title,body,url,state,labels,author,updatedAt,assignees': issueView,- });-- const result = run(['claim', '12', '--repo', 'affaan-m/ECC', '--actor', 'codex', '--db', dbPath, '--json'], {- cwd: rootDir,- env: {- ECC_GH_SHIM: shim.shimPath,- ECC_GH_SHIM_LOG: shim.logPath,- },- });- assert.strictEqual(result.status, 0, result.stderr);- const payload = parseJson(result.stdout);- assert.strictEqual(payload.status, 'claimed');- assert.strictEqual(payload.owner, 'codex');- assert.strictEqual(payload.project.state, 'in-progress');-- const logEntries = fs.readFileSync(shim.logPath, 'utf8').trim().split(/\r?\n/).map(line => JSON.parse(line));- assert.ok(logEntries.some(entry => entry.args[0] === 'issue' && entry.args[1] === 'edit'));- assert.ok(logEntries.some(entry => entry.args[0] === 'issue' && entry.args[1] === 'comment'));-- const stored = await readStore(dbPath);- const epicItem = stored.items.find(item => item.source === 'github-epic');- assert.ok(epicItem, 'expected github epic work item');- assert.strictEqual(epicItem.status, 'in-progress');- assert.strictEqual(epicItem.metadata.coordination.status, 'claimed');- assert.strictEqual(epicItem.metadata.coordination.owner, 'codex');- } finally {- cleanup(rootDir);- }- })) passed++; else failed++;-- if (await test('unblocks an epic when dependencies are closed', async () => {- const rootDir = createTempDir('github-coordination-unblock-');- const dbPath = path.join(rootDir, 'state.db');-- try {- const blockedBody = [- '# Release readiness',- '',- 'Dependencies: #2',- '',- '<!-- ecc-coordination:start -->',- '```json',- JSON.stringify({- schemaVersion: 'ecc.github.coordination.v1',- kind: 'epic',- status: 'blocked',- owner: 'codex',- branch: 'feat/release-readiness',- validation: 'pending',- review: 'requested',- project: { state: 'blocked', fields: {} },- dependencies: [2],- tasks: [{ title: 'Check release checklist', done: false }],- labels: ['epic', 'coordination:blocked'],- lastAction: 'claim',- lastActionAt: '2026-06-01T13:00:00Z',- lastSyncAt: '2026-06-01T13:00:00Z',- notes: null,- }, null, 2),- '```',- '<!-- ecc-coordination:end -->',- ].join('\n');- const openIssue = {- number: 1,- title: 'Release readiness',- body: blockedBody,- url: 'https://github.com/affaan-m/ECC/issues/1',- state: 'OPEN',- labels: [{ name: 'epic' }, { name: 'coordination:blocked' }],- author: { login: 'codex' },- updatedAt: '2026-06-01T13:00:00Z',- };- const closedDependency = {- number: 2,- title: 'Release prerequisite',- body: '# Release prerequisite',- url: 'https://github.com/affaan-m/ECC/issues/2',- state: 'CLOSED',- labels: [{ name: 'blocked-by-release' }],- author: { login: 'maintainer' },- updatedAt: '2026-06-01T10:00:00Z',- };- const shim = writeGhShim(rootDir, {- 'issue list --repo affaan-m/ECC --state all --limit 100 --json number,title,body,url,state,labels,author,updatedAt,assignees': [openIssue, closedDependency],- 'issue view 1 --repo affaan-m/ECC --json number,title,body,url,state,labels,author,updatedAt,assignees': openIssue,- });-- const result = run(['unblock', '--repo', 'affaan-m/ECC', '--db', dbPath, '--json'], {- cwd: rootDir,- env: {- ECC_GH_SHIM: shim.shimPath,- ECC_GH_SHIM_LOG: shim.logPath,- },- });- assert.strictEqual(result.status, 0, result.stderr);- const payload = parseJson(result.stdout);- assert.strictEqual(payload.count, 1);- assert.strictEqual(payload.items[0].status, 'ready');-- const logEntries = fs.readFileSync(shim.logPath, 'utf8').trim().split(/\r?\n/).map(line => JSON.parse(line));- assert.ok(logEntries.some(entry => entry.args[0] === 'issue' && entry.args[1] === 'edit'));- assert.ok(logEntries.some(entry => entry.args[0] === 'issue' && entry.args[1] === 'comment'));-- const stored = await readStore(dbPath);- const epicItem = stored.items.find(item => item.source === 'github-epic');- assert.ok(epicItem, 'expected github epic work item');- assert.strictEqual(epicItem.metadata.coordination.status, 'ready');- } finally {- cleanup(rootDir);- }- })) passed++; else failed++;+ if (+ await test('claims an epic issue, updates GitHub state, and caches a work item', async () => {+ const rootDir = createTempDir('github-coordination-claim-');+ const dbPath = path.join(rootDir, 'state.db');++ try {+ const epicBody = ['# Ship GitHub-native coordination', '', 'We want deterministic epic state.', '', '## Tasks', '- [ ] Claim the epic', '- [ ] Validate the epic'].join('\n');+ const issueView = {+ number: 12,+ title: 'Ship GitHub-native coordination',+ body: epicBody,+ url: 'https://github.com/affaan-m/ECC/issues/12',+ state: 'OPEN',+ labels: [{ name: 'epic' }],+ author: { login: 'maintainer' },+ updatedAt: '2026-06-01T12:00:00Z'+ };+ const shim = writeGhShim(rootDir, {+ 'issue view 12 --repo affaan-m/ECC --json number,title,body,url,state,labels,author,updatedAt,assignees': issueView+ });++ const result = run(['claim', '12', '--repo', 'affaan-m/ECC', '--actor', 'codex', '--db', dbPath, '--json'], {+ cwd: rootDir,+ env: {+ ECC_GH_SHIM: shim.shimPath,+ ECC_GH_SHIM_LOG: shim.logPath+ }+ });+ assert.strictEqual(result.status, 0, result.stderr);+ const payload = parseJson(result.stdout);+ assert.strictEqual(payload.status, 'claimed');+ assert.strictEqual(payload.owner, 'codex');+ assert.strictEqual(payload.project.state, 'in-progress');++ const logEntries = fs+ .readFileSync(shim.logPath, 'utf8')+ .trim()+ .split(/\r?\n/)+ .map(line => JSON.parse(line));+ assert.ok(logEntries.some(entry => entry.args[0] === 'issue' && entry.args[1] === 'edit'));+ assert.ok(logEntries.some(entry => entry.args[0] === 'issue' && entry.args[1] === 'comment'));++ const stored = await readStore(dbPath);+ const epicItem = stored.items.find(item => item.source === 'github-epic');+ assert.ok(epicItem, 'expected github epic work item');+ assert.strictEqual(epicItem.status, 'in-progress');+ assert.strictEqual(epicItem.metadata.coordination.status, 'claimed');+ assert.strictEqual(epicItem.metadata.coordination.owner, 'codex');+ } finally {+ cleanup(rootDir);+ }+ })+ )+ passed++;+ else failed++;++ if (+ await test('unblocks an epic when dependencies are closed', async () => {+ const rootDir = createTempDir('github-coordination-unblock-');+ const dbPath = path.join(rootDir, 'state.db');++ try {+ const blockedBody = [+ '# Release readiness',+ '',+ 'Dependencies: #2',+ '',+ '<!-- ecc-coordination:start -->',+ '```json',+ JSON.stringify(+ {+ schemaVersion: 'ecc.github.coordination.v1',+ kind: 'epic',+ status: 'blocked',+ owner: 'codex',+ branch: 'feat/release-readiness',+ validation: 'pending',+ review: 'requested',+ project: { state: 'blocked', fields: {} },+ dependencies: [2],+ tasks: [{ title: 'Check release checklist', done: false }],+ labels: ['epic', 'coordination:blocked'],+ lastAction: 'claim',+ lastActionAt: '2026-06-01T13:00:00Z',+ lastSyncAt: '2026-06-01T13:00:00Z',+ notes: null+ },+ null,+ 2+ ),+ '```',+ '<!-- ecc-coordination:end -->'+ ].join('\n');+ const openIssue = {+ number: 1,+ title: 'Release readiness',+ body: blockedBody,+ url: 'https://github.com/affaan-m/ECC/issues/1',+ state: 'OPEN',+ labels: [{ name: 'epic' }, { name: 'coordination:blocked' }],+ author: { login: 'codex' },+ updatedAt: '2026-06-01T13:00:00Z'+ };+ const closedDependency = {+ number: 2,+ title: 'Release prerequisite',+ body: '# Release prerequisite',+ url: 'https://github.com/affaan-m/ECC/issues/2',+ state: 'CLOSED',+ labels: [{ name: 'blocked-by-release' }],+ author: { login: 'maintainer' },+ updatedAt: '2026-06-01T10:00:00Z'+ };+ const shim = writeGhShim(rootDir, {+ 'issue list --repo affaan-m/ECC --state all --limit 100 --json number,title,body,url,state,labels,author,updatedAt,assignees': [openIssue, closedDependency],+ 'issue view 1 --repo affaan-m/ECC --json number,title,body,url,state,labels,author,updatedAt,assignees': openIssue+ });++ const result = run(['unblock', '--repo', 'affaan-m/ECC', '--db', dbPath, '--json'], {+ cwd: rootDir,+ env: {+ ECC_GH_SHIM: shim.shimPath,+ ECC_GH_SHIM_LOG: shim.logPath+ }+ });+ assert.strictEqual(result.status, 0, result.stderr);+ const payload = parseJson(result.stdout);+ assert.strictEqual(payload.count, 1);+ assert.strictEqual(payload.items[0].status, 'ready');++ const logEntries = fs+ .readFileSync(shim.logPath, 'utf8')+ .trim()+ .split(/\r?\n/)+ .map(line => JSON.parse(line));+ assert.ok(logEntries.some(entry => entry.args[0] === 'issue' && entry.args[1] === 'edit'));+ assert.ok(logEntries.some(entry => entry.args[0] === 'issue' && entry.args[1] === 'comment'));++ const stored = await readStore(dbPath);+ const epicItem = stored.items.find(item => item.source === 'github-epic');+ assert.ok(epicItem, 'expected github epic work item');+ assert.strictEqual(epicItem.metadata.coordination.status, 'ready');+ } finally {+ cleanup(rootDir);+ }+ })+ )+ passed++;+ else failed++;process.stdout.write(`\nResults: Passed: ${passed}, Failed: ${failed}\n`);process.exit(failed > 0 ? 1 : 0);