attraverso 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,7 @@
1
+ <p align="center">
2
+ <img src="roadmap/favicon.svg" alt="The attraverso logo: a robot crossing a hanging rope bridge" width="120">
3
+ </p>
4
+
1
5
  # attraverso
2
6
 
3
7
  Durable, structured project memory for AI coding agents, over [MCP](https://modelcontextprotocol.io): the plan,
@@ -13,6 +17,13 @@ budget-bounded slice rather than dumped into context wholesale.
13
17
  The plan lives as version-controlled YAML committed alongside your code, so it is reviewable in a pull request
14
18
  like any other file, and is rebuilt into an in-memory Postgres ([PGlite](https://pglite.dev)) on load.
15
19
 
20
+ And you can see it. The viewer draws the plan as a map, every item grouped by area and linked by what it depends
21
+ on, so it is both the way to explore your project and a window into what the agent remembers about it.
22
+
23
+ <p align="center">
24
+ <img src="docs/screenshots/desktop-graph.jpg" alt="The graph: each area a coloured box of its items, summarised when zoomed out" width="760">
25
+ </p>
26
+
16
27
  ## Quick start
17
28
 
18
29
  Needs Node 22 or newer. In your repo, with [Claude Code](https://claude.com/claude-code):
@@ -35,12 +46,10 @@ And see the plan:
35
46
  npx attraverso viewer --open
36
47
  ```
37
48
 
38
- | | |
39
- | :-: | :-: |
40
- | <img src="docs/screenshots/desktop-graph.jpg" alt="The graph: each area a coloured box of its items, summarised when zoomed out" width="420"> | <img src="docs/screenshots/desktop-board.jpg" alt="The board: status columns, area lanes, the agreed order first" width="420"> |
41
- | **Graph**: items by dependency, grouped by area | **Board**: status columns, the agreed order first |
42
- | <img src="docs/screenshots/desktop-calendar.jpg" alt="The calendar: items on their planned days, or when they were filed or last changed" width="420"> | <img src="docs/screenshots/mobile-graph.jpg" alt="The graph on a phone, with the views in a bar along the bottom" width="200"> |
43
- | **Calendar**: planned dates, or when items were filed or changed | **Phone**: the same views, tabs along the bottom |
49
+ | | | |
50
+ | :-: | :-: | :-: |
51
+ | <img src="docs/screenshots/desktop-board.jpg" alt="The board: status columns, area lanes, the agreed order first" width="340"> | <img src="docs/screenshots/desktop-calendar.jpg" alt="The calendar: items on their planned days, or when they were filed or last changed" width="340"> | <img src="docs/screenshots/mobile-graph.jpg" alt="The graph on a phone, with the views in a bar along the bottom" width="150"> |
52
+ | **Board**: status columns, the agreed order first | **Calendar**: planned dates, or when items were filed or changed | **Phone**: the same views, tabs along the bottom |
44
53
 
45
54
  ## Using it
46
55
 
@@ -83,6 +92,24 @@ command finds the plan the way the server does (or takes `--store <path>`), prin
83
92
  `--open`. `--project <key>` picks which project it lands on. It can edit the plan as the agent's viewer can, and
84
93
  is safe to run beside a connected server on the same file. Ctrl+C stops it.
85
94
 
95
+ ### Where a claim came from
96
+
97
+ When something in the plan rests on more than the agent's own reasoning, it can say so. A claim is followed by a
98
+ short pointer, and the agent records what stands behind it:
99
+
100
+ ```markdown
101
+ The production database runs Postgres 18.4 [ref pg18].
102
+ ```
103
+
104
+ A source is one of `user` (your words, verbatim), `test` (the command that checks it), `search` (the URL), `docs`
105
+ (the file or page) or `code` (lines of a file at a commit, `src/db/schema.ts:120-140@345a746`). A claim can gather
106
+ several over time. It is all optional: anything without a pointer is simply the agent's own reasoning.
107
+
108
+ When the agent reads the item, each pointer comes back with its sources beside the claim. If the claim has been
109
+ edited since a source vouched for it, or the code a `code` source points at has changed, it says so. In the viewer,
110
+ references show as numbers - **[1]**, or **[2?]** when one deserves a second look - and clicking one highlights the
111
+ claim and shows where it came from. Nothing is ever refused over a reference; it is there to help, not to gate.
112
+
86
113
  ### Where the plan lives
87
114
 
88
115
  In order of precedence:
@@ -0,0 +1,77 @@
1
+ CREATE TABLE "source_references" (
2
+ "id" text PRIMARY KEY NOT NULL,
3
+ "project_id" text NOT NULL,
4
+ "key" text NOT NULL,
5
+ "item_id" text,
6
+ "section_id" text,
7
+ "source" text NOT NULL,
8
+ "detail" text NOT NULL,
9
+ "quoted_text" text NOT NULL,
10
+ "actor" text NOT NULL,
11
+ "recorded_at" text NOT NULL,
12
+ "retired_at" text,
13
+ CONSTRAINT "source_references_one_owner" CHECK (("source_references"."item_id" IS NULL) <> ("source_references"."section_id" IS NULL))
14
+ );
15
+ --> statement-breakpoint
16
+ ALTER TABLE "source_references" ADD CONSTRAINT "source_references_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
17
+ ALTER TABLE "source_references" ADD CONSTRAINT "source_references_item_id_items_id_fk" FOREIGN KEY ("item_id") REFERENCES "public"."items"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
18
+ ALTER TABLE "source_references" ADD CONSTRAINT "source_references_section_id_context_sections_id_fk" FOREIGN KEY ("section_id") REFERENCES "public"."context_sections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
19
+ CREATE INDEX "source_references_project_key" ON "source_references" USING btree ("project_id","key");--> statement-breakpoint
20
+ CREATE INDEX "source_references_item" ON "source_references" USING btree ("item_id");--> statement-breakpoint
21
+ CREATE INDEX "source_references_section" ON "source_references" USING btree ("section_id");--> statement-breakpoint
22
+ -- CTX-13: every live source reference's pointer is in its owner's text, and a key has one owner. Hand-written: a
23
+ -- trigger is beyond what drizzle-kit generates. Deferred to commit, so a reference and its pointer can arrive in
24
+ -- either order within one transaction. Each firing checks only the item, section or key that changed. Loading a
25
+ -- plan file sets attraverso.loading_plan for its transaction and is let through: a hand edit that broke a
26
+ -- pointer must still load (stale is a state a plan loads in, never a refusal to load), and apm:check reports it.
27
+ -- A pointer is "[ref key]" or the expanded "[ref key: ...]", matched exactly so r7k2 never matches r7k29.
28
+ CREATE FUNCTION "source_references_check"() RETURNS trigger LANGUAGE plpgsql AS $$
29
+ DECLARE
30
+ bad text;
31
+ BEGIN
32
+ IF current_setting('attraverso.loading_plan', true) = 'on' THEN
33
+ RETURN NULL;
34
+ END IF;
35
+ IF TG_TABLE_NAME = 'items' THEN
36
+ SELECT r.key INTO bad FROM source_references r JOIN items i ON i.id = r.item_id
37
+ WHERE r.item_id = NEW.id AND r.retired_at IS NULL
38
+ AND position('[ref ' || r.key || ']' IN coalesce(i.body, '')) = 0
39
+ AND position('[ref ' || r.key || ':' IN coalesce(i.body, '')) = 0
40
+ LIMIT 1;
41
+ ELSIF TG_TABLE_NAME = 'context_sections' THEN
42
+ SELECT r.key INTO bad FROM source_references r JOIN context_sections c ON c.id = r.section_id
43
+ WHERE r.section_id = NEW.id AND r.retired_at IS NULL
44
+ AND position('[ref ' || r.key || ']' IN c.content) = 0
45
+ AND position('[ref ' || r.key || ':' IN c.content) = 0
46
+ LIMIT 1;
47
+ ELSE
48
+ SELECT r.key INTO bad FROM source_references r
49
+ LEFT JOIN items i ON i.id = r.item_id LEFT JOIN context_sections c ON c.id = r.section_id
50
+ WHERE r.project_id = NEW.project_id AND r.key = NEW.key AND r.retired_at IS NULL
51
+ AND position('[ref ' || r.key || ']' IN coalesce(i.body, c.content, '')) = 0
52
+ AND position('[ref ' || r.key || ':' IN coalesce(i.body, c.content, '')) = 0
53
+ LIMIT 1;
54
+ IF bad IS NULL THEN
55
+ SELECT r.key INTO bad FROM source_references r
56
+ WHERE r.project_id = NEW.project_id AND r.key = NEW.key AND r.retired_at IS NULL
57
+ GROUP BY r.key HAVING count(DISTINCT coalesce(r.item_id, r.section_id)) > 1;
58
+ IF bad IS NOT NULL THEN
59
+ RAISE EXCEPTION 'source reference % has more than one owner', bad USING ERRCODE = 'check_violation';
60
+ END IF;
61
+ END IF;
62
+ END IF;
63
+ IF bad IS NOT NULL THEN
64
+ RAISE EXCEPTION 'source reference % is live but its pointer is not in the text', bad USING ERRCODE = 'check_violation';
65
+ END IF;
66
+ RETURN NULL;
67
+ END
68
+ $$;
69
+ --> statement-breakpoint
70
+ CREATE CONSTRAINT TRIGGER "source_references_on_items" AFTER UPDATE OF "body" ON "items"
71
+ DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION "source_references_check"();
72
+ --> statement-breakpoint
73
+ CREATE CONSTRAINT TRIGGER "source_references_on_sections" AFTER UPDATE OF "content" ON "context_sections"
74
+ DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION "source_references_check"();
75
+ --> statement-breakpoint
76
+ CREATE CONSTRAINT TRIGGER "source_references_on_rows" AFTER INSERT OR UPDATE ON "source_references"
77
+ DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION "source_references_check"();