Skip to content

DataArt/artisyn-implementation-harness / skills/implementation-harness

implementation-harness

Flagged

Install the portable AI-dev harness, rebuild its operational graph standalone, harvest project skill improvements into its canonical templates, package direct canonical edits into a portable bundle, or apply canonical updates to an existing project. Use /implementation-harness launch, /implementation-harness reindex-graph, or /implementation-harness patch harvest|prepare|apply.

FileKindSize
CHANGELOG.mdmarkdown37.5 KB
README.mdmarkdown13.7 KB
SKILL.mdskill md9.6 KB
bin/artisyn-implementation-harness.mjsexecutablescript11.8 KB
bin/lib/placer.mjsscript2.6 KB
bin/lib/providers.mjsscript1.8 KB
bin/lib/reporter.mjsscript3.0 KB
bin/lib/zip.mjsscript4.0 KB
canonical/adaptors/claude/browser.mdmarkdown2.5 KB
canonical/adaptors/claude/context.mdmarkdown517 B
canonical/adaptors/claude/credentials.mdmarkdown512 B
canonical/adaptors/claude/delegation.mdmarkdown910 B
canonical/adaptors/claude/interaction.mdmarkdown359 B
canonical/adaptors/claude/planning.mdmarkdown745 B
canonical/adaptors/claude/review.mdmarkdown1.0 KB
canonical/adaptors/claude/task-tracking.mdmarkdown897 B
canonical/adaptors/codex/browser.mdmarkdown1.0 KB
canonical/adaptors/codex/context.mdmarkdown517 B
canonical/adaptors/codex/credentials.mdmarkdown480 B
canonical/adaptors/codex/delegation.mdmarkdown910 B
canonical/adaptors/codex/interaction.mdmarkdown359 B
canonical/adaptors/codex/planning.mdmarkdown904 B
canonical/adaptors/codex/review.mdmarkdown973 B
canonical/adaptors/codex/task-tracking.mdmarkdown1.1 KB
canonical/adaptors/copilot/browser.mdmarkdown620 B
canonical/adaptors/copilot/context.mdmarkdown881 B
canonical/adaptors/copilot/credentials.mdmarkdown992 B
canonical/adaptors/copilot/delegation.mdmarkdown1.2 KB
canonical/adaptors/copilot/interaction.mdmarkdown454 B
canonical/adaptors/copilot/planning.mdmarkdown785 B
canonical/adaptors/copilot/review.mdmarkdown791 B
canonical/adaptors/copilot/task-tracking.mdmarkdown723 B
canonical/agents/architect/INTENT.mdmarkdown2.4 KB
canonical/agents/architect/TEMPLATE.mdmarkdown6.5 KB
canonical/agents/docs-writer/INTENT.mdmarkdown2.2 KB
canonical/agents/docs-writer/TEMPLATE.mdmarkdown2.8 KB
canonical/agents/infra/INTENT.mdmarkdown2.1 KB
canonical/agents/infra/TEMPLATE.mdmarkdown5.1 KB
canonical/agents/layer/INTENT.mdmarkdown6.0 KB
canonical/agents/layer/TEMPLATE.mdmarkdown1.5 KB
canonical/agents/onboarding/INTENT.mdmarkdown5.3 KB
canonical/agents/onboarding/TEMPLATE.mdmarkdown4.2 KB
canonical/agents/product-architect/INTENT.mdmarkdown7.5 KB
canonical/agents/product-architect/TEMPLATE.mdmarkdown3.9 KB
canonical/agents/scrum-master/INTENT.mdmarkdown10.9 KB
canonical/agents/scrum-master/TEMPLATE.mdmarkdown12.3 KB
canonical/docs/.og/cli.mjsscript13.6 KB
canonical/docs/.og/cli.test.mjsscript19.6 KB
canonical/docs/.og/constants.mjsscript2.9 KB
canonical/docs/.og/docs-operational-graph.sqlitebinary24.0 KB
canonical/docs/.og/docs.mjsscript5.5 KB
canonical/docs/.og/edges.mjsscript5.8 KB
canonical/docs/.og/schema.mjsscript741 B
canonical/docs/.og/utils.mjsscript5.2 KB
canonical/docs/Engineering Guide/01 Conventions.mdmarkdown3.0 KB
canonical/docs/Engineering Guide/03 Engineer Role.mdmarkdown2.6 KB
canonical/docs/Engineering Guide/04 AI Coding Tool Compatibility.mdmarkdown3.6 KB
canonical/docs/Engineering Guide/05 MCP Setup.mdmarkdown6.6 KB
canonical/docs/Engineering Guide/Documentation/01 Principles.mdmarkdown15.3 KB
canonical/docs/Engineering Guide/Documentation/02 Structure.mdmarkdown3.8 KB
canonical/docs/Engineering Guide/Documentation/03 HLD Intent.mdmarkdown8.1 KB
canonical/docs/Engineering Guide/Documentation/04 LLD Intent.mdmarkdown9.7 KB
canonical/docs/Engineering Guide/Documentation/05 NFR Intent.mdmarkdown6.0 KB
canonical/docs/Engineering Guide/Documentation/07 Terminology.mdmarkdown1.4 KB
canonical/docs/Engineering Guide/Lifecycles/00 Overview.mdmarkdown5.8 KB
canonical/docs/Engineering Guide/Lifecycles/01 Dev Lifecycle.mdmarkdown19.9 KB
canonical/docs/Engineering Guide/Lifecycles/02 Design Lifecycle.mdmarkdown29.4 KB
canonical/docs/Engineering Guide/Lifecycles/03 Evolve Lifecycle.mdmarkdown7.0 KB
canonical/docs/Engineering Guide/Lifecycles/04 Architecture Lifecycle.mdmarkdown3.6 KB
canonical/docs/Engineering Guide/Lifecycles/05 Documents Flow.mdmarkdown9.5 KB
canonical/manifest.jsonconfig1.6 KB
canonical/mcp.jsonconfig23 B
canonical/root-instructions/INTERFACE.mdmarkdown3.3 KB
canonical/settings.jsonconfig332 B
canonical/skills/design/INTENT.mdmarkdown28.6 KB
canonical/skills/design/TEMPLATE.mdmarkdown19.0 KB
canonical/skills/design/interfaces/architecture.mdmarkdown2.8 KB
canonical/skills/design/interfaces/contract.mdmarkdown7.4 KB
canonical/skills/design/interfaces/design.mdmarkdown2.3 KB
canonical/skills/design/interfaces/efforts.mdmarkdown2.5 KB
canonical/skills/design/interfaces/stack.mdmarkdown1.6 KB
canonical/skills/design/patterns/announce-progress.mdmarkdown997 B
canonical/skills/design/patterns/approval-intelligent.mdmarkdown1.5 KB
canonical/skills/design/patterns/approval-sign-off.mdmarkdown2.4 KB
canonical/skills/design/patterns/context-resolution.mdmarkdown6.6 KB
canonical/skills/design/patterns/design-architect-review.mdmarkdown2.4 KB
canonical/skills/design/patterns/design-oq-triage.mdmarkdown3.8 KB
canonical/skills/design/patterns/design-quality-gate.mdmarkdown1.4 KB
canonical/skills/design/patterns/do-report-commit.mdmarkdown1.2 KB
canonical/skills/design/patterns/docs-writer-authoring.mdmarkdown3.6 KB
canonical/skills/design/patterns/metrics.mdmarkdown11.9 KB
canonical/skills/design/patterns/multi-decision-split.mdmarkdown3.6 KB
canonical/skills/design/patterns/phase-sign-off.mdmarkdown2.4 KB
canonical/skills/design/patterns/satellite-review.mdmarkdown1.5 KB
canonical/skills/design/patterns/session-continuity.mdmarkdown827 B
canonical/skills/design/patterns/task-tracking.mdmarkdown779 B
canonical/skills/design/patterns/waf-review.mdmarkdown4.2 KB
canonical/skills/design/patterns/write-confirm.mdmarkdown963 B
canonical/skills/design/references/00-decision-router.mdmarkdown3.8 KB
canonical/skills/design/references/00-router.mdmarkdown4.6 KB
canonical/skills/design/references/01-context-gathering.mdmarkdown8.1 KB
canonical/skills/design/references/02-ceremony.mdmarkdown4.6 KB
canonical/skills/design/references/03-frame.mdmarkdown6.7 KB
canonical/skills/design/references/04-research.mdmarkdown8.1 KB
canonical/skills/design/references/05-evaluate.mdmarkdown9.0 KB
canonical/skills/design/references/06-solution.mdmarkdown13.7 KB
canonical/skills/design/references/07-review-gate.mdmarkdown4.1 KB
canonical/skills/design/references/08-address-feedback.mdmarkdown8.0 KB
canonical/skills/design/references/09-publish.mdmarkdown8.9 KB
canonical/skills/design/references/10-completion.mdmarkdown7.4 KB
canonical/skills/design/scripts/constants.mjsscript2.0 KB
canonical/skills/design/scripts/design-metrics.mjsscript35.4 KB
canonical/skills/design/scripts/design-metrics.test.mjsscript12.0 KB
canonical/skills/design/scripts/utils.mjsscript3.1 KB
canonical/skills/design/templates/evaluate.mdmarkdown1.4 KB
canonical/skills/design/templates/frame.mdmarkdown2.6 KB
canonical/skills/design/templates/report.mdmarkdown4.8 KB
canonical/skills/design/templates/research.mdmarkdown2.4 KB
canonical/skills/design/templates/stat.jsonconfig1.7 KB
canonical/skills/design/templates/stat.schema.jsonconfig17.1 KB
canonical/skills/dev/INTENT.mdmarkdown15.9 KB
canonical/skills/dev/TEMPLATE.mdmarkdown9.0 KB
canonical/skills/dev/interfaces/intent.mdmarkdown2.6 KB
canonical/skills/dev/patterns/announce-progress.mdmarkdown1.1 KB
canonical/skills/dev/patterns/approval-intelligent.mdmarkdown1.5 KB
canonical/skills/dev/patterns/approval-sign-off.mdmarkdown1.9 KB
canonical/skills/dev/patterns/do-report-commit.mdmarkdown888 B
canonical/skills/dev/patterns/metrics.mdmarkdown17.7 KB
canonical/skills/dev/patterns/phase-sign-off.mdmarkdown2.2 KB
canonical/skills/dev/patterns/review-gate.mdmarkdown3.6 KB
canonical/skills/dev/patterns/satellite-review.mdmarkdown3.1 KB
canonical/skills/dev/patterns/session-continuity.mdmarkdown797 B
canonical/skills/dev/patterns/task-tracking.mdmarkdown766 B
canonical/skills/dev/patterns/write-confirm.mdmarkdown615 B
canonical/skills/dev/references/00-router.mdmarkdown2.2 KB
canonical/skills/dev/references/01-context-gathering.mdmarkdown10.3 KB
canonical/skills/dev/references/02-ceremony.mdmarkdown4.5 KB
canonical/skills/dev/references/03-plan.mdmarkdown14.2 KB
canonical/skills/dev/references/04-implement.mdmarkdown11.7 KB
canonical/skills/dev/references/05-test.mdmarkdown7.8 KB
canonical/skills/dev/references/06-document.mdmarkdown11.7 KB
canonical/skills/dev/references/07-completion.mdmarkdown6.3 KB
canonical/skills/dev/scripts/constants.mjsscript3.2 KB
canonical/skills/dev/scripts/quality.mjsscript9.1 KB
canonical/skills/dev/scripts/quality.test.mjsscript6.6 KB
canonical/skills/dev/scripts/timing.mjsscript38.1 KB
canonical/skills/dev/scripts/timing.test.mjsscript21.0 KB
canonical/skills/dev/scripts/utils.mjsscript3.1 KB
canonical/skills/dev/templates/plan.mdmarkdown3.3 KB
canonical/skills/dev/templates/report.mdmarkdown6.4 KB
canonical/skills/dev/templates/stat.jsonconfig1.4 KB
canonical/skills/dev/templates/stat.schema.jsonconfig29.3 KB
canonical/skills/evolve/INTENT.mdmarkdown1.6 KB
canonical/skills/evolve/TEMPLATE.mdmarkdown1.3 KB
canonical/skills/evolve/interfaces/improvement.mdmarkdown1.2 KB
canonical/skills/evolve/interfaces/reflection.mdmarkdown353 B
canonical/skills/evolve/interfaces/validation.mdmarkdown653 B
canonical/skills/evolve/patterns/task-tracking.mdmarkdown787 B
canonical/skills/evolve/references/00-router.mdmarkdown1.1 KB
canonical/skills/evolve/references/01-reflect.mdmarkdown805 B
canonical/skills/evolve/references/02-triage.mdmarkdown2.6 KB
canonical/skills/evolve/references/03-draft.mdmarkdown1.2 KB
canonical/skills/evolve/references/04-validate.mdmarkdown1.5 KB
canonical/skills/evolve/references/05-adopt.mdmarkdown1.5 KB
canonical/skills/war/INTENT.mdmarkdown4.5 KB
canonical/skills/war/TEMPLATE.mdmarkdown1.8 KB
canonical/skills/war/patterns/present-and-save.mdmarkdown1.0 KB
canonical/skills/war/patterns/scope-resolution.mdmarkdown830 B
canonical/skills/war/references/01-design.mdmarkdown3.4 KB
canonical/skills/war/references/02-implementation.mdmarkdown3.8 KB
canonical/skills/war/templates/design-report.mdmarkdown869 B
canonical/skills/war/templates/implementation-report.mdmarkdown1.8 KB
canonical/skills/where-we-are/INTENT.mdmarkdown3.3 KB
canonical/skills/where-we-are/TEMPLATE.mdmarkdown6.3 KB
canonical/skills/where-we-are/report-template.mdmarkdown2.0 KB
canonical/skills/x-ray/INTENT.mdmarkdown2.4 KB
canonical/skills/x-ray/TEMPLATE.mdmarkdown10.5 KB
implementation-harness.mdmarkdown1.4 KB
package.jsonmanifest696 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/CHANGELOG.md.patchother1.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/README.md.patchother1.9 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/SKILL.md.patchother2.5 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/agents/docs-writer/INTENT.md.patchother1.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/.og/cli.test.mjs.patchother846 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/Engineering Guide/04 AI Coding Tool Compatibility.md.patchother3.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/Engineering Guide/05 MCP Setup.md.patchother5.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/manifest.json.patchother662 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/settings.json.patchother150 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/skills/design/INTENT.md.patchother19.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/patterns/skill-authoring.md.patchother692 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/host-capabilities.md.patchother1.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01-launch.md.patchother1.1 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01a-launch-plan.md.patchother1.6 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01b-launch-install.md.patchother7.3 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/02-launch-questions.md.patchother5.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/08-provider-launch.md.patchother3.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/04-patch-harvest.md.patchother2.6 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/05-patch-apply.md.patchother3.0 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/06-patch-state.md.patchother7.1 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/scripts/lib/agent-format.mjs.patchother2.2 KB

canonical/docs/.og/cli.test.mjs

View on GitHub
import { test } from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { build, index, reindex, query, search, list, unedge } from './cli.mjs';
import { DB_FILE, EDGE_TYPES, SCAN_EDGE_TYPES } from './constants.mjs';

const here = path.dirname(fileURLToPath(import.meta.url));
const cliPath = path.join(here, 'cli.mjs');

/** @returns {string} A fresh scratch directory, removed by the caller via cleanup. */
function scratchDir() {
  return fs.mkdtempSync(path.join(os.tmpdir(), 'docs-graph-test-'));
}

/** Write `content` to `relPath` under `root`, creating parent directories. */
function writeDoc(root, relPath, content) {
  const full = path.join(root, relPath);
  fs.mkdirSync(path.dirname(full), { recursive: true });
  fs.writeFileSync(full, content);
  return full;
}

/** A fixture tree exercising each of the six named graduation edges, plus one
 * HLD/LLD mirror pair (consistent), one mirror gap, and one malformed name. */
function graduationFixture(root) {
  writeDoc(root, 'docs/Target Architecture (HLD)/v1/Containers/Web.md', '# Web\n');
  writeDoc(root, 'docs/System Architecture (LLD)/Web/README.md', '# Web LLD\n');
  writeDoc(root, 'docs/Target Architecture (HLD)/v1/Containers/Auth.md', '# Auth\n');
  // No docs/System Architecture (LLD)/Auth/ — a known mirrors-gap.
  writeDoc(root, 'docs/Target Architecture (HLD)/v1/Containers/-weird name-.md', '# Malformed\n');
  writeDoc(root, 'docs/Stories/[DEV-1] Example/impl/0-intent.md', '# Example intent\n');
  return root;
}

test('build() creates the schema on an empty tree; a second doc cannot claim an ID already in use', async () => {
  const dir = scratchDir();
  try {
    await build({ dir });
    assert.ok(fs.existsSync(path.join(dir, DB_FILE)));
    const a = writeDoc(dir, 'docs/a.md', '# A\n');
    const b = writeDoc(dir, 'docs/b.md', '# B\n');
    await index({ dir, doc: a, id: 'dup-1' });
    await assert.rejects(() => index({ dir, doc: b, id: 'dup-1' }));
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('index() assigns IDs additively, idempotently, and collision-safe', async () => {
  const dir = scratchDir();
  try {
    const docPath = writeDoc(dir, 'docs/Example.md', '# Example\n\nBody text.\n');
    await build({ dir });
    await index({ dir, doc: docPath });
    const once = fs.readFileSync(docPath, 'utf8');
    assert.match(once, /^---\nid: /);
    await index({ dir, doc: docPath });
    const twice = fs.readFileSync(docPath, 'utf8');
    assert.equal(once, twice, 'idempotent: a second index() must not reassign or touch the doc');
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('EDGE_TYPES names exactly the six Documents Flow graduation edges', () => {
  assert.deepEqual(
    [...EDGE_TYPES].sort(),
    [
      'impl-to-engineering-guide',
      'impl-to-hld',
      'impl-to-lld',
      'impl-to-readme',
      'story-to-hld',
      'story-to-product',
    ].sort()
  );
});

test('index() writes an authored (derived=0) graduation edge for each of the six named types', async () => {
  const dir = scratchDir();
  try {
    const story = writeDoc(dir, 'docs/Stories/[DEV-1] Example/impl/0-intent.md', '# Intent\n');
    const hld = writeDoc(dir, 'docs/Target Architecture (HLD)/v1/Containers/Web.md', '# Web\n');
    await build({ dir });
    await index({ dir, doc: story });
    await index({ dir, doc: hld });
    await index({ dir, doc: story, edge: 'story-to-hld', to: hld });
    const edges = await query({ dir, relatedTo: story, edge: 'story-to-hld' });
    assert.equal(edges.length, 1);
    assert.equal(edges[0].derived, 0);
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('index() rejects an edge type outside the six named types', async () => {
  const dir = scratchDir();
  try {
    const story = writeDoc(dir, 'docs/Stories/[DEV-1] Example/impl/0-intent.md', '# Intent\n');
    const other = writeDoc(dir, 'docs/Other.md', '# Other\n');
    await build({ dir });
    await index({ dir, doc: story });
    await index({ dir, doc: other });
    await assert.rejects(() => index({ dir, doc: story, edge: 'not-a-real-edge', to: other }));
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('index() accepts the "references" scan-edge type, written derived=0, outside the six graduation types', async () => {
  const dir = scratchDir();
  try {
    const a = writeDoc(dir, 'docs/A.md', '# A\n\nSee [B](./B.md).\n');
    const b = writeDoc(dir, 'docs/B.md', '# B\n');
    await build({ dir });
    await index({ dir, doc: a });
    await index({ dir, doc: b });
    await index({ dir, doc: a, edge: SCAN_EDGE_TYPES[0], to: b });
    const edges = await query({ dir, relatedTo: a, edge: SCAN_EDGE_TYPES[0] });
    assert.equal(edges.length, 1);
    assert.equal(edges[0].derived, 0);
    assert.ok(
      !EDGE_TYPES.includes(SCAN_EDGE_TYPES[0]),
      'sanity: not one of the six graduation types'
    );
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('unedge() retracts a specific edge — the review/stale-edge-cleanup path', async () => {
  const dir = scratchDir();
  try {
    const a = writeDoc(dir, 'docs/A.md', '# A\n');
    const b = writeDoc(dir, 'docs/B.md', '# B\n');
    await build({ dir });
    await index({ dir, doc: a });
    await index({ dir, doc: b });
    await index({ dir, doc: a, edge: SCAN_EDGE_TYPES[0], to: b });
    assert.equal((await query({ dir, relatedTo: a, edge: SCAN_EDGE_TYPES[0] })).length, 1);

    await unedge({ dir, doc: a, edge: SCAN_EDGE_TYPES[0], to: b });
    assert.equal((await query({ dir, relatedTo: a, edge: SCAN_EDGE_TYPES[0] })).length, 0);

    // Retracting an already-gone edge is a no-op, not an error.
    await unedge({ dir, doc: a, edge: SCAN_EDGE_TYPES[0], to: b });
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('unedge() rejects an unindexed --doc or --to', async () => {
  const dir = scratchDir();
  try {
    const a = writeDoc(dir, 'docs/A.md', '# A\n');
    await build({ dir }); // indexes A.md; B.md doesn't exist yet, so it stays unindexed
    const b = writeDoc(dir, 'docs/B.md', '# B\n');
    await assert.rejects(() => unedge({ dir, doc: a, edge: SCAN_EDGE_TYPES[0], to: b }));
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('reindex() computes mirrors-consistent and mirrors-gap, and skips a malformed name without aborting', async () => {
  const dir = scratchDir();
  try {
    graduationFixture(dir);
    await build({ dir });
    const result = await reindex({ dir });
    assert.ok(result.skipped?.some((s) => /weird name/.test(s.path)));
    const webEdges = await query({
      dir,
      relatedTo: 'docs/Target Architecture (HLD)/v1/Containers/Web.md',
      edge: 'mirrors-consistent',
    });
    assert.ok(webEdges.length >= 1, 'Web HLD/LLD pair should mirror consistently');
    const authEdges = await query({
      dir,
      relatedTo: 'docs/Target Architecture (HLD)/v1/Containers/Auth.md',
      edge: 'mirrors-gap',
    });
    assert.ok(authEdges.length >= 1, 'Auth has no LLD folder — a known mirrors-gap');
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('reindex() computes keyword-match edges from the stored keywords column alone — no content read', async () => {
  const dir = scratchDir();
  try {
    const a = writeDoc(dir, 'docs/A.md', '---\nkeywords: [marine, tusked]\n---\n\n# A\n');
    const b = writeDoc(dir, 'docs/B.md', '---\nkeywords: [Marine, finned]\n---\n\n# B\n');
    const c = writeDoc(dir, 'docs/C.md', '---\nkeywords: [desert]\n---\n\n# C\n');
    await build({ dir });
    await index({ dir, doc: a });
    await index({ dir, doc: b });
    await index({ dir, doc: c });
    await reindex({ dir });
    const abEdges = await query({ dir, relatedTo: a, edge: 'keyword-match' });
    assert.equal(abEdges.length, 1, 'A and B share "marine" (case-insensitive)');
    assert.equal(abEdges[0].derived, 1);
    assert.ok(
      !(await query({ dir, relatedTo: c })).some((e) => e.edge_type === 'keyword-match'),
      'C shares no keywords with anything'
    );
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('reindex() clears stale keyword-match edges when keywords no longer overlap', async () => {
  const dir = scratchDir();
  try {
    const a = writeDoc(dir, 'docs/A.md', '---\nkeywords: [marine]\n---\n\n# A\n');
    const b = writeDoc(dir, 'docs/B.md', '---\nkeywords: [marine]\n---\n\n# B\n');
    await build({ dir });
    await index({ dir, doc: a });
    await index({ dir, doc: b });
    await reindex({ dir });
    assert.equal((await query({ dir, relatedTo: a, edge: 'keyword-match' })).length, 1);

    fs.writeFileSync(a, fs.readFileSync(a, 'utf8').replace('marine', 'desert'));
    await reindex({ dir });
    assert.equal(
      (await query({ dir, relatedTo: a, edge: 'keyword-match' })).length,
      0,
      'stale match should be cleared once keywords diverge'
    );
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('reindex() never indexes a path listed in docs/.ogignore, and prunes it if it was indexed before', async () => {
  const dir = scratchDir();
  try {
    writeDoc(dir, 'docs/Guide/01 Mine.md', '# Mine\n');
    const foreign = writeDoc(dir, 'docs/agents/tracker.md', '# Foreign\n');
    writeDoc(dir, 'docs/vendor/README.md', '# Vendor\n');
    await build({ dir });
    assert.ok(
      (await search({ dir, term: 'Foreign' })).length === 1,
      'sanity: indexed before ignore'
    );
    writeDoc(
      dir,
      'docs/.ogignore',
      '# owned by other tooling\ndocs/agents/tracker.md\ndocs/vendor/\n'
    );
    const result = await reindex({ dir });
    assert.equal(result.pruned.length, 2, 'both ignored docs leave the graph');
    assert.deepEqual(await search({ dir, term: 'Foreign' }), []);
    assert.deepEqual(await search({ dir, term: 'Vendor' }), []);
    assert.equal((await search({ dir, term: 'Mine' })).length, 1);
    const before = fs.readFileSync(foreign, 'utf8');
    await build({ dir });
    assert.equal(fs.readFileSync(foreign, 'utf8'), before, 'an ignored file is never rewritten');
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('reindex() prunes a doc row (and its edges) once the file is deleted', async () => {
  const dir = scratchDir();
  try {
    const story = writeDoc(dir, 'docs/Stories/[DEV-1] Example/impl/0-intent.md', '# Intent\n');
    const hld = writeDoc(dir, 'docs/Target Architecture (HLD)/v1/Containers/Web.md', '# Web\n');
    await build({ dir });
    await index({ dir, doc: story });
    await index({ dir, doc: hld });
    await index({ dir, doc: story, edge: 'story-to-hld', to: hld });
    const edgesBefore = (await query({ dir, relatedTo: story })).length;
    assert.ok(edgesBefore >= 1, 'sanity: the edge was written before deletion');

    fs.rmSync(story);
    const result = await reindex({ dir });
    assert.equal(result.pruned.length, 1);

    const afterQuery = await query({
      dir,
      relatedTo: 'docs/Stories/[DEV-1] Example/impl/0-intent.md',
    });
    assert.deepEqual(afterQuery, [], 'pruned doc should have no remaining edges');
    const hits = await search({ dir, term: 'Intent' });
    assert.ok(
      !hits.some((h) => h.path.endsWith('0-intent.md')),
      'pruned doc should not be searchable'
    );
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test("reindex() updates a moved doc's path in place, preserving its id and edges", async () => {
  const dir = scratchDir();
  try {
    const story = writeDoc(dir, 'docs/Stories/[DEV-1] Example/impl/0-intent.md', '# Intent\n');
    const hld = writeDoc(dir, 'docs/Target Architecture (HLD)/v1/Containers/Web.md', '# Web\n');
    await build({ dir });
    const { id: storyId } = await index({ dir, doc: story });
    await index({ dir, doc: hld });
    await index({ dir, doc: story, edge: 'story-to-hld', to: hld });
    const edgesBefore = await query({ dir, relatedTo: story });
    assert.ok(edgesBefore.length >= 1, 'sanity: the edge was written before the move');

    const oldPath = story;
    const newPath = path.join(dir, 'docs/Stories/archive/[DEV-1] Example/impl/0-intent.md');
    fs.mkdirSync(path.dirname(newPath), { recursive: true });
    fs.renameSync(oldPath, newPath);

    const result = await reindex({ dir });
    assert.deepEqual(result.pruned, [], 'a move is not a deletion; nothing should be pruned');

    const hits = await search({ dir, term: 'Intent' });
    const moved = hits.find((h) => h.id === storyId);
    assert.ok(moved, 'moved doc should still be findable by its original id');
    assert.equal(
      moved.path,
      'docs/Stories/archive/[DEV-1] Example/impl/0-intent.md',
      'row should reflect the new path'
    );

    const edgesAfter = await query({ dir, relatedTo: newPath });
    assert.equal(
      edgesAfter.length,
      edgesBefore.length,
      'edges referencing the id survive the move'
    );
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('sql.js opens and queries the exact .sqlite file node:sqlite wrote, with no conversion step', async () => {
  const dir = scratchDir();
  try {
    await build({ dir });
    const dbPath = path.join(dir, DB_FILE);
    const bytes = fs.readFileSync(dbPath);
    const initSqlJs = (await import('sql.js')).default;
    const SQL = await initSqlJs();
    const sqlDb = new SQL.Database(bytes);
    const result = sqlDb.exec("SELECT name FROM sqlite_master WHERE type='table'");
    const tableNames = result[0]?.values.map((row) => row[0]) ?? [];
    assert.ok(tableNames.includes('docs'));
    assert.ok(tableNames.includes('edges'));
    sqlDb.close();
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('build() emits a tier-rooted Mermaid mindmap grouping docs by tier branch', async () => {
  const dir = scratchDir();
  try {
    graduationFixture(dir);
    await build({ dir });
    const artifact = fs.readFileSync(path.join(dir, 'docs/.og/graph.mmd'), 'utf8');
    assert.match(artifact, /^mindmap/);
    assert.match(artifact, /root\(\("Operational Graph"\)\)/);
    assert.match(artifact, /^\s{4}HLD$/m, 'HLD tier branch should be its own mindmap line');
    assert.match(artifact, /^\s{4}Story$/m, 'Story tier branch should be its own mindmap line');
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('the mindmap never emits classDef or inline :::class — mindmap has no classDef grammar and a bare classDef line parses as a bogus rootless node', async () => {
  const dir = scratchDir();
  try {
    graduationFixture(dir);
    await build({ dir });
    const artifact = fs.readFileSync(path.join(dir, 'docs/.og/graph.mmd'), 'utf8');
    assert.doesNotMatch(artifact, /classDef/);
    assert.doesNotMatch(
      artifact,
      /:::[A-Za-z]/,
      'flowchart-style inline :::class is invalid mindmap syntax'
    );
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('the mindmap quotes node text so an embedded quote cannot break the diagram', async () => {
  const dir = scratchDir();
  try {
    writeDoc(dir, 'docs/Quoted.md', '# A "quoted" title\n');
    await build({ dir });
    const artifact = fs.readFileSync(path.join(dir, 'docs/.og/graph.mmd'), 'utf8');
    assert.doesNotMatch(
      artifact,
      /A "quoted" title/,
      'an unescaped quote would split the node text'
    );
    assert.match(artifact, /#quot;quoted#quot;/);
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('frontmatter purpose:/keywords: map to docs.purpose/docs.keywords, surfaced by search()', async () => {
  const dir = scratchDir();
  try {
    const doc = writeDoc(
      dir,
      'docs/Described.md',
      '---\npurpose: a doc about narwhals\nkeywords: [marine, tusked]\n---\n\n# Described\n'
    );
    await build({ dir });
    await index({ dir, doc });
    const hits = await search({ dir, term: 'narwhals' });
    assert.ok(hits.some((h) => h.path.endsWith('Described.md')));
    assert.ok((await search({ dir, term: 'tusked' })).length >= 1);
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('list({missing}) finds docs lacking purpose/keywords — a pure query, never writes', async () => {
  const dir = scratchDir();
  try {
    const bare = writeDoc(dir, 'docs/Bare.md', '# Bare\n');
    const described = writeDoc(
      dir,
      'docs/Described.md',
      '---\npurpose: has one\nkeywords: [a]\n---\n\n# Described\n'
    );
    await build({ dir });
    await index({ dir, doc: bare });
    await index({ dir, doc: described });

    const missingBoth = await list({ dir, missing: 'purpose,keywords' });
    assert.ok(missingBoth.some((row) => row.path.endsWith('Bare.md')));
    assert.ok(!missingBoth.some((row) => row.path.endsWith('Described.md')));

    const before = fs.readFileSync(bare, 'utf8');
    await list({ dir, missing: 'purpose' });
    assert.equal(fs.readFileSync(bare, 'utf8'), before, 'list() must never write to a doc');
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('list() rejects an unknown --missing field', async () => {
  const dir = scratchDir();
  try {
    await build({ dir });
    await assert.rejects(() => list({ dir, missing: 'description' }));
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('list() with no --missing returns every indexed doc', async () => {
  const dir = scratchDir();
  try {
    const a = writeDoc(dir, 'docs/A.md', '# A\n');
    const b = writeDoc(dir, 'docs/B.md', '---\npurpose: has one\nkeywords: [x]\n---\n\n# B\n');
    await build({ dir });
    await index({ dir, doc: a });
    await index({ dir, doc: b });
    const all = await list({ dir });
    assert.equal(all.length, 2);
    assert.ok(all.some((row) => row.path.endsWith('A.md')));
    assert.ok(all.some((row) => row.path.endsWith('B.md')));
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

test('search() finds a doc by term', async () => {
  const dir = scratchDir();
  try {
    writeDoc(dir, 'docs/Findable.md', '# Findable\n\nUnique keyword: xylophone.\n');
    await build({ dir });
    await index({ dir, doc: path.join(dir, 'docs/Findable.md') });
    const hits = await search({ dir, term: 'xylophone' });
    assert.ok(hits.some((h) => h.path.endsWith('Findable.md')));
  } finally {
    fs.rmSync(dir, { recursive: true, force: true });
  }
});

for (const [name, args] of [
  ['build', ['build', '--dir', '.']],
  ['index', ['index', '--dir', '.', '--doc', 'docs/x.md']],
  ['reindex', ['reindex', '--dir', '.']],
  ['query', ['query', '--dir', '.', '--related-to', 'x']],
  ['search', ['search', '--dir', '.', '--term', 'x']],
  ['list', ['list', '--dir', '.', '--missing', 'purpose,keywords']],
  [
    'unedge',
    ['unedge', '--dir', '.', '--doc', 'docs/x.md', '--edge', 'references', '--to', 'docs/y.md'],
  ],
]) {
  test(`CLI subcommand "${name}" parses its flags and dispatches`, () => {
    const dir = scratchDir();
    try {
      const result = spawnSync('node', [cliPath, ...args], { cwd: dir, encoding: 'utf8' });
      // A real run may fail on fixture content, but must not fail on argument parsing.
      assert.doesNotMatch(result.stderr ?? '', /unknown option|ERR_PARSE_ARGS/i);
    } finally {
      fs.rmSync(dir, { recursive: true, force: true });
    }
  });
}

test('CLI entry prints usage for --help or an unknown subcommand', () => {
  const help = spawnSync('node', [cliPath, '--help'], { encoding: 'utf8' });
  assert.match(help.stdout + help.stderr, /usage/i);
  const unknown = spawnSync('node', [cliPath, 'not-a-command'], { encoding: 'utf8' });
  assert.notEqual(unknown.status, 0);
});
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall