@rryando/arcs 3.8.0 → 3.9.0

package/scripts/lint-bundle.mjs

@@ -21,32 +21,6 @@ const bundleRoot = process.env.BUNDLE_LINT_BUNDLE_ROOT
   ? resolve(repoRoot, process.env.BUNDLE_LINT_BUNDLE_ROOT)
   : defaultBundleRoot;
 
-// Preserved files that are repo-authored, not sourced from manifest.
-const preservedFiles = new Set([
-  "manifest.json",
-  "bundle-runtime.json",
-  ".opencode/plugins/arcs.js",
-  "skills/loop/SKILL.md",
-  "skills/caveman-commit/SKILL.md",
-  "skills/init-project/SKILL.md",
-  "skills/the-ladder/SKILL.md",
-  // Sub-agent prompt files (repo-authored, referenced from manifest.json
-  // requiredMerges, not from bundle-runtime.json's `agents` array).
-  "prompts/software-engineer.txt",
-  "prompts/tech-architect.txt",
-  "prompts/oncall-ops.txt",
-  "prompts/arcs-docs.txt",
-  "prompts/code-reviewer.txt",
-  "prompts/docs-researcher.txt",
-  "prompts/devil-advocate.txt",
-  "prompts/graph-explorer.txt",
-  // Orchestrator prompt files — generated from src/cli/arcs-orchestrate*.ts
-  // by build-opencode-bundle.mjs. Committed mirrors so the bundle is
-  // self-describing alongside the static sub-agent prompts.
-  "prompts/arcs-orchestrate.txt",
-  "prompts/arcs-orchestrate-caveman.txt",
-]);
-
 /** @type {Array<{severity: 'error'|'warning', kind: string, message: string, file?: string, repair?: string}>} */const issues = [];
 
 function addIssue(severity, kind, message, file, repair) {
@@ -74,6 +48,12 @@ if (!existsSync(manifestPath)) {
 }
 
 const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+const sourceManifestPath = resolve(bundleRoot, "manifest.json");
+if (!existsSync(sourceManifestPath)) {
+  addIssue("error", "source-manifest-missing", `manifest.json not found at ${sourceManifestPath}`);
+  output();
+}
+const sourceManifest = JSON.parse(readFileSync(sourceManifestPath, "utf-8"));
 
 // --- Check 1: Every manifest-declared bundled file exists ---
 const declaredFiles = new Set();
@@ -108,6 +88,30 @@ for (const pluginFile of manifest.plugin ?? []) {
   }
 }
 
+for (const agent of sourceManifest.agents ?? []) {
+  declaredFiles.add(agent.source);
+  if (!existsSync(resolve(bundleRoot, agent.source))) {
+    addIssue(
+      "error",
+      "missing-declared-file",
+      `Source manifest declares ${agent.source} but file is missing`,
+      agent.source,
+    );
+  }
+}
+
+const preservedFiles = new Set(manifest.preservedFiles ?? []);
+for (const preservedFile of preservedFiles) {
+  if (!existsSync(resolve(bundleRoot, preservedFile))) {
+    addIssue(
+      "error",
+      "missing-preserved-file",
+      `Runtime manifest preserves ${preservedFile} but file is missing`,
+      preservedFile,
+    );
+  }
+}
+
 // --- Check 2: No extra undeclared files in bundle ---
 const allBundleFiles = listAllFiles(bundleRoot);
 const allowedFiles = new Set([...declaredFiles, ...preservedFiles]);
@@ -115,7 +119,7 @@ const allowedFiles = new Set([...declaredFiles, ...preservedFiles]);
 for (const file of allBundleFiles) {
   if (!allowedFiles.has(file)) {
     addIssue(
-      "warning",
+      "error",
       "undeclared-file",
       `File ${file} exists in bundle but is not declared in manifest`,
       file,

package/skills/explore-dag.md

@@ -17,9 +17,9 @@ flowchart TD
 
     A[arcs project list → big picture] --> B{Question answered by DAG?}
     B -->|yes| C[Report from DAG data]
-    B -->|no| D[Dispatch explore sub-agent]:::sub
+    B -->|no| D[Dispatch graph-explorer sub-agent]:::sub
     D --> E{Durable discovery?}
-    E -->|yes| F[arcs knowledge create]
+    E -->|yes| F[arcs knowledge upsert]
     E -->|no| C
     F --> C
 ```
@@ -54,4 +54,4 @@ Discovery: `arcs --commands --json`
 - Start with `arcs project list` for the big picture
 - Use `knowledge` docs to quickly understand unfamiliar codebases
 - Check `status` to know if a dependency is still actively maintained
-- Persist durable discoveries via `arcs knowledge create`
+- Persist durable discoveries via `arcs knowledge upsert`

package/skills/orchestrate.md

@@ -84,7 +84,7 @@ Discovery: `arcs --commands --json`
 - `arcs loop cancel <slug> --json` — cancel active loop
 - `arcs loop status <slug> --json` — inspect loop state
 
-Pair with `loop` skill for iteration discipline.
+Use these `arcs loop` session commands only when iterative execution is explicitly needed; otherwise route work through the selected execution skill.
 
 ## Verification Contract
 

package/templates/knowledge.md.tmpl

@@ -1,11 +1,11 @@
 # Knowledge — {{name}}
 
 > This is a summary landing page. Detailed knowledge lives in structured entries under `knowledge/`.
-> Use `list_project_knowledge_entries` to browse, or `get_project_knowledge_entry` to read a specific entry.
+> Use `arcs knowledge list <slug>` to browse, `arcs knowledge search <slug> "<keywords>"` to find entries, and `arcs knowledge get <slug> <id> --body` to read one.
 
 ## Structured Entries
 
-_No entries yet. Run the init or sync prompt to analyze the codebase and populate entries._
+_No entries yet. Run `arcs init` for a new project or `arcs sync` to refresh an existing project._
 
 ## Quick Reference
 

package/dist/utils/graphify-knowledge.d.ts

@@ -1,22 +0,0 @@
-import type { KnowledgeProposal } from "./graphify.js";
-/**
- * Convert graphify ingestion output into a `proposals/graphify.json` payload
- * and persist it through `proposal-store.writeProposals()`.
- *
- * Replaces the legacy direct-write path that used to populate
- * `knowledge/index.json` and `knowledge/<id>.md` at ingest time. Graphify
- * proposals now sit in the proposals gate until a skill-aware host enriches
- * them into durable knowledge entries.
- *
- * Merge semantics: if a proposals file already exists, proposals from the
- * existing file with ids NOT present in the new extraction are preserved.
- * This protects backfilled proposals (with empty structuralFacts) and any
- * other pending entries from being clobbered when graphify re-runs. The new
- * extraction wins on collisions — a fresh extraction produces fresher facts.
- */
-export declare function writeProposalsFile(slug: string, proposals: KnowledgeProposal[], graphJsonContent: string): Promise<{
-    written: number;
-    fingerprint: string;
-    preserved: number;
-}>;
-//# sourceMappingURL=graphify-knowledge.d.ts.map

package/dist/utils/graphify-knowledge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"graphify-knowledge.d.ts","sourceRoot":"","sources":["../../src/utils/graphify-knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAUvD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,iBAAiB,EAAE,EAC9B,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAmCtE"}

package/dist/utils/graphify-knowledge.js

@@ -1,47 +0,0 @@
-import { annotateDedupCandidates, computeGraphFingerprint, readProposals, writeProposals, } from "./proposal-store.js";
-/**
- * Convert graphify ingestion output into a `proposals/graphify.json` payload
- * and persist it through `proposal-store.writeProposals()`.
- *
- * Replaces the legacy direct-write path that used to populate
- * `knowledge/index.json` and `knowledge/<id>.md` at ingest time. Graphify
- * proposals now sit in the proposals gate until a skill-aware host enriches
- * them into durable knowledge entries.
- *
- * Merge semantics: if a proposals file already exists, proposals from the
- * existing file with ids NOT present in the new extraction are preserved.
- * This protects backfilled proposals (with empty structuralFacts) and any
- * other pending entries from being clobbered when graphify re-runs. The new
- * extraction wins on collisions — a fresh extraction produces fresher facts.
- */
-export async function writeProposalsFile(slug, proposals, graphJsonContent) {
-    // Map ingestion shape → storage shape. The storage `Proposal` adds an
-    // initially-empty `suggestedDedupCandidates`; `annotateDedupCandidates`
-    // populates it from the existing knowledge index.
-    const draft = proposals.map((p) => ({
-        id: p.id,
-        kind: p.kind,
-        label: p.label,
-        structuralFacts: p.structuralFacts,
-        sourceFiles: p.sourceFiles,
-        suggestedDedupCandidates: [],
-    }));
-    const annotated = await annotateDedupCandidates(slug, draft);
-    // Preserve existing proposals not present in the new extraction. This
-    // protects the lossy backfill payload (structuralFacts: {}) and any other
-    // pending agent-enrichment work from being silently dropped on the next
-    // graphify-sync. New extraction wins on id collisions.
-    const existing = await readProposals(slug);
-    const newIds = new Set(annotated.map((p) => p.id));
-    const preserved = existing ? existing.proposals.filter((p) => !newIds.has(p.id)) : [];
-    const fingerprint = computeGraphFingerprint(graphJsonContent);
-    const payload = {
-        version: 1,
-        generatedAt: new Date().toISOString(),
-        graphFingerprint: fingerprint,
-        proposals: [...annotated, ...preserved],
-    };
-    await writeProposals(slug, payload);
-    return { written: proposals.length, fingerprint, preserved: preserved.length };
-}
-//# sourceMappingURL=graphify-knowledge.js.map

package/dist/utils/graphify-knowledge.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"graphify-knowledge.js","sourceRoot":"","sources":["../../src/utils/graphify-knowledge.ts"],"names":[],"mappings":"AACA,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EAGvB,aAAa,EACb,cAAc,GACf,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAY,EACZ,SAA8B,EAC9B,gBAAwB;IAExB,sEAAsE;IACtE,wEAAwE;IACxE,kDAAkD;IAClD,MAAM,KAAK,GAAe,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9C,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,eAAe,EAAE,CAAC,CAAC,eAAqD;QACxE,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,wBAAwB,EAAE,EAAE;KAC7B,CAAC,CAAC,CAAC;IAEJ,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAE7D,sEAAsE;IACtE,0EAA0E;IAC1E,wEAAwE;IACxE,uDAAuD;IACvD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEtF,MAAM,WAAW,GAAG,uBAAuB,CAAC,gBAAgB,CAAC,CAAC;IAE9D,MAAM,OAAO,GAAkB;QAC7B,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,gBAAgB,EAAE,WAAW;QAC7B,SAAS,EAAE,CAAC,GAAG,SAAS,EAAE,GAAG,SAAS,CAAC;KACxC,CAAC;IAEF,MAAM,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAEpC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;AACjF,CAAC"}

package/dist/utils/graphify.d.ts

@@ -1,104 +0,0 @@
-export interface GraphifyInfo {
-    available: boolean;
-    version?: string;
-    path?: string;
-}
-export declare function detectGraphify(): GraphifyInfo;
-export interface ExtractionResult {
-    success: true;
-    graphJsonPath: string;
-}
-export interface ExtractionError {
-    success: false;
-    error: string;
-    code?: string;
-}
-export type ExtractionOutcome = ExtractionResult | ExtractionError;
-/**
- * A graphify-derived knowledge proposal.
- *
- * Carries STRUCTURAL FACTS only — not prose. The calling agent (which has LLM
- * tokens) is responsible for producing the final `title`/`summary`/`keywords`
- * during the proposal-promote step. See plan
- * `2026-06-02-graphify-proposal-gate-implementation-plan` §Proposal Shape.
- *
- * `suggestedDedupCandidates` is intentionally NOT on this type — that's
- * computed by the proposal-store layer when proposals are written to disk,
- * not at ingest time.
- */
-export interface KnowledgeProposal {
-    /** Stable id, e.g. "graphify-cluster-src-utils". */
-    id: string;
-    kind: "architecture" | "module" | "gotcha" | "pattern";
-    /** Human-friendly label. Agents will write the final title. */
-    label: string;
-    structuralFacts: ProposalStructuralFacts;
-    sourceFiles: Array<{
-        path: string;
-        anchor?: string;
-    }>;
-}
-export interface ProposalStructuralFacts {
-    memberCount?: number;
-    fileCount?: number;
-    /** e.g. { code: 260, document: 0 } */
-    fileTypeBreakdown?: Record<string, number>;
-    topHubs?: Array<{
-        label: string;
-        file: string;
-        in: number;
-        out: number;
-    }>;
-    topFilesByEntityCount?: Array<{
-        file: string;
-        count: number;
-    }>;
-    incomingFromOtherClusters?: number;
-    outgoingToOtherClusters?: number;
-    nodeFile?: string;
-    nodeIn?: number;
-    nodeOut?: number;
-    topCallers?: Array<{
-        label: string;
-        file: string;
-    }>;
-    topCallees?: Array<{
-        label: string;
-        file: string;
-    }>;
-    couplingA?: {
-        label: string;
-        file: string;
-        degree: number;
-    };
-    couplingB?: {
-        label: string;
-        file: string;
-        degree: number;
-    };
-    /** Edge relation types (e.g. ["imports_from", "calls"]). */
-    relations?: string[];
-}
-export interface IngestionResult {
-    proposals: KnowledgeProposal[];
-    stats: {
-        godNodes: number;
-        communities: number;
-        crossModuleCouplings: number;
-        totalProposals: number;
-    };
-}
-export declare function ingestGraph(graphJsonPath: string, _slug: string): IngestionResult;
-export interface QueryResult {
-    success: true;
-    answer: string;
-}
-export interface QueryError {
-    success: false;
-    error: string;
-}
-export type QueryOutcome = QueryResult | QueryError;
-export declare function queryGraph(question: string, workspacePath: string): QueryOutcome;
-export declare function pathBetween(entityA: string, entityB: string, workspacePath: string): QueryOutcome;
-export declare function runExtraction(workspacePath: string): ExtractionOutcome;
-//# sourceMappingURL=graphify.d.ts.map

package/dist/utils/graphify.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"graphify.d.ts","sourceRoot":"","sources":["../../src/utils/graphify.ts"],"names":[],"mappings":"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"}