@stevenvincentone/intidev-agentloops 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## 0.1.0
+
+First public release.
+
+### Core
+- Durable ticket ledger with kinds, statuses, severities, confidences, and notes.
+- Source-aware **queue aliases** (`ISSUE-` / `USER-` / `DEV-`) derived from kind and
+  source, over a single canonical `ISSUE-NNNNNN` id (config-driven `queues`).
+- Family-based **Pattern** grouping (auto-activates at ≥2 tickets).
+- Workflow transitions: begin, resolve, reopen, **defer**.
+- **Source-convergence audit**, **guard-gap report**, **resolution knowledge** search +
+  gaps, and **prior-art** related-ticket lookup (config-tunable scoring).
+- Copyable agent **handoff** prompts.
+- Optional **redaction** hook (`TicketRedactor`) — config patterns or injected redactor.
+
+### Storage
+- Pluggable `StateBackend`: filesystem JSON (default), in-memory, and **Postgres**
+  (public relational `ticket_*` schema; `pg` is an optional peer dependency).
+- CLI and MCP run on Postgres automatically via `DATABASE_URL`.
+
+### Interfaces
+- `agentloop` **CLI** (init, create, list, show, patterns, begin, resolve, reopen,
+  defer, note, guard, handoff, summary, convergence, guard-gaps, knowledge,
+  knowledge-gaps, related, dashboard, serve, config, mcp).
+- **MCP server** (`agentloop mcp`): 9 read-only tools, plus 5 write tools behind `--write`.
+- Zero-dependency **dashboard** (`agentloop dashboard` / `agentloop serve`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steven Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# IntiDev AgentLoops
+
+### Feedback Loops for Agentic Workflows
+
+IntiDev AgentLoops is an open-source toolkit for tracking issues, features, and user feedback through an agent-friendly resolution loop. It is intentionally lightweight and project-agnostic, while remaining opinionated about reproducibility, resolution hygiene, and machine-readable handoff artifacts.
+
+This repo is the first extractable iteration from our internal Tickets implementation, and is aimed at:
+
+- developers building AI coding workflows,
+- teams that need one loop for bugfixes, features, and support feedback,
+- maintainers who want reusable resolution knowledge and structured evidence.
+
+## Why this project exists
+
+Most bug trackers treat support, defects, and features as separate workflows.
+IntiDev AgentLoops links them into one consistent lifecycle so humans and agents use the same ticket surface and knowledge.
+
+## Quick install
+
+```bash
+npm install -g @stevenvincentone/intidev-agentloops
+```
+
+Then run:
+
+```bash
+agentloop init
+agentloop create --title "Rendering regression in list pages" --summary "List pages lose anchors after parser update" --family "reader_rendering" --kind bug --source manual_admin
+agentloop list
+agentloop resolve ISSUE-000001 --summary "Added deterministic fallback for anchor selection"
+```
+
+## Try the convergence demo
+
+Run a self-contained demo that seeds three independent intake loops — a smoke
+test, a user report, and an agent proposal — all pointing at the same
+`export_pipeline` family, and watch them converge into a single Pattern:
+
+```bash
+npm run demo
+```
+
+Expected output:
+
+```text
+AgentLoops source-convergence demo
+==================================
+
+Three intake loops, one underlying problem:
+
+  ISSUE-000001  bug            source=smoke        [export_pipeline]
+    Export smoke test times out on 500-page report
+  USER-000002   user_feedback  source=user_report  [export_pipeline]
+    Export fails for long reports
+  DEV-000003    feature        source=agent        [export_pipeline]
+    Stream the export pipeline instead of buffering
+
+Converged into:
+  PATTERN-000001 ACTIVE (3 tickets) — Recurring export_pipeline issues
+
+Summary: 3 tickets, 1 active pattern(s).
+```
+
+The demo writes to a throwaway temp directory and leaves your repo untouched.
+The same scenario is asserted in `test/demo.test.ts` against a committed golden
+state fixture; run it with `npm test`.
+
+## Core concepts
+
+- Ticket: one concrete work item (bug, feature, user feedback, incident, etc.)
+- Pattern: a recurring cluster, often by family/domain
+- Source: origin (`user_report`, `smoke`, `ci`, `agent`, `ingestion`, etc.)
+- Alias: human-facing IDs such as `ISSUE-000001`, `DEV-000001`, `USER-000001`
+- Handoff: copyable context block for an agent to continue execution
+
+## Commands
+
+- `agentloop init` initialize `.agentloops` state and local config
+- `agentloop create` add a ticket
+- `agentloop list` view active and resolved work
+- `agentloop begin <id>` mark triaged ticket as in-progress
+- `agentloop resolve <id> --summary ...` mark resolved with evidence
+- `agentloop reopen <id>` reopen and record a recurrence reason
+- `agentloop defer <id> [--summary ...]` defer a ticket with an optional reason
+- `agentloop note <id> --type ... --body ...` add context notes
+- `agentloop guard <id> --guard-status ...` record guard decision
+- `agentloop handoff <id>` print a copyable agent handoff prompt
+- `agentloop patterns` list pattern groups
+- `agentloop summary` print quick health metrics
+- `agentloop convergence` report patterns whose tickets span multiple sources
+- `agentloop guard-gaps` report resolved tickets missing a regression guard
+- `agentloop knowledge` search how prior resolved tickets were fixed
+- `agentloop knowledge-gaps` report resolved tickets lacking reusable knowledge
+- `agentloop related <id>` find prior-art tickets related to one ticket
+- `agentloop dashboard` write a standalone HTML dashboard
+- `agentloop serve` serve the dashboard over HTTP
+- `agentloop config` print resolved configuration
+- `agentloop mcp` run the read-only MCP server over stdio
+
+All commands support `--json` for machine-readable output where relevant.
+
+## MCP server (agent integration)
+
+AgentLoops ships an [MCP](https://modelcontextprotocol.io) server so coding
+agents (Claude Code, Codex, and other MCP clients) can use the ledger directly.
+Writes are **opt-in**: the server is read-only unless you pass `--write`.
+
+```bash
+agentloop mcp            # read-only; speaks JSON-RPC over stdio, status to stderr
+agentloop mcp --write    # also expose the guarded write tools
+```
+
+Read-only tools (annotated `readOnlyHint`):
+
+| Tool | Purpose |
+| --- | --- |
+| `agentloop_summary` | loop health metrics (ticket and pattern counts) |
+| `agentloop_list` | list tickets, optional `status` / `kind` filters |
+| `agentloop_show` | one ticket (by `ISSUE-`/alias) or a `PATTERN-` id |
+| `agentloop_handoff` | copyable agent handoff prompt for a ticket |
+| `agentloop_convergence` | patterns whose tickets span multiple sources |
+| `agentloop_guard_gaps` | resolved tickets missing a regression guard |
+| `agentloop_search_knowledge` | search how prior resolved tickets were fixed |
+| `agentloop_knowledge_gaps` | resolved tickets lacking reusable knowledge |
+| `agentloop_related` | prior-art: tickets related to a given ticket |
+
+Write tools (only registered with `--write`):
+
+| Tool | Purpose |
+| --- | --- |
+| `agentloop_create` | create a ticket (`summary` required; `source` defaults to `agent`) |
+| `agentloop_note` | append a non-resolution note |
+| `agentloop_workflow` | transition a ticket (`active` / `reopened` / `deferred`) |
+| `agentloop_resolve` | resolve with a summary, optional verification + guard |
+| `agentloop_guard` | record a regression-guard decision |
+
+Each result is a JSON envelope with `schemaVersion` and `generatedAt`. The server
+reads/writes state from the `.agentloops/state.json` in its working directory, so
+run it from your project root (or where you ran `agentloop init`).
+
+Register it with an MCP client, for example Claude Code:
+
+```bash
+claude mcp add agentloop -- agentloop mcp
+```
+
+or directly in a client config:
+
+```json
+{
+  "mcpServers": {
+    "agentloop": { "command": "agentloop", "args": ["mcp"] }
+  }
+}
+```
+
+## Dashboard
+
+A zero-dependency reference UI renders the ledger as a single self-contained HTML
+page — queues (Issues / User / Development), patterns, source convergence, and
+guard gaps — with no build step or frontend framework.
+
+```bash
+agentloop dashboard --out dashboard.html   # write a static snapshot, open in a browser
+agentloop serve --port 4319                # live dashboard + read-only JSON at /api/*
+```
+
+Both work over either storage backend. All ticket content is HTML-escaped. For a
+richer or embeddable UI, the `renderDashboard(data)` and `createDashboardServer(store)`
+exports can be built upon.
+
+## Data model
+
+State is stored in your working directory at `.agentloops/state.json` by default.
+The store persists through a pluggable `StateBackend`, so the same ledger can run
+over the filesystem, an in-memory store, or **Postgres** (a relational `ticket_*`
+schema) — see [docs/postgres.md](docs/postgres.md).
+
+For local project settings, copy and customize:
+
+```bash
+cp agentloop.config.json.example agentloop.config.json
+```
+
+The config controls:
+
+- project naming
+- ticket kinds and aliases (`ISSUE`, `DEV`, `USER`, etc.)
+- default family for auto-grouping
+- configured sources
+
+## Privacy and redaction
+
+By default AgentLoops stores ticket text as-is and makes no model or network calls.
+Host apps own redaction. Two ways to scrub sensitive content (PII, secrets) before
+it is written to `.agentloops/state.json`:
+
+- **Config-driven** — add regex rules under `redaction.patterns` in
+  `agentloop.config.json`; they apply to titles, summaries, notes, resolutions,
+  and guard summaries on every write (CLI and MCP included):
+
+  ```json
+  { "redaction": { "patterns": [{ "pattern": "[\\w.]+@[\\w.]+\\.[a-z]+", "replacement": "[email]" }] } }
+  ```
+
+- **Code-driven** — library users can inject a `TicketRedactor`:
+  `new AgentLoopStore(cwd, config, { redactor })`.
+
+## Contributing
+
+Open issues and PRs are welcome.
+
+When adding new sources or fields, include:
+
+1. a config-backed approach, not hardcoded assumptions,
+2. a short schema note in docs,
+3. a concise example command and expected output.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/agentloop.config.json.example

@@ -0,0 +1,31 @@
+{
+  "projectName": "IntiDev AgentLoops",
+  "description": "Feedback loops for agentic workflows",
+  "defaultKind": "bug",
+  "ticketKinds": [
+    { "kind": "bug", "defaultSeverity": "high", "requiredFields": ["summary"] },
+    { "kind": "feature", "defaultSeverity": "medium", "requiredFields": ["summary"] },
+    { "kind": "user_feedback", "defaultSeverity": "high", "requiredFields": ["summary"] },
+    { "kind": "investigation", "defaultSeverity": "medium", "requiredFields": ["summary"] },
+    { "kind": "incident", "defaultSeverity": "critical", "requiredFields": ["summary"] },
+    { "kind": "tech_debt", "defaultSeverity": "medium", "requiredFields": ["summary"] },
+    { "kind": "task", "defaultSeverity": "medium", "requiredFields": ["summary"] }
+  ],
+  "queues": [
+    { "prefix": "USER", "kinds": ["user_feedback"], "sources": ["user_report"] },
+    { "prefix": "DEV", "kinds": ["feature", "task", "investigation", "tech_debt"] },
+    { "prefix": "ISSUE", "kinds": ["bug", "incident"], "default": true }
+  ],
+  "sources": [
+    "user_report",
+    "manual_admin",
+    "smoke",
+    "agent",
+    "ci",
+    "ingestion"
+  ],
+  "patterns": {
+    "autoCreateByFamily": true,
+    "defaultFamily": "general"
+  }
+}

package/dist/aliases.d.ts

@@ -0,0 +1,25 @@
+import { ProjectConfig } from "./types";
+/** Zero-pad a ticket sequence number to the canonical width. */
+export declare function padSeq(seq: number): string;
+/** The canonical key for a ticket is always `ISSUE-NNNNNN`, regardless of queue. */
+export declare function canonicalKey(seq: number): string;
+/**
+ * Resolve the single queue-alias prefix for a ticket from its kind and source.
+ *
+ * Ported from Inti's `TicketAliases` (USER → DEV → ISSUE precedence): a queue
+ * matches when the ticket's `source` is in `queue.sources` OR its `kind` is in
+ * `queue.kinds`. Queues are tried in config order, so the source override (e.g.
+ * `user_report` → USER) wins for any kind. Falls back to the `default` queue.
+ */
+export declare function resolveQueuePrefix(input: {
+    kind: string;
+    source?: string;
+}, config: ProjectConfig): string;
+/**
+ * Build the user-facing alias key(s) for a ticket. Currently a single queue
+ * alias; returned as an array to keep the `Ticket.aliases` shape stable.
+ */
+export declare function deriveAliases(input: {
+    kind: string;
+    source?: string;
+}, seq: number, config: ProjectConfig): string[];

package/dist/aliases.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.padSeq = padSeq;
+exports.canonicalKey = canonicalKey;
+exports.resolveQueuePrefix = resolveQueuePrefix;
+exports.deriveAliases = deriveAliases;
+const SEQ_PAD = 6;
+/** Zero-pad a ticket sequence number to the canonical width. */
+function padSeq(seq) {
+    return String(seq).padStart(SEQ_PAD, "0");
+}
+/** The canonical key for a ticket is always `ISSUE-NNNNNN`, regardless of queue. */
+function canonicalKey(seq) {
+    return `ISSUE-${padSeq(seq)}`;
+}
+/**
+ * Resolve the single queue-alias prefix for a ticket from its kind and source.
+ *
+ * Ported from Inti's `TicketAliases` (USER → DEV → ISSUE precedence): a queue
+ * matches when the ticket's `source` is in `queue.sources` OR its `kind` is in
+ * `queue.kinds`. Queues are tried in config order, so the source override (e.g.
+ * `user_report` → USER) wins for any kind. Falls back to the `default` queue.
+ */
+function resolveQueuePrefix(input, config) {
+    const source = input.source ?? "";
+    for (const queue of config.queues) {
+        if (queue.sources?.includes(source))
+            return queue.prefix;
+        if (queue.kinds?.includes(input.kind))
+            return queue.prefix;
+    }
+    const fallback = config.queues.find((queue) => queue.default);
+    return fallback?.prefix ?? "ISSUE";
+}
+/**
+ * Build the user-facing alias key(s) for a ticket. Currently a single queue
+ * alias; returned as an array to keep the `Ticket.aliases` shape stable.
+ */
+function deriveAliases(input, seq, config) {
+    return [`${resolveQueuePrefix(input, config)}-${padSeq(seq)}`];
+}
+//# sourceMappingURL=aliases.js.map

package/dist/backend.d.ts

@@ -0,0 +1,29 @@
+import { LoopState } from "./types";
+/**
+ * Persistence port for the ledger. `AgentLoopStore` holds the whole `LoopState`
+ * in memory and delegates loading/saving to a backend, so the same domain logic
+ * runs over the filesystem, an in-memory store, or Postgres.
+ */
+export interface StateBackend {
+    /** Return the persisted state, or null if nothing has been stored yet. */
+    load(): Promise<LoopState | null>;
+    /** Persist the full state snapshot. */
+    save(state: LoopState): Promise<void>;
+    /** Optional one-time setup (e.g. create schema). No-op for filesystem/memory. */
+    migrate?(): Promise<void>;
+}
+/** Default backend: JSON at `<cwd>/.agentloops/state.json`. */
+export declare class FilesystemStateBackend implements StateBackend {
+    private readonly dirPath;
+    private readonly statePath;
+    constructor(cwd: string, dir?: string, fileName?: string);
+    load(): Promise<LoopState | null>;
+    save(state: LoopState): Promise<void>;
+}
+/** Ephemeral backend, handy for tests and short-lived processes. */
+export declare class MemoryStateBackend implements StateBackend {
+    private state;
+    constructor(initial?: LoopState | null);
+    load(): Promise<LoopState | null>;
+    save(state: LoopState): Promise<void>;
+}

package/dist/backend.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStateBackend = exports.FilesystemStateBackend = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Default backend: JSON at `<cwd>/.agentloops/state.json`. */
+class FilesystemStateBackend {
+    dirPath;
+    statePath;
+    constructor(cwd, dir = ".agentloops", fileName = "state.json") {
+        this.dirPath = (0, node_path_1.join)(cwd, dir);
+        this.statePath = (0, node_path_1.join)(this.dirPath, fileName);
+    }
+    async load() {
+        if (!(0, node_fs_1.existsSync)(this.statePath))
+            return null;
+        const text = await node_fs_1.promises.readFile(this.statePath, "utf-8");
+        return JSON.parse(text);
+    }
+    async save(state) {
+        await node_fs_1.promises.mkdir(this.dirPath, { recursive: true });
+        await node_fs_1.promises.writeFile(this.statePath, JSON.stringify(state, null, 2), "utf-8");
+    }
+}
+exports.FilesystemStateBackend = FilesystemStateBackend;
+/** Ephemeral backend, handy for tests and short-lived processes. */
+class MemoryStateBackend {
+    state;
+    constructor(initial = null) {
+        this.state = initial ? structuredClone(initial) : null;
+    }
+    async load() {
+        return this.state ? structuredClone(this.state) : null;
+    }
+    async save(state) {
+        this.state = structuredClone(state);
+    }
+}
+exports.MemoryStateBackend = MemoryStateBackend;
+//# sourceMappingURL=backend.js.map

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};