@stevenvincentone/intidev-agentloops 0.1.0

package/docs/config.md

@@ -0,0 +1,88 @@
+# Configuration
+
+`agentloop.config.json` controls the project vocabulary.
+
+```json
+{
+  "projectName": "IntiDev AgentLoops",
+  "description": "Feedback loops for agentic workflows",
+  "defaultKind": "bug",
+  "ticketKinds": [
+    { "kind": "bug", "defaultSeverity": "high", "requiredFields": ["summary"] },
+    { "kind": "feature", "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", "agent", "smoke", "ci", "ingestion"]
+}
+```
+
+### Ticket kinds
+
+Each kind can define:
+
+- `defaultSeverity`: used when `--severity` is omitted
+- `requiredFields`: enforcement when creating tickets
+
+### Queues and aliases
+
+Canonical ids are always stored as `ISSUE-000123`. Each ticket also gets one
+user-facing **queue alias** derived from its `kind` and `source`:
+
+- `queues` are evaluated in order; the first whose `sources` includes the
+  ticket's source, or whose `kinds` includes its kind, wins.
+- a `sources` match takes that queue's precedence, so a `user_report`-sourced
+  bug routes to `USER-000123` even though `bug` is otherwise an `ISSUE` kind.
+- the queue marked `"default": true` is the fallback when nothing matches.
+
+With the default config that yields:
+
+- `USER-000123` for product/support feedback (kind `user_feedback` or source `user_report`)
+- `DEV-000123` for development work (`feature`, `task`, `investigation`, `tech_debt`)
+- `ISSUE-000123` for defects (`bug`, `incident`) and anything unrouted
+
+The canonical `ISSUE-` key keeps downstream systems stable while the alias gives
+each operational queue a recognizable prefix. Aliases and canonical ids share the
+same number, and any of them resolves back to the same ticket on lookup.
+
+### Prior-art scoring (optional)
+
+`agentloop related <id>` (and the `agentloop_related` MCP tool) rank related
+tickets from deterministic signals: shared family, shared pattern, shared tags,
+same kind, and title/summary token overlap. Core ships fixed default weights; a
+project can override any of them, or raise the default match threshold:
+
+```json
+{
+  "priorArt": {
+    "weights": { "family": 3, "pattern": 3, "tag": 2, "kind": 1, "textOverlap": 4 },
+    "minScore": 1
+  }
+}
+```
+
+Omit `priorArt` entirely to use the core defaults.
+
+### Redaction (optional)
+
+By default ticket text is stored unchanged. Add regex rules under
+`redaction.patterns` to scrub sensitive content (PII, secrets) on every write —
+titles, summaries, notes, resolutions, and guard summaries, via both the CLI and
+the MCP write tools:
+
+```json
+{
+  "redaction": {
+    "patterns": [
+      { "name": "email", "pattern": "[\\w.]+@[\\w.]+\\.[a-z]+", "replacement": "[email]" }
+    ]
+  }
+}
+```
+
+Each rule takes a `pattern` (regex source), optional `flags` (default `g`), and
+optional `replacement` (default `[redacted]`). Library users can instead inject a
+`TicketRedactor` directly: `new AgentLoopStore(cwd, config, { redactor })`.

package/docs/mcp.md

@@ -0,0 +1,88 @@
+# MCP server
+
+AgentLoops exposes a [Model Context Protocol](https://modelcontextprotocol.io)
+server so coding agents can use the ticket ledger directly. Writes are **opt-in**:
+the server is read-only by default and only registers the write tools (create /
+note / workflow / resolve / guard) when started with `--write`.
+
+## Running
+
+```bash
+agentloop mcp            # read-only
+agentloop mcp --write    # also expose the write tools (alias: --allow-writes)
+```
+
+- Communicates over **stdio** using JSON-RPC. `stdout` carries only the protocol
+  stream; human-readable status (including the read-only/read-write mode) is
+  written to `stderr`.
+- Reads/writes `.agentloops/state.json` from the **current working directory**, so
+  start it from the project root where you ran `agentloop init`.
+- Implemented over the same `AgentLoopStore` as the CLI, so the CLI and MCP
+  surfaces always agree.
+
+## Read-only tools
+
+Always available; annotated `readOnlyHint: true`.
+
+| Tool | Input | Returns |
+| --- | --- | --- |
+| `agentloop_summary` | none | `{ schemaVersion, generatedAt, summary }` — ticket/pattern counts |
+| `agentloop_list` | `status?`, `kind?` | `{ ..., filters, count, tickets }` |
+| `agentloop_show` | `id` | `{ ..., kind: "ticket", ticket }` or `{ ..., kind: "pattern", pattern }` |
+| `agentloop_handoff` | `id` | `{ ..., ticketId, aliases, prompt }` |
+| `agentloop_convergence` | `family?`, `minSources?`, `includeAll?` | `{ ..., filters, summary, patterns }` — patterns whose tickets span ≥ `minSources` (default 2) distinct sources |
+| `agentloop_guard_gaps` | `family?`, `includeWaived?`, `allKinds?` | `{ ..., filters, summary, gaps }` — resolved tickets (ISSUE/USER queues by default) lacking an active regression guard |
+| `agentloop_search_knowledge` | `family?`, `kind?`, `source?`, `tag?`, `query?`, `limit?` | `{ ..., filters, summary, entries }` — how prior resolved tickets were fixed (searchable corpus) |
+| `agentloop_knowledge_gaps` | `family?`, `severity?`, `source?` | `{ ..., filters, summary, gaps }` — resolved tickets whose knowledge is incomplete (missing resolution or verification) |
+| `agentloop_related` | `id`, `minScore?`, `limit?` | `{ ..., ticket, weights, related }` — prior-art lookup ranking tickets by shared family/pattern/tags/kind and title overlap (weights tunable via `config.priorArt`) |
+
+## Write tools
+
+Only registered with `--write`. Each returns `{ schemaVersion, generatedAt,
+action, ticket }`, where `ticket` carries the canonical `id` and queue `aliases`.
+
+| Tool | Input | Notes |
+| --- | --- | --- |
+| `agentloop_create` | `summary` (required), `title?`, `family?`, `kind?`, `source?`, `severity?`, `confidence?`, `tags?`, `handoff?` | `kind`/`family` default from config; `source` defaults to `agent` |
+| `agentloop_note` | `id`, `body` (required), `type?`, `author?` | `type` defaults to `triage`, `author` to `agent` |
+| `agentloop_workflow` | `id`, `status` (`active` \| `reopened` \| `deferred`), `reason?` | resolve via `agentloop_resolve`, not here |
+| `agentloop_resolve` | `id`, `summary` (required), `verification?`, `guardStatus?`, `guardSummary?` | |
+| `agentloop_guard` | `id`, `guardStatus`, `guardSummary?` | |
+
+Notes:
+
+- `id` accepts the canonical `ISSUE-NNNNNN` id, any queue alias (`DEV-...`,
+  `USER-...`, etc.), or a `PATTERN-NNNNNN` id for `agentloop_show`.
+- `status` (for `agentloop_list`) accepts `triaged | active | resolved | reopened | deferred | all`.
+- `kind`, `severity`, `confidence`, `guardStatus`, and note `type` are validated
+  against the configured/known values; invalid inputs return a readable error.
+- Every envelope includes `schemaVersion` (currently `1`) and `generatedAt`.
+  Fields are added, not removed, within a schema version.
+- Unknown ids return a tool error (`isError: true`) with a readable message
+  rather than failing the protocol call.
+- Writes pass through the configured redactor before storage (no-op by default;
+  see `redaction.patterns` in [config](config.md) or inject a `TicketRedactor`).
+
+## Client configuration
+
+Claude Code:
+
+```bash
+claude mcp add agentloop -- agentloop mcp
+```
+
+Generic MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "agentloop": {
+      "command": "agentloop",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+If you have not installed the package globally, point the client at the built CLI
+instead, e.g. `"command": "node", "args": ["/path/to/dist/cli.js", "mcp"]`.

package/docs/postgres.md

@@ -0,0 +1,84 @@
+# Storage backends (filesystem & Postgres)
+
+`AgentLoopStore` holds the whole ledger in memory and delegates persistence to a
+`StateBackend`, so the same domain logic (tickets, patterns, audits, prior art)
+runs over different stores:
+
+| Backend | Use |
+| --- | --- |
+| `FilesystemStateBackend` (default) | JSON at `<cwd>/.agentloops/state.json` |
+| `MemoryStateBackend` | ephemeral; tests and short-lived processes |
+| `PostgresStateBackend` | a relational `ticket_*` schema in Postgres |
+
+```ts
+import { AgentLoopStore, MemoryStateBackend } from "@stevenvincentone/intidev-agentloops";
+
+const store = new AgentLoopStore(process.cwd(), config, { backend: new MemoryStateBackend() });
+```
+
+## Postgres
+
+`PostgresStateBackend` brings **no `pg` dependency** — you inject a client that
+matches `pg.Pool`/`pg.Client` (`{ query(text, params) => Promise<{ rows }> }`).
+
+```ts
+import { Pool } from "pg";
+import { AgentLoopStore, PostgresStateBackend } from "@stevenvincentone/intidev-agentloops";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const backend = new PostgresStateBackend(pool);
+await backend.migrate(); // optional; load()/save() also create the schema on first use
+
+const store = new AgentLoopStore("", config, { backend });
+```
+
+- Saves are **transactional** (whole-snapshot replace), so a failed write never
+  leaves a partially-updated ledger. A `pg.Pool` is used via a single dedicated
+  connection per operation.
+- Schema is created with `CREATE TABLE IF NOT EXISTS`, so `migrate()` is safe to
+  run repeatedly.
+
+## CLI and MCP on Postgres
+
+The `agentloop` CLI and `agentloop mcp` server run on Postgres automatically when
+a connection string is configured — no flags needed:
+
+```bash
+export DATABASE_URL=postgres://user:pass@host:5432/db
+agentloop init        # creates the ticket_* schema and an empty ledger
+agentloop create --kind bug --summary "..." --source smoke
+agentloop summary
+agentloop mcp         # MCP server backed by Postgres
+```
+
+- Connection string precedence: explicit > `DATABASE_URL` env > `config.storage.databaseUrl`.
+  Prefer the env var so secrets stay out of committed config.
+- `pg` is an **optional peer dependency** — install it in your project (`npm install pg`)
+  when you want the Postgres backend. Filesystem users need nothing extra; if a
+  Postgres URL is set but `pg` is missing, the CLI prints an actionable error.
+- One-shot commands open and **close** the pool so the process exits cleanly; the
+  MCP server holds the pool open until its stdin closes.
+
+### Public schema
+
+The canonical relational schema is exported as `TICKET_SCHEMA_SQL`:
+
+- `loop_meta` — single row of top-level ledger state (project, sequences)
+- `ticket_patterns`, `ticket_pattern_links` — patterns and their members
+- `tickets`, `ticket_aliases`, `ticket_tags`, `ticket_notes`
+
+Timestamps are stored as ISO text to keep round-trips identical to the JSON
+backend. `serializeState` / `deserializeRows` are exported pure mappers between
+`LoopState` and these rows.
+
+### Running the Postgres tests
+
+The Postgres integration test is skipped unless `DATABASE_URL` is set:
+
+```bash
+docker run -d --name agentloops-pg -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=agentloops -p 55432:5432 postgres:16
+DATABASE_URL=postgres://postgres:postgres@127.0.0.1:55432/agentloops npm test
+```
+
+CI runs it automatically against a `postgres:16` service container.

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@stevenvincentone/intidev-agentloops",
+  "version": "0.1.0",
+  "description": "IntiDev AgentLoops - Feedback Loops for Agentic Workflows",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "agentloop": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "cli": "tsx src/cli.ts",
+    "demo": "tsx scripts/demo-seed.ts",
+    "test": "tsx --test test/*.test.ts",
+    "start": "npm run cli --",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test",
+    "format": "npx prettier --write \"src/**/*.ts\" \"docs/**/*.md\" \"*.md\"",
+    "lint": "npx tsc --noEmit",
+    "typecheck": "npx tsc -p tsconfig.tooling.json"
+  },
+  "keywords": [
+    "agentic",
+    "issue-tracking",
+    "ticketing",
+    "feedback-loop",
+    "devtool",
+    "observability",
+    "knowledge-base",
+    "guardrails",
+    "agent-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/StevenVincentOne/IntiDev-AgentLoops.git"
+  },
+  "homepage": "https://github.com/StevenVincentOne/IntiDev-AgentLoops#readme",
+  "bugs": {
+    "url": "https://github.com/StevenVincentOne/IntiDev-AgentLoops/issues"
+  },
+  "author": {
+    "name": "Inti / Steven Vincent"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "@types/pg": "^8.11.10",
+    "pg": "^8.13.1",
+    "prettier": "^3.3.3",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.3"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/*.md",
+    "agentloop.config.json.example"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  }
+}