bmad-module-ultracode-goal 2.3.0 → 3.0.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/.claude-plugin/marketplace.json +1 -1
- package/README.md +3 -3
- package/docs/_internal/STABILITY.md +17 -8
- package/docs/architecture.md +14 -8
- package/docs/comparison.md +20 -20
- package/docs/cross-session-recall.md +136 -54
- package/docs/getting-started.md +23 -13
- package/docs/how-it-works.md +4 -4
- package/docs/index.md +1 -1
- package/docs/knowledge-graph-refresh.md +31 -13
- package/docs/operating-tips.md +4 -12
- package/docs/troubleshooting.md +2 -1
- package/docs/why-ultracode-goal.md +3 -3
- package/package.json +18 -7
- package/skills/ucg-create-story/LICENSE.md +47 -0
- package/skills/ucg-create-story/SKILL.md +438 -0
- package/skills/ucg-create-story/checklist.md +357 -0
- package/skills/ucg-create-story/customize.toml +40 -0
- package/skills/ucg-create-story/discover-inputs.md +88 -0
- package/skills/ucg-create-story/template.md +49 -0
- package/skills/ucg-dev-story/LICENSE.md +49 -0
- package/skills/ucg-dev-story/SKILL.md +561 -0
- package/skills/ucg-dev-story/checklist.md +82 -0
- package/skills/ucg-dev-story/customize.toml +40 -0
- package/skills/ucg-formalize/SKILL.md +118 -46
- package/skills/ucg-resolve/SKILL.md +4 -2
- package/skills/ucg-status/SKILL.md +1 -1
- package/skills/ultracode-goal/SKILL.md +7 -5
- package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +1 -1
- package/skills/ultracode-goal/assets/ucg-awareness/{bmad-create-story.toml → ucg-create-story.toml} +10 -9
- package/skills/ultracode-goal/customize.toml +20 -6
- package/skills/ultracode-goal/references/define-done.md +15 -7
- package/skills/ultracode-goal/references/execute.md +26 -9
- package/skills/ultracode-goal/references/finalize.md +32 -25
- package/skills/ultracode-goal/references/gate.md +5 -3
- package/skills/ultracode-goal/references/health-check.md +4 -2
- package/skills/ultracode-goal/references/ingest-and-scope.md +29 -26
- package/skills/ultracode-goal/references/preflight.md +78 -30
- package/skills/ultracode-goal/scripts/claim_check.py +374 -0
- package/skills/ultracode-goal/scripts/drive_epic.py +1 -1
- package/skills/ultracode-goal/scripts/formalize_check.py +409 -72
- package/skills/ultracode-goal/scripts/gate_eval.py +203 -6
- package/skills/ultracode-goal/scripts/headless_envelope.py +30 -14
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +1762 -123
- package/skills/ultracode-goal/scripts/lib/mem_common.py +1277 -23
- package/skills/ultracode-goal/scripts/link_worktree_deps.py +174 -0
- package/skills/ultracode-goal/scripts/mem_observation.py +500 -147
- package/skills/ultracode-goal/scripts/mem_recall.py +307 -372
- package/skills/ultracode-goal/scripts/merge_customization.py +54 -27
- package/skills/ultracode-goal/scripts/mutate_check.py +200 -26
- package/skills/ultracode-goal/scripts/preflight_check.py +251 -103
- package/skills/ultracode-goal/scripts/red_ids.py +11 -1
- package/skills/ultracode-goal/scripts/story_sizing.py +107 -1
- package/tools/cli/commands/status.js +92 -47
- package/tools/cli/lib/ide-skills.js +5 -1
- package/tools/cli/lib/installer.js +12 -8
- package/.gitattributes +0 -16
- package/.nvmrc +0 -1
- package/docs/_internal/RELEASING.md +0 -134
- package/tools/build-docs.js +0 -350
- package/tools/validate-docs-links.js +0 -936
- package/tools/validate-fixtures.js +0 -161
- package/website/README.md +0 -92
- package/website/astro.config.mjs +0 -150
- package/website/package-lock.json +0 -8454
- package/website/package.json +0 -26
- package/website/public/favicon.svg +0 -13
- package/website/public/img/ucg-logo.svg +0 -73
- package/website/public/js/mermaid-lightbox.js +0 -67
- package/website/public/robots.txt +0 -36
- package/website/src/components/Banner.astro +0 -82
- package/website/src/components/Header.astro +0 -146
- package/website/src/components/MobileMenuFooter.astro +0 -69
- package/website/src/content/config.ts +0 -6
- package/website/src/lib/site-url.js +0 -28
- package/website/src/pages/404.astro +0 -11
- package/website/src/rehype-base-paths.js +0 -83
- package/website/src/rehype-markdown-links.js +0 -189
- package/website/src/styles/custom.css +0 -674
- package/website/tsconfig.json +0 -9
|
@@ -1,112 +1,194 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Cross-Session Recall
|
|
3
|
-
description: The optional
|
|
3
|
+
description: The optional run history - UCG keeps one record per run in a local store it owns, and reads this repo's past runs before it scopes an Epic and before its preflight gate. Advisory only, never in the gate path. Opt-in, hook-latched, off by default.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **Optional, opt-in, off by default.** Cross-Session Recall is an *advisory* read of your own past runs. It informs the model; it never decides anything. It
|
|
6
|
+
> **Optional, opt-in, off by default.** Cross-Session Recall is an *advisory* read of your own past runs. It informs the model; it never decides anything. It can **never** sit in the gate or completion path, and it **fails closed** during a run. When it is off, a run reads no past runs and writes no record.
|
|
7
7
|
|
|
8
8
|
## What it does
|
|
9
9
|
|
|
10
|
-
Cross-Session Recall lets UCG learn from its own history in *this* codebase instead of starting amnesiac every Epic.
|
|
10
|
+
Cross-Session Recall lets UCG learn from its own history in *this* codebase instead of starting amnesiac every Epic. Each run that reaches Finalize writes one small record of how it went: the Epic, the gate status, the verdict and the root causes it hit. Before the next run scopes its Epic, and again before its preflight gate, UCG reads this repo's records and surfaces what bit you here before. You stay in the driver's seat; it informs, it doesn't auto-decide.
|
|
11
11
|
|
|
12
12
|
The benefit compounds: your first Epic teaches it, your third Epic consults two.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Recall lives in a store UCG owns, on this machine. It needs nothing new to install: two scripts that ship with the skill, `mem_recall.py` and `mem_observation.py`, read and write it, with the Python and `uv` UCG already requires. There is no memory tool and no MCP call.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
> **UCG no longer uses claude-mem.** Earlier versions read and wrote your run summaries through claude-mem's MCP tools. If you used that, see [migrating from claude-mem](#migrating-from-claude-mem).
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
## The store
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
The store is a folder you name with the `cross_session_recall_store` key.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
- **No default.** The key ships as `""`. An empty or blank value, an unresolved `{...}` token, a literal `$VAR` or `%VAR%` and a relative path all count as unset.
|
|
23
|
+
- **Accepted values.** A `~` path, expanded like `health_check_seen_cache`, such as `~/.ultracode-goal/recall`. An absolute path or a `{project-root}` path works too.
|
|
24
|
+
- **Layout.** Each run gets one file, `<store>/<fingerprint-dir>/runs/<run_id>.jsonl`, holding one JSON line. The file is created once and never rewritten. `<fingerprint-dir>` comes from this repo's fingerprint (its origin and root commit), in a form that is legal on Windows; a repo with no remote gets `local-<hex>`.
|
|
25
|
+
- **Per machine.** Another developer or a CI runner never sees this machine's records. Worktrees and clones of one repo on this machine share the same fingerprint, so they read each other's records. A shared store is a follow-up, tracked in [#154](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/154).
|
|
26
|
+
- **It ignores itself.** When the scripts create the store folder, they write a `.gitignore` holding `*` inside it, so a store inside your workspace leaves `git status` clean. A folder that already existed gets no `.gitignore`.
|
|
27
|
+
- **Give it a folder of its own.** While a run is active, the guard denies every tool call that names the store. A store set to your workspace, to a folder above it, or to a folder that holds the implementation artifacts makes nearly every command there name the store, so they are denied. [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) has the detail.
|
|
28
|
+
- **Growth.** The store has no pruning yet. Each run, so each `drive_epic` spawn, adds one small file, and Ingest reads them all. The filter's 120-day horizon hides stale records at read time, except records holding a root cause that two or more runs recorded. Pruning is a follow-up, most naturally with #154.
|
|
23
29
|
|
|
24
|
-
|
|
30
|
+
## Turning it on
|
|
31
|
+
|
|
32
|
+
Set both keys in your project's `_bmad/custom/ultracode-goal.toml`. **No installer creates that file**, so on most projects you are creating it: `_bmad/custom/` exists already, but the `config.toml` sitting in it belongs to BMAD's own configuration, and putting a UCG knob there does nothing.
|
|
33
|
+
|
|
34
|
+
```toml
|
|
35
|
+
[workflow]
|
|
36
|
+
# Cross-Session Recall: read and record prior runs of this repo in a local store.
|
|
37
|
+
# Advisory only, never part of the gate. Off by default.
|
|
38
|
+
cross_session_recall = "on"
|
|
39
|
+
cross_session_recall_store = "~/.ultracode-goal/recall"
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The `[workflow]` table header matters: the resolver extracts the `workflow` block from the merged files, so a bare top-level line is silently discarded and the feature stays off.
|
|
43
|
+
|
|
44
|
+
Both keys are needed. With `on` and the store key unset, the run's latch is red, recall stays off, and the run report carries `NOTE recall-store-unset`, naming the key. A store folder that cannot be written also turns the latch red; the run report then gives the latch's `reason`.
|
|
25
45
|
|
|
26
|
-
|
|
46
|
+
If you ran with `cross_session_recall = "on"` before this release, recall stays off until you set the store key. That is on purpose: no run summary moves to a new place without your choice.
|
|
27
47
|
|
|
28
|
-
##
|
|
48
|
+
## Turning it off
|
|
29
49
|
|
|
30
|
-
|
|
50
|
+
Set the knob back to `off` (its default):
|
|
51
|
+
|
|
52
|
+
```toml
|
|
53
|
+
[workflow]
|
|
54
|
+
cross_session_recall = "off"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Off still writes the run latch at Stage 1, so while a run is active the guard still denies claude-mem calls, calls that name a set store, and changes to the latch. Only reading and writing records stops.
|
|
58
|
+
|
|
59
|
+
> **OFF-coherence disclosure.** UCG does not use claude-mem, whether recall is on or off. A separately installed claude-mem still captures your sessions and injects its session-start index into them; that is claude-mem's behavior, not UCG's. To stop that, configure or uninstall claude-mem itself.
|
|
60
|
+
|
|
61
|
+
## What a run does
|
|
62
|
+
|
|
63
|
+
Recall touches the run in three places. A machine latch, `.mem-state.json` in the implementation artifacts folder, is present for the whole run, and the `PreToolUse` guard reads it on every tool call.
|
|
31
64
|
|
|
32
65
|
```mermaid
|
|
33
66
|
flowchart TD
|
|
34
|
-
I["Stage 1 Ingest: write latch,
|
|
67
|
+
I["Stage 1 Ingest: write the latch, then one filtered read"] --> P{"Stage 2 Preflight: reuses the Stage 1 read"}
|
|
35
68
|
P -->|"advisory only, voice never vote"| X["Stage 4 Execute: untouched"]
|
|
36
69
|
X --> G["Stage 5 Gate: untouched, gate_eval.py only"]
|
|
37
|
-
G --> F["Stage 6 Finalize: one
|
|
70
|
+
G --> F["Stage 6 Finalize: drain, write one record, then unlatch"]
|
|
71
|
+
|
|
72
|
+
STORE[("Local run store: one file per run")]
|
|
73
|
+
I -.->|"reads"| STORE
|
|
74
|
+
F -.->|"writes"| STORE
|
|
38
75
|
|
|
39
|
-
LATCH{".mem-state.json latch: present
|
|
40
|
-
LATCH -.->|"
|
|
41
|
-
LATCH -.->|"
|
|
42
|
-
LATCH -.->|"
|
|
76
|
+
LATCH{".mem-state.json latch: while present, the guard denies claude-mem, calls that name the store, and changes to the latch"}
|
|
77
|
+
LATCH -.->|"guards"| I
|
|
78
|
+
LATCH -.->|"guards"| P
|
|
79
|
+
LATCH -.->|"guards"| F
|
|
43
80
|
|
|
44
81
|
classDef gate fill:#6366F1,stroke:#4F46E5,color:#fff
|
|
45
82
|
class P,LATCH gate
|
|
46
83
|
```
|
|
47
84
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
85
|
+
| Stage | What recall does |
|
|
86
|
+
| --- | --- |
|
|
87
|
+
| Stage 1 Ingest | Mints the run id, then runs `mem_recall.py latch` whatever the knob says, which writes the latch. With recall `on`, the latch is green only when the store can be written. On a green latch, one `mem_recall.py filter` call reads this repo's records. An attended run shows one line per record; a headless run logs them and goes on. |
|
|
88
|
+
| Stage 2 Preflight | Reuses the Stage 1 read as prior-failure hypotheses for the readiness check. It never reads the store again, and a recalled record is never a RED on its own. A preflight STOP removes the latch first. |
|
|
89
|
+
| Stage 4 Execute, Stage 5 Gate | Untouched. |
|
|
90
|
+
| Stage 6 Finalize | Reads the latch. Only when it is this run's and green: `mem_observation.py drain` lands records parked earlier, then `mem_observation.py write` writes this run's record. Then, on every path, `mem_recall.py unlatch` removes this run's latch. |
|
|
51
91
|
|
|
52
|
-
|
|
92
|
+
Each recall call is attempted once and never retried. A run whose recall turned off along the way says so in its report, with the tokens under [troubleshooting](#troubleshooting).
|
|
53
93
|
|
|
54
|
-
|
|
94
|
+
**What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed with whether they recurred, the time, and the project's folder name for display. Free text is redacted before it is written. A run whose gate was never evaluated writes no record; a `WAIVED` outcome is written.
|
|
55
95
|
|
|
56
|
-
The
|
|
96
|
+
**When the store cannot take a record.** The record waits in `mem-outbox.<run_id>.jsonl` in the implementation artifacts folder, and the run logs `WARN mem-write-deferred`. The next run that reaches Finalize with a green latch drains it, keeping its original time. A deferred record older than 14 days is dropped, and one whose drain fails three times moves to `mem-outbox.dead.jsonl`, with `WARN mem-write-dead-lettered`. No drain replays that file.
|
|
57
97
|
|
|
58
|
-
|
|
98
|
+
### One record per spawn
|
|
59
99
|
|
|
60
|
-
- **
|
|
61
|
-
- **Redacts secrets.** High-precision patterns (AWS keys, `ghp_`/`gho_` tokens, `sk-` keys, bearer tokens, PEM headers, `password=`/`token=`/`api_key=` values) are replaced with `[redacted]`.
|
|
62
|
-
- **Neutralizes shape.** Bidi controls are stripped, backticks and code fences removed, newlines collapsed, and each surfaced title clamped to 80 codepoints, so an advisory cannot carry instruction-shaped or prompt-injection payloads.
|
|
63
|
-
- **Drops the stale and the foreign.** Records past the recency horizon are dropped (signatures that recurred across two or more distinct runs earn per-signal horizon immunity), foreign-project and cross-schema records are filtered out, and malformed records are discarded.
|
|
100
|
+
`drive_epic.py` runs each story in its own `claude -p` session, and each spawn is its own run with its own run id: a spawn that resumes the Epic mints a fresh one and never reuses an earlier spawn's. So a drive writes **one record file per spawn**, not one per Epic. The consequence: **two stories of one drive hitting the same root cause count as recurring**, and that root cause is then exempt from the 120-day horizon, even though one drive produced both records. A spawn killed by the driver's session timeout never reaches Finalize and writes no record.
|
|
64
101
|
|
|
65
|
-
|
|
102
|
+
## The latch and the guard
|
|
66
103
|
|
|
67
|
-
|
|
68
|
-
- It does **not** vote. Advisories carry only a mechanical `recurred` field (`yes`/`no`/`unknown`); there are no LLM self-grades, and nothing recall surfaces is ever an input to `gate_eval.py`. The gate reads TEA's `gate-decision.json` and only that. See the [gate model](./gate-model.md).
|
|
69
|
-
- It does **not** keep working when claude-mem looks wrong. If the capability contract fails (a missing tool, a malformed probe, a breaking schema change) the latch records recall as absent and the hook denies claude-mem calls for the run. Fail closed, never fail open.
|
|
104
|
+
The latch is how the guard knows a run is active. Only `mem_recall.py` changes it: `latch` writes or replaces it at Stage 1, and `unlatch` removes it at each exit (Finalize, a preflight STOP, or any other stop before Finalize, attended or headless), only when it carries that run's id.
|
|
70
105
|
|
|
71
|
-
|
|
106
|
+
The latch never belongs in git. `latch` adds a line for the latch to the repository's `.git/info/exclude`, a local file git never commits: `/<artifacts folder>/.mem-state*`, anchored to the implementation artifacts folder so no other file is hidden. So on a project that tracks its artifacts folder, the latch does not show in `git status`, does not trip preflight's clean-tree check, and is not staged by a `git add -A`. A latch git already tracks, which a run on an earlier release could commit, still shows as a change: `latch` then prints `NOTE recall-latch-visible`, and you untrack it once by hand, from a terminal of your own once no run is active: while a latch is present, the guard denies a command that names it.
|
|
72
107
|
|
|
73
|
-
|
|
108
|
+
While a latch is present, whatever it records, the guard:
|
|
74
109
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
# Requires claude-mem installed; advisory only, never part of the gate. Off by default.
|
|
79
|
-
cross_session_recall = "on"
|
|
80
|
-
```
|
|
110
|
+
- **denies every claude-mem call**: claude-mem's MCP tools, its MCP resources, a resource listing that names no server (it lists every server's resources, claude-mem's included), and any reach into `.claude-mem` by its name or a path to it. A search of a folder above it, such as your home folder, is not seen. There is no green path, since UCG does not use claude-mem any more.
|
|
111
|
+
- **denies tool calls that name the store**: Read, Grep, Glob, Write, Edit, MultiEdit, NotebookEdit and Bash. Only the two recall scripts get through, run by the path the skill is installed at.
|
|
112
|
+
- **denies tool calls that would change the latch**: Write, Edit, MultiEdit and NotebookEdit, and Bash commands such as `rm`, `mv`, `cp`, `tee`, a redirection, `sed -i`, `truncate` or `python -c`. A Bash command counts when it names the latch by its path or by its file name alone, so a `cd` into its folder first changes nothing. Reading it stays allowed (Read, Grep, Glob, or a plain `cat`), since Finalize reads it.
|
|
81
113
|
|
|
82
|
-
|
|
114
|
+
With no latch present, the guard leaves claude-mem, the store and the latch path alone. Most of these denies are file-tool or MCP calls, so the guard sees them only when its hook group matches every tool. Preflight arms it that way; if you merge the hook by hand, match every tool. [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) (invariants 6 and 7) has the full rules and their limits.
|
|
83
115
|
|
|
84
|
-
|
|
116
|
+
### A latch left behind
|
|
85
117
|
|
|
86
|
-
|
|
118
|
+
The guard cannot tell a live run from a dead one: a present latch counts as live. If a run ends without removing its latch, because it crashed, was killed, or its `unlatch` call was refused, the latch keeps denying, in your later sessions too. It stays until the next run's Stage 1 replaces it or you delete it by hand.
|
|
87
119
|
|
|
88
|
-
|
|
120
|
+
Every deny a latch causes names the latch file and ends with a note for you:
|
|
89
121
|
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
cross_session_recall = "off"
|
|
122
|
+
```text
|
|
123
|
+
For the user: if no UltraCode-Goal run is active, a run ended without removing this latch. Delete <path> by hand. The model must not try to remove it itself.
|
|
93
124
|
```
|
|
94
125
|
|
|
95
|
-
|
|
126
|
+
If no run is active, delete that one file yourself rather than asking the model. The guard denies the model's own ways to remove it, such as `rm` or a file tool, and the note tells the model not to try. The recall script's own `unlatch` call is the one way through, since the guard lets those scripts pass; [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md) lists this limit.
|
|
127
|
+
|
|
128
|
+
## The trust model
|
|
129
|
+
|
|
130
|
+
The rule is **data, never directive**: recalled content is treated as facts to consider, never as instructions to follow, and it never reaches the gate.
|
|
96
131
|
|
|
97
|
-
|
|
132
|
+
What the reader **does** before any advisory is surfaced:
|
|
98
133
|
|
|
99
|
-
|
|
134
|
+
- **Scopes to this repo.** The repository fingerprint pins recall to the same origin and root commit, so another project's history cannot leak in.
|
|
135
|
+
- **Redacts secrets.** High-precision patterns (AWS keys, `ghp_`/`gho_` tokens, `sk-` keys, bearer tokens, PEM headers, `password=`/`token=`/`api_key=` values) are replaced with `[redacted]`, when a record is written and again when it is read.
|
|
136
|
+
- **Neutralizes shape.** The line shown for each record is built from its Epic, gate status and verdict. Bidi controls are stripped, backticks removed, newlines collapsed, a lone surrogate escape (text that is not valid Unicode) replaced with U+FFFD, and each line clamped, so an advisory cannot carry instruction-shaped or prompt-injection payloads.
|
|
137
|
+
- **Drops the bad one by one.** A file that does not parse, nests deeper than any record, or has the wrong shape is dropped as `invalid`, a newer record format as `cross_schema`, and another repo's record as foreign. A name that is not a regular file, such as a FIFO, is skipped unread. One bad file never stops the read or turns the latch red.
|
|
138
|
+
- **Drops the stale.** Records past the 120-day horizon are dropped, unless a root cause in them was recorded by two or more distinct runs.
|
|
139
|
+
- **Stays bounded.** At most 5 records, 2048 bytes each and 8192 bytes in all, in the same order every time: this Epic first, then recurring, then the most recent.
|
|
140
|
+
|
|
141
|
+
What it honestly does **not** do:
|
|
142
|
+
|
|
143
|
+
- It is **not** a complete secret scrubber: redaction is high-precision pattern matching, not a guarantee that nothing sensitive ever survives.
|
|
144
|
+
- It does **not** vote. Advisories carry only a mechanical `recurred` field (`yes`/`no`/`unknown`); there are no LLM self-grades, and nothing recall surfaces is ever an input to `gate_eval.py`. The gate reads TEA's `gate-decision.json` and only that. See the [gate model](./gate-model.md).
|
|
145
|
+
- It does **not** keep going when the store looks wrong. A store that cannot be written turns the latch red, and the run goes on with recall off. Fail closed, never fail open.
|
|
146
|
+
|
|
147
|
+
## Migrating from claude-mem
|
|
148
|
+
|
|
149
|
+
- **Opt in again.** Set `cross_session_recall_store`. Until you do, `on` gives a red latch and `NOTE recall-store-unset`.
|
|
150
|
+
- **History is not imported.** Recall starts empty. A root cause counts as recurring once two runs record it.
|
|
151
|
+
- **Parked summaries are converted.** A summary an earlier version parked in `mem-outbox.<run_id>.jsonl` is turned into a store record by the next green Finalize's drain, keeping its original time, even when it is older than 14 days. One that cannot be converted moves to `mem-outbox.dead.jsonl` with `NOTE mem-legacy-unconvertible`. The run report prints the `converted` and `legacy_unconvertible` counts.
|
|
152
|
+
- **The dead-letter file is kept.** The existing `mem-outbox.dead.jsonl` is never converted. It stays for you to inspect or delete.
|
|
153
|
+
- **An old latch reads as red.** A latch an earlier version wrote still denies claude-mem and any change to the latch file. If no run is active, delete it by hand, or let the next Stage 1 replace it.
|
|
154
|
+
- **Removed script forms.** `mem_recall.py selftest`, the `latch` flags `--probe`, `--claude-mem-absent` and `--tool-form`, a `latch` or `filter` call without `--store`, `filter --probe` and `filter --project`, and `mem_observation.py build`, `spill` and `drain` without `--store` are gone. Each exits 2 with one line naming its replacement. This matters only if you called the scripts yourself.
|
|
155
|
+
- **claude-mem's own capture keeps running** where it is installed. UCG stops writing to it and depending on it; it does not stop it.
|
|
156
|
+
|
|
157
|
+
## Troubleshooting
|
|
158
|
+
|
|
159
|
+
Each recall problem leaves a line in `.decision-log.md` and the run report: one of these tokens, a red latch's `reason`, or what a recall call that exited non-zero printed.
|
|
160
|
+
|
|
161
|
+
| Token | When | What to do |
|
|
162
|
+
| --- | --- | --- |
|
|
163
|
+
| `NOTE recall-store-unset` | Stage 1: recall is `on` but the store key is unset, or is not a `~`, absolute or `{project-root}` path. | Set `cross_session_recall_store` in `[workflow]`. |
|
|
164
|
+
| Red latch, `reason` `store-unwritable: <error>` | Stage 1: recall is `on` but the store folder could not be created or written. Recall is off for the run, and the run report repeats the reason. | Fix the folder (permissions, disk space, sandbox) or set the key to another folder. |
|
|
165
|
+
| Red latch, `reason` `no-fingerprint` | Stage 1: the repo has no commit yet, or the session's working folder is not inside it, so its records have no folder. Recall is off for the run. | Make a first commit, or start the session from the project folder. |
|
|
166
|
+
| `NOTE recall-latch-visible` | Stage 1: git can still see the latch, so it shows as a change and preflight's clean-tree check reads it. Either git already tracks it, committed by a run on an earlier release, or the repository's `.git/info/exclude` could not be written; the NOTE says which. | Once no run is active, untrack it from a terminal of your own with `git rm --cached <the latch path>` and commit that, or fix the exclude file the NOTE names. While a latch is present, the guard denies a command that names it. |
|
|
167
|
+
| A latch call that exits non-zero | Stage 1: the latch call failed (for example, the implementation artifacts folder cannot be written). It writes no latch, so Finalize also logs `NOTE recall-latch-missing`; the log holds what it printed. | Fix what the log names. |
|
|
168
|
+
| A filter, drain or write call that exits non-zero | Stage 1 or Finalize: the call failed. The log and the run report hold what it printed, and the run goes on: a failed filter surfaces no advisories, a failed drain still lets the write run, and a failed write may leave no record. | Fix what the log names. |
|
|
169
|
+
| `NOTE recall-read-refused` | Stage 1: the permission layer refused the latch or filter call. A refused latch call leaves no latch, so recall is off for the run and Finalize also logs `NOTE recall-latch-missing`. A refused filter call only skips the read: Finalize still writes the record. | Let the recall scripts' `uv run` calls through your permission mode. |
|
|
170
|
+
| `NOTE recall-latch-missing` | Finalize: there was no latch, or another run's latch. No record is written. | Look earlier in the log for the cause, such as `NOTE recall-read-refused`, a latch call that failed, or another run started in the same folder. |
|
|
171
|
+
| `NOTE recall-write-refused` | Finalize: the permission layer refused the drain or write call. Nothing is parked. | Let the recall scripts' `uv run` calls through your permission mode. |
|
|
172
|
+
| `NOTE recall-unlatch-failed` | Any exit: removing this run's latch was refused or failed, so the latch is still there and keeps the guard denying. | Delete the latch file the NOTE names by hand. |
|
|
173
|
+
| `WARN mem-write-deferred` | Finalize: the store could not take the record, so it waits in the outbox. | Fix the store folder (permissions, disk space, sandbox). The next green Finalize drains it. |
|
|
174
|
+
| `WARN mem-write-dead-lettered` | Drain: a parked record failed its third write, so it moved to `mem-outbox.dead.jsonl`, and the run report's `dead_lettered` count includes it. No drain replays that file. | Fix the store folder. The record stays in `mem-outbox.dead.jsonl` for you to inspect. |
|
|
175
|
+
| `NOTE mem-target-foreign` | The run's file already exists but is not this run's, or cannot be parsed. It is never touched; the record moves to `mem-outbox.dead.jsonl`. | Inspect that run file. |
|
|
176
|
+
| `NOTE mem-run-id-invalid` | Drain: a parked record carries a malformed run id. It moves to `mem-outbox.dead.jsonl`; the others still land. | Inspect `mem-outbox.dead.jsonl`. |
|
|
177
|
+
| `NOTE mem-legacy-unconvertible` | Drain: a summary parked by a claude-mem era run cannot be converted. It moves to `mem-outbox.dead.jsonl`. | Inspect `mem-outbox.dead.jsonl`. |
|
|
178
|
+
|
|
179
|
+
A claude-mem call, a call that names the store, or a call that would change the latch, denied while no run is active, means a latch was left behind: see [a latch left behind](#a-latch-left-behind).
|
|
100
180
|
|
|
101
181
|
## Known limits: be honest
|
|
102
182
|
|
|
103
183
|
Recall is deliberately bounded. Treat these as the residuals you are signing up for:
|
|
104
184
|
|
|
105
185
|
- **A factual advisory still informs reasoning.** Sanitized advisories carry no instruction-shaped, stale, or foreign content and never reach the gate, but a well-formed factual advisory can still inform the model's reasoning. That is the feature, bounded; it is not a side channel into the verdict.
|
|
106
|
-
- **
|
|
107
|
-
- **
|
|
186
|
+
- **The store is per machine.** Recall across Epics holds on one machine only, until [#154](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/154).
|
|
187
|
+
- **The store folder follows the fingerprint.** If a repo with no remote gains one, or you work from a shallow clone, new records go to another folder and the earlier ones stop being read.
|
|
188
|
+
- **A record file is plain JSON.** Anyone who can write the store folder can edit one. The reader treats every record as untrusted data and defangs it, but it cannot tell an edited record from a real one.
|
|
108
189
|
- **Redaction is high-precision, not complete.** Secret redaction is pattern matching tuned for precision; it is not a complete data-loss-prevention layer.
|
|
109
|
-
- **A
|
|
190
|
+
- **A latch left behind keeps denying.** It blocks claude-mem, the store and changes to the latch until you delete it by hand or the next run replaces it.
|
|
191
|
+
- **The guard matches what a call spells.** It does not follow indirection, such as a variable holding part of a path, or a `cd` then a relative path to the store. SECURITY.md lists these limits.
|
|
110
192
|
|
|
111
193
|
## The default, and what would flip it
|
|
112
194
|
|
package/docs/getting-started.md
CHANGED
|
@@ -9,20 +9,30 @@ Install UltraCode Goal into a BMAD project, point it at an Epic, and let it run
|
|
|
9
9
|
|
|
10
10
|
UltraCode Goal conducts BMAD and TEA skills and runs deterministic Python under `uv`. You need:
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
| `
|
|
19
|
-
|
|
|
20
|
-
|
|
|
21
|
-
|
|
|
12
|
+
<!-- tool-requirements:start -->
|
|
13
|
+
<!-- Generated from tools/tool-requirements.yaml by `node tools/tool-requirements.js --write`: edit that file, not this table. -->
|
|
14
|
+
|
|
15
|
+
| Tool | Used for | Minimum | Tested on | Install |
|
|
16
|
+
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------------- | --------------------------------------------------------------------------- |
|
|
17
|
+
| Claude Code | **The runtime: non-negotiable.** UCG composes Auto Mode, Auto Memory, and runtime hooks, which only exist in Claude Code, and writes each story's Definition-of-Done as a `/goal`-style condition; the autonomous run cannot execute anywhere else. Preflight refuses to launch below the minimum | 2.1.154 | 2.1.301 | <https://claude.com/product/claude-code> |
|
|
18
|
+
| Node.js | Installation, `npx` commands | 22 | 22, 24 | <https://nodejs.org> |
|
|
19
|
+
| Python | The deterministic gate, preflight, and hook scripts (run via `uv`) | 3.11 | 3.11, 3.12 | <https://www.python.org> |
|
|
20
|
+
| `uv` (Python package runner) | Running the module's Python scripts with automatic dependency management | none | 0.13.1 | <https://docs.astral.sh/uv/getting-started/installation/> |
|
|
21
|
+
| `git` | Epic-branch isolation and per-story commits (the real rollback) | none | 2.55.0, 2.56.0 | <https://git-scm.com/downloads> |
|
|
22
|
+
| `gh` (GitHub CLI) | Submitting or queuing [health-check](./health-check.md) findings | none | not recorded | <https://cli.github.com> |
|
|
23
|
+
| BMAD Method | The Epic toolbox UCG conducts, `bmad-sprint-planning`, `bmad-code-review` and the rest. No deprecated shims are needed, since UCG ships its own story skills (see below) | 6.2 | 6.12.0 | <https://docs.bmad-method.org> |
|
|
24
|
+
| TEA (Test Architect) | **The gate: non-negotiable.** UCG invokes the `bmad-testarch-*` skills to produce the `gate-decision.json` that `gate_eval.py` reads. Required in both profiles: `--light` still runs test-design and trace. Supported: TEA 1.27.x with BMAD Method 6. TEA 2.0 and later, and BMAD 7, are not supported yet. Preflight refuses to launch without the skills the run's profile delegates to | none | 1.27.2 | <https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise> |
|
|
25
|
+
| A BMAD project with an Epic | The unit of delivery: a `_bmad/` install, a `sprint-status.yaml`, and at least one Epic with stories | | | see <https://docs.bmad-method.org> |
|
|
26
|
+
|
|
27
|
+
<!-- tool-requirements:end -->
|
|
28
|
+
|
|
29
|
+
**Minimum** is the oldest version UCG accepts; for Claude Code it is the version preflight refuses to launch below. **Tested on** lists the versions UCG's own runs use: CI, the install smoke test or a named Epic run (the README's "Tested with" table, which also records that run's profile). `none` means UCG sets no minimum for the tool yet, and `not recorded` means no UCG run has recorded a version of it yet.
|
|
22
30
|
|
|
23
31
|
The run also depends on recent Claude Code primitives: dynamic workflows and Auto Memory, plus `/goal` if you start one yourself. The preflight script version-gates these and reports a mechanical blocker if the installed Claude Code is below the minimum any of them needs (see [troubleshooting](./troubleshooting.md)).
|
|
24
32
|
|
|
25
|
-
**
|
|
33
|
+
**No BMAD shims needed.** UltraCode Goal ships its own story skills, `ucg-create-story` and `ucg-dev-story`, adapted from BMAD Method's `bmad-create-story` and `bmad-dev-story`, which BMAD 6.12 made opt-in shims (a fresh install leaves them out, and the installer recommends declining them) and v7 removes. UCG's installer copies both beside the `ultracode-goal` skill, so a BMAD install made without shims runs UCG as it is. While either is missing from `.claude/skills/`, preflight reports a non-remediable blocker and the run does not launch; run `npx bmad-module-ultracode-goal update` from the project root to restore them, or `install` where UCG was never installed in the project (a plugin-marketplace install alone ships neither). If you installed BMAD with `--shims`, its own `bmad-create-story` and `bmad-dev-story` stay yours to run by hand, and a UCG run never uses them. A team override written for them (`_bmad/custom/bmad-create-story.toml` or `bmad-dev-story.toml`) no longer reaches a UCG run: copy what it holds to `_bmad/custom/ucg-create-story.toml` or `ucg-dev-story.toml`, which UCG's skills read the same way.
|
|
34
|
+
|
|
35
|
+
**Supported BMAD and TEA.** UCG supports BMAD Method 6 with TEA 1.27.x. BMAD Method 6.12.2 and later install TEA 1.27.2, while an older BMAD 6 installer can pick a later TEA. TEA 2.0 and later, and BMAD 7, are not supported yet: TEA 2.0 moved to BMAD 7's module format, and TEA 3.0 renamed the `bmad-testarch-*` skills UCG calls to `bmad-tea-*`. Preflight refuses to launch while a TEA skill the run's profile delegates to is missing from `.claude/skills/`. It checks skill names, not the TEA version, so it does not catch TEA 2.x, which kept the old names. Production needs all eight `bmad-testarch-*` skills. `--light` needs `bmad-testarch-framework`, `bmad-testarch-test-design` and `bmad-testarch-trace`. Add TEA from the project root with `npx bmad-method install`, with the `tea` module selected.
|
|
26
36
|
|
|
27
37
|
## Install
|
|
28
38
|
|
|
@@ -30,7 +40,7 @@ The run also depends on recent Claude Code primitives: dynamic workflows and Aut
|
|
|
30
40
|
npx bmad-module-ultracode-goal install
|
|
31
41
|
```
|
|
32
42
|
|
|
33
|
-
The installer is interactive: it prompts for the project name and whether to install the learning material, then installs the skill for Claude Code. As an alternative, the module can be installed from the plugin marketplace entry (`.claude-plugin/marketplace.json`) the same way as other BMAD plugins.
|
|
43
|
+
The installer is interactive: it prompts for the project name and whether to install the learning material, then installs the skill for Claude Code. As an alternative, the module can be installed from the plugin marketplace entry (`.claude-plugin/marketplace.json`) the same way as other BMAD plugins. That entry ships the `ultracode-goal` skill alone, so run `npx bmad-module-ultracode-goal install` in the project as well: it adds the story skills a run delegates to (`ucg-create-story`, `ucg-dev-story`) and the `ucg-*` commands, and preflight does not launch without the story skills.
|
|
34
44
|
|
|
35
45
|
## First run
|
|
36
46
|
|
|
@@ -38,7 +48,7 @@ Invoke the skill with one of its trigger phrases ("run an epic autonomously", "e
|
|
|
38
48
|
|
|
39
49
|
1. **Name the Epic.** Stage 1 opens the floor: name the Epic, or drop any context (a story id, a branch, a paste of the Epic body). The skill fills the gaps from the BMAD artifacts. If `_bmad/` config, `sprint-status.yaml`, and any Epic are *all* absent, this is not a BMAD project; the skill says so and stops, pointing you at `bmad-bmb-setup` and `bmad-sprint-planning`.
|
|
40
50
|
2. **Preflight runs.** Stage 2 is the autonomy gate. It runs a mechanical check (`preflight_check.py`), auto-remediates the fixable ambers (scaffolding the test framework, generating missing acceptance criteria, pre-creating TEA output dirs, and so on), then adds a semantic scan for undecided product or architecture decisions the script cannot see. The run launches **only** when the post-remediation intervention budget is zero and the semantic scan found no red blocker. A single undecided architecture decision stops the run here rather than letting an unattended run guess it.
|
|
41
|
-
3. **The launch briefing.** On an attended run, before the first unattended action the skill prints a one-screen briefing: what is about to run, the per-story turn ceiling (it sizes stories; it does not cap time or cost), the autonomy line ("from here I will not ask you anything"), the kill switch (Ctrl-C, or delete the Epic branch; `/rewind` will not help), and where to watch (the run's `.decision-log.md` and `run-status.json`). One soft confirm crosses the line.
|
|
51
|
+
3. **The launch briefing.** On an attended run, before the first unattended action the skill prints a one-screen briefing: what is about to run, the per-story turn ceiling (it sizes stories; it does not cap time or cost), the autonomy line ("from here I will not ask you anything"), the kill switch (Ctrl-C, or delete the Epic branch; `/rewind` will not help; on a project that gitignores its BMAD output, the branch undoes the code only), and where to watch (the run's `.decision-log.md` and `run-status.json`). One soft confirm crosses the line.
|
|
42
52
|
|
|
43
53
|
From there the run is autonomous: it defines done with TEA, executes each story to a green commit, gates each one deterministically, and finalizes with a run report and the deferred-work ledger. See [how it works](./how-it-works.md) for the full stage-by-stage narration and the routing diagram.
|
|
44
54
|
|
package/docs/how-it-works.md
CHANGED
|
@@ -66,19 +66,19 @@ The one absence that hard-stops here: if `_bmad/` config **and** `sprint-status.
|
|
|
66
66
|
|
|
67
67
|
This is the load-bearing gate, because after it the run goes unattended. The posture is **hard gate with auto-remediation**:
|
|
68
68
|
|
|
69
|
-
1. **Mechanical check**: `preflight_check.py` parses tool versions, git state, and file existence and returns a `budget` count of mechanical blockers (test framework absent, dirty tree, on a protected branch, a repository with nothing committed yet, Claude Code below the minimum versions,
|
|
70
|
-
2. **Auto-remediation pass**: clear each remediable blocker, then re-run the check so `budget` reflects the fixes: create the Epic branch when the run started on a protected branch (it is a remediable, budget-counted blocker, so it has to clear here rather than at arming), scaffold the test framework (`bmad-testarch-framework`), scaffold the CI quality pipeline (`bmad-testarch-ci`, production only, strictly *after* the framework), generate missing acceptance criteria (`
|
|
69
|
+
1. **Mechanical check**: `preflight_check.py` parses tool versions, git state, and file existence and returns a `budget` count of mechanical blockers (test framework absent, dirty tree, on a protected branch, a repository with nothing committed yet, Claude Code below the minimum versions, UCG's story skills `ucg-create-story` and `ucg-dev-story` not installed, the TEA skills the run's profile delegates to not installed). It does **not** decide semantic intervention.
|
|
70
|
+
2. **Auto-remediation pass**: clear each remediable blocker, then re-run the check so `budget` reflects the fixes: create the Epic branch when the run started on a protected branch (it is a remediable, budget-counted blocker, so it has to clear here rather than at arming), scaffold the test framework (`bmad-testarch-framework`), scaffold the CI quality pipeline (`bmad-testarch-ci`, production only, strictly *after* the framework), generate missing acceptance criteria (`ucg-create-story`), pre-create the TEA output dirs, de-duplicate `project-context.md` when there is more than one (a missing one is logged, never generated), ensure `sprint-status.yaml` is present, force TEA **Create** mode, and prompt once (interactively) for any secrets.
|
|
71
71
|
3. **Semantic intervention scan**: the part the script cannot do: read the PRD and ADR for undecided product/architecture decisions, contradictions, acceptance criteria that presuppose an unmade decision, or a story whose "done" is undefinable. Any such item is **RED** and cannot be auto-remediated, because the fix is a human decision.
|
|
72
72
|
|
|
73
73
|
The run launches **only** when all hold: post-remediation `budget == 0`, the semantic scan found no RED, and ultracode session effort plus Auto Mode are on. Then the skill arms the environment: asserts the Epic branch off `epic_branch_prefix` (already created during remediation when the run started on a protected branch), merges the PreToolUse and Stop hooks into `.claude/settings.local.json` (asserting they are active, and injecting the resolved config into their env), and pre-populates the allowlist. On an attended run it prints the launch briefing and takes one soft confirm. See [`references/preflight.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/preflight.md).
|
|
74
74
|
|
|
75
75
|
### Stage 3: Define Done
|
|
76
76
|
|
|
77
|
-
Turn the Epic's acceptance criteria into **executable, red-phase acceptance tests** before any production code is written. Once per Epic, `bmad-testarch-test-design` (Epic-Level Mode) builds the risk-and-priority backbone: a risk matrix with scored, mitigated risks; P0-P3 priorities (the gate keys its thresholds to these); and NFR thresholds (unknowns are marked `UNKNOWN` and deferred, never guessed). Then, per in-scope story in sprint order: `
|
|
77
|
+
Turn the Epic's acceptance criteria into **executable, red-phase acceptance tests** before any production code is written. Once per Epic, `bmad-testarch-test-design` (Epic-Level Mode) builds the risk-and-priority backbone: a risk matrix with scored, mitigated risks; P0-P3 priorities (the gate keys its thresholds to these); and NFR thresholds (unknowns are marked `UNKNOWN` and deferred, never guessed). Then, per in-scope story in sprint order: `ucg-create-story` sharpens the acceptance criteria, and `bmad-testarch-atdd` generates an `atdd-checklist-{story_key}.md` plus acceptance test files **every test marked `test.skip()`** (TDD red phase). ATDD hard-halts if a story's ACs are vague or the framework is missing; that is the signal to loop back to `ucg-create-story` for that story. Stage 3 is done only when every in-scope story has a story file with clear ACs, and, **in the production profile**, a generated atdd-checklist with red-phase tests on disk. Under `--light` there is no ATDD step and no checklist by design, so an absent one is expected rather than a gap: the story's acceptance criteria are the trace oracle instead. The clear-ACs half of the bar holds in both profiles. See [`references/define-done.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/define-done.md).
|
|
78
78
|
|
|
79
79
|
### Stage 4: Execute
|
|
80
80
|
|
|
81
|
-
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `
|
|
81
|
+
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's evidence commit follows it) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
|
|
82
82
|
|
|
83
83
|
### Stage 5: Gate
|
|
84
84
|
|
package/docs/index.md
CHANGED
|
@@ -61,7 +61,7 @@ The docs split into three buckets: **Why** (start here), **Try** (do stuff), and
|
|
|
61
61
|
- [Architecture](./architecture.md): the conductor model, the enforcement layers in depth, and customization resolution.
|
|
62
62
|
- [Gate Model](./gate-model.md): how `gate_eval.py` maps `gate_status` to a verdict, the thresholds, and the fail-closed contract.
|
|
63
63
|
- [Health Check](./health-check.md): the terminal self-improvement reflection: what it sends, the privacy model, and how to disable it.
|
|
64
|
-
- [Cross-Session Recall](./cross-session-recall.md): the optional
|
|
64
|
+
- [Cross-Session Recall](./cross-session-recall.md): the optional run history in a local store, its trust model, and how to enable it.
|
|
65
65
|
- [Knowledge-Graph Refresh](./knowledge-graph-refresh.md): the optional graphify integration, its preconditions, and what it sends where.
|
|
66
66
|
- [Operating Tips](./operating-tips.md): field notes from real drives: the driver's stop reasons, why row order is the only sequencing mechanism, and the verification traps.
|
|
67
67
|
- [Troubleshooting](./troubleshooting.md): real failure modes and their remediations.
|
|
@@ -3,11 +3,11 @@ title: Knowledge-Graph Refresh
|
|
|
3
3
|
description: The optional graphify integration - UCG refreshes your project's knowledge graph as a run exits, so the next session starts from a current graph. Opt-in, advisory, never in the gate path, off by default.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **Optional, opt-in, off by default.** The refresh is one time-boxed call on the way out of a run. It
|
|
6
|
+
> **Optional, opt-in, off by default.** The refresh is one time-boxed call on the way out of a run. It writes `graphify-out/` in your project (or wherever `GRAPHIFY_OUT` points) and nothing else, because Finalize turns graphify's own housekeeping off for that call ([where it writes](#what-it-runs-and-where-it-writes) has the detail). It changes nothing in the run: not the gate verdict, not the recorded run-status, not the headless envelope. When it is off, or when the [graphify](https://github.com/Graphify-Labs/graphify) CLI or an existing graph is missing, the run is byte-for-byte the same as a run without it.
|
|
7
7
|
|
|
8
8
|
## What it does
|
|
9
9
|
|
|
10
|
-
A knowledge graph of your codebase goes stale the moment a run lands eight stories of new code and the documents that came with them, which is exactly what a UCG run produces. With `graphify_integration = "refresh"`, Stage 6 Finalize spends one incremental, local rebuild, so the next session starts from a current picture instead of a stale one. It refreshes what can be parsed and leaves what needs a model alone; [what it runs](#what-it-runs-and-where-it-writes) draws that line precisely.
|
|
10
|
+
A knowledge graph of your codebase goes stale the moment a run lands eight stories of new code and the documents that came with them, which is exactly what a UCG run produces. With `graphify_integration = "refresh"`, Stage 6 Finalize spends one incremental, local rebuild, so the next session starts from a current picture instead of a stale one. graphify rescans the project but re-parses only the files that changed since its cache last saw them. The cache is kept per graphify version, so the first refresh after an upgrade re-parses every file and is the one most likely to run past the time box. It refreshes what can be parsed and leaves what needs a model alone; [what it runs](#what-it-runs-and-where-it-writes) draws that line precisely.
|
|
11
11
|
|
|
12
12
|
Finalize is the only call site. No preflight step, no per-story step, and nothing in the gate path calls graphify or reads its output. See [how it works](./how-it-works.md) for where Stage 6 sits.
|
|
13
13
|
|
|
@@ -21,7 +21,7 @@ uv tool install graphifyy # or: pipx install graphifyy. The command is `graphi
|
|
|
21
21
|
|
|
22
22
|
> graphify is a third-party tool maintained independently of this module. We don't bundle, endorse, or install it; the refresh simply uses it when you already have it.
|
|
23
23
|
|
|
24
|
-
You also need a graph to refresh, since this step updates one and never builds one. Build it once yourself
|
|
24
|
+
You also need a graph to refresh, since this step updates one and never builds one. Build it once yourself. graphify's own route is `graphify install`, then `/graphify .` in your AI assistant, which runs the semantic pass on that assistant's model. From a shell, `graphify .` runs the same full pipeline and needs an LLM backend (an API key, a local Ollama or the `claude` CLI) once the project has documents, PDFs or images, while `graphify update .` builds the parsed layer alone, offline. After that first build, the run keeps the parsed layer current.
|
|
25
25
|
|
|
26
26
|
## Turning it on
|
|
27
27
|
|
|
@@ -30,37 +30,55 @@ Set the knob in your project's `_bmad/custom/ultracode-goal.toml`. **No installe
|
|
|
30
30
|
```toml
|
|
31
31
|
[workflow]
|
|
32
32
|
# Knowledge-graph refresh: one incremental rebuild as the run exits.
|
|
33
|
-
# Needs the graphify CLI and an existing graphify-out
|
|
33
|
+
# Needs the graphify CLI on PATH and an existing graphify-out/graph.json. Advisory, never gates.
|
|
34
34
|
graphify_integration = "refresh"
|
|
35
35
|
```
|
|
36
36
|
|
|
37
37
|
The `[workflow]` table header matters: the resolver extracts the `workflow` block from the merged files, so a bare top-level `graphify_integration` line is silently discarded and the feature stays off.
|
|
38
38
|
|
|
39
|
+
**To let the refresh run unattended**, allow its command. Without an allow rule, the command is left to Claude Code's permission check: under Auto Mode the classifier decides whether it runs, and in a mode that asks first, such as `drive_epic.py`'s default `acceptEdits`, nobody is there to answer. A refusal is logged as a `WARN graphify-refresh-failed` line like any other failure. Add the whole command to `allowlist_commands` under the same `[workflow]` header, not a second one: TOML refuses a table declared twice, and the resolver then rejects the whole file. Arrays append to the shipped list, and preflight writes each entry as an allow rule in `.claude/settings.local.json`. The whole file then reads:
|
|
40
|
+
|
|
41
|
+
```toml
|
|
42
|
+
[workflow]
|
|
43
|
+
graphify_integration = "refresh"
|
|
44
|
+
allowlist_commands = ["GRAPHIFY_NO_AUTO_REFRESH=1 timeout 300 graphify update ."]
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
An entry for the binary alone, `graphify`, does not cover it: Claude Code does not match an allow rule past a leading assignment of a variable it does not know, such as `GRAPHIFY_NO_AUTO_REFRESH=1`. If you added that entry for an earlier version, replace it. Replacing it leaves the allow rule an earlier preflight wrote for it, such as `Bash(graphify:*)`, in `.claude/settings.local.json`, because preflight only adds rules. Delete that rule yourself unless you want every graphify command, `graphify extract` included, to run without asking.
|
|
48
|
+
|
|
39
49
|
## Three things to know before you turn it on
|
|
40
50
|
|
|
41
|
-
- **The values are `off` and `refresh`, not `on` and `off`.** `cross_session_recall` sits
|
|
42
|
-
- **A first-ever enable does nothing, deliberately.** Two preconditions are both required: `graphify` resolves on `PATH`, and a `graphify-out/graph.json` already exists under the project root to update. Refresh means refresh:
|
|
43
|
-
- **Absence is silent, failure is logged.** When either precondition is missing, the run is byte-identical to an `off` run: no probe output, no decision-log line, nothing. When the pass
|
|
51
|
+
- **The values are `off` and `refresh`, not `on` and `off`.** `cross_session_recall` sits just above it in the shipped file and takes `on`, so copying that shape here produces `"on"`, which is not a legal value: only `refresh` turns the step on.
|
|
52
|
+
- **A first-ever enable does nothing, deliberately.** Two preconditions are both required: `graphify` resolves on `PATH`, and a `graphify-out/graph.json` already exists under the project root to update. Refresh means refresh: the step updates a graph you already have and never creates one, because whether your project gets a graph at all is your call, not an exit step's. Build the graph once yourself, and the run keeps its parsed layer current from then on. If `GRAPHIFY_OUT` is set, graphify reads and writes the graph there, but the probe still checks only `graphify-out/graph.json`. With no graph at `graphify-out/` the step stays silently off; with an old one still there, the refresh runs against the `GRAPHIFY_OUT` location and builds a graph there if it has none.
|
|
53
|
+
- **Absence is silent, failure is logged.** When either precondition is missing, the run is byte-identical to an `off` run: no probe output, no decision-log line, nothing. When the pass is attempted and ends in anything but a clean exit 0 (a non-zero exit, the 300 second time box running out, or a permission or sandbox denial of the command), Finalize logs one `WARN graphify-refresh-failed` line to `.decision-log.md` and moves on. It is never retried. If the permission layer refuses the probe itself, Finalize logs one `NOTE graphify-probe-unavailable` line instead and skips the step.
|
|
44
54
|
|
|
45
55
|
## What it runs, and where it writes
|
|
46
56
|
|
|
47
|
-
The delegation is exactly one command, `graphify update .`, time-boxed to 300 seconds and never retried.
|
|
57
|
+
The delegation is exactly one command, `GRAPHIFY_NO_AUTO_REFRESH=1 timeout 300 graphify update .`, time-boxed to 300 seconds and never retried. Its `update` subcommand re-extracts the graph's **parsed layer** against what is on disk, using graphify's local parsers (tree-sitter for most code, rule-based parsers for Markdown and package manifests): **no LLM call, no API key, no token spend** at the end of a run you were not watching, and **no network request** unless you have turned on graphify's Google Workspace export (`GRAPHIFY_GOOGLE_WORKSPACE=1`), which fetches each `.gdoc`, `.gsheet` or `.gslides` shortcut from Google Drive on every refresh.
|
|
48
58
|
|
|
49
|
-
The parsed layer
|
|
59
|
+
The parsed layer covers the files graphify has a local parser for: source code and the Markdown family (`.md`, `.mdx`, `.qmd`, `.skill`). Source code here includes shell scripts, `.sql` and `.tf` files, package manifests such as `pyproject.toml` and `go.mod`, and config JSON such as `package.json` and `tsconfig.json`; a data `.json` file, such as a fixture, gets no nodes. So an Epic's new modules and the story and documentation files it wrote are both picked up, with one exception: a Markdown file the last full build already gave LLM-derived nodes is not re-parsed, so an edit to it waits for the next semantic pass. What stays as the last full build left it is the **semantic** layer: images, PDFs and papers, documents graphify has no parser for (such as `.txt`, `.rst`, `.html` and `.yaml`), and anything an LLM derived from a document, except that a source deleted from disk or newly ignored loses its nodes. That pass is the one that sends your files to an LLM and spends tokens, which is exactly what an unattended exit step should not decide to do. Run it yourself, on your own terms, when you want it.
|
|
50
60
|
|
|
51
61
|
One behaviour worth knowing, because it is the opposite of what people expect:
|
|
52
62
|
|
|
53
63
|
- **Deleting code shrinks the graph, and nothing warns.** That is correct: the rebuild accounts for sources that are gone and writes the smaller graph, exit 0.
|
|
54
|
-
- **What graphify refuses is
|
|
64
|
+
- **What graphify refuses is a loss it cannot account for**, such as nodes vanishing from a file that is still on disk but could not be extracted this run (an unreadable file, for example), or LLM-derived nodes vanishing while their file is still there. Then graphify declines the write, exits non-zero, and you get a `WARN graphify-refresh-failed` line with the graph left intact. Whether to re-run `graphify update . --force` is a decision the run does not make for you.
|
|
65
|
+
- **Narrowing the scan is not refused.** When an Epic adds a `.graphifyignore` rule, or a `.gitignore` rule over files git does not track, graphify drops those files' nodes like a deletion, prints `pruned N node(s) from M newly-ignored file(s)` and exits 0. A `.gitignore` rule does not apply to files git already tracks, so those stay in the graph.
|
|
66
|
+
|
|
67
|
+
The output is a `graphify-out/` directory at your project root, not in the run folder, so it is not part of the run's evidence and nothing in the gate path reads it. It holds `graph.json`, `GRAPH_REPORT.md`, `graph.html`, `manifest.json`, a `cache/` and a few dotfiles, and a refresh that finds no change leaves the graph and the report as they were. Before a refresh rewrites the graph, graphify copies the old one into a dated folder such as `graphify-out/2026-10-20/`, one a day, if a shell `graphify .` built it with an LLM backend (graphify then leaves a `.graphify_semantic_marker`) or `.graphify_labels.json` holds community names, which a `/graphify .` build in your assistant saves. The hub names `update` fills in go to a separate file and do not count. Setting `GRAPHIFY_NO_BACKUP` turns the copy off. **Add `graphify-out/` to your `.gitignore`**: UCG commits each green story, and an untracked-but-not-ignored tree at the repo root is exactly what a story commit should never sweep up.
|
|
68
|
+
|
|
69
|
+
Before most commands, `update` included, graphify does some housekeeping outside `graphify-out/` (it skips it only for `install`, `uninstall` and the `hook-check` and `hook-guard` calls made by its editor hooks):
|
|
70
|
+
|
|
71
|
+
- On the first such command after you upgrade graphify, it re-copies any skill files `graphify install` put in your home directory, such as `~/.claude/skills/graphify/` for Claude Code, if their version stamp is older than the new package, and keeps the previous `SKILL.md` as `SKILL.md.bak` whenever it differs from the new one.
|
|
72
|
+
- On every such command, upgrade or not, it checks `.opencode/` in the project and in your home directory: it replaces a graphify OpenCode plugin written by graphify 0.9.74 or earlier once your OpenCode can load the current one, and drops graphify's stale plugin entry from `opencode.json`.
|
|
55
73
|
|
|
56
|
-
|
|
74
|
+
Each of these also leaves a lock file under `~/.cache/graphify/skill-locks/`. The `GRAPHIFY_NO_AUTO_REFRESH=1` at the start of Finalize's command turns all of it off for the refresh, so the refresh writes nothing outside `graphify-out/` (or wherever `GRAPHIFY_OUT` points): no skill, OpenCode or lock file in your home directory, and, in a project that commits `.opencode/`, no modified tracked file there after the last story commit. You don't need to set anything. The next graphify command you run yourself does the housekeeping as usual. Until you do, after a graphify upgrade the refresh prints graphify's warning that its installed skill is out of date, and Finalize does not act on it.
|
|
57
75
|
|
|
58
76
|
## What it never touches
|
|
59
77
|
|
|
60
78
|
The refresh is advisory in the same sense [Cross-Session Recall](./cross-session-recall.md) is, and the two are independent: either can be on without the other.
|
|
61
79
|
|
|
62
|
-
- The **gate verdict** is `gate_eval.py` reading TEA's
|
|
80
|
+
- The **gate verdict** is `gate_eval.py` reading TEA's gate artifacts, and nothing graphify writes is among them. See the [gate model](./gate-model.md).
|
|
63
81
|
- The **recorded run-status** and the **headless envelope** are identical whether the refresh ran, failed, or never fired.
|
|
64
82
|
- A graphify failure or timeout **never** blocks, re-loops, or escalates a story, and never changes a run's `complete` / `blocked` / `partial-complete` outcome.
|
|
65
83
|
|
|
66
|
-
Verified against graphify 0.9.
|
|
84
|
+
Verified against graphify 0.9.92 on 2026-10-20. It is a pre-1.0 tool whose CLI surface moves; if the install name, the command name, or the output layout above no longer match what you have, trust `graphify --help`.
|
package/docs/operating-tips.md
CHANGED
|
@@ -32,21 +32,13 @@ Two limits to respect. An hour covers roughly one story at the rate above, so pa
|
|
|
32
32
|
|
|
33
33
|
The tradeoff is real: a foreground drive blocks the agent for its whole duration. For a strict drive-then-verify loop that costs nothing, because there is nothing to do in between. If you want the agent working on something else while a story runs, background is still the right mechanism.
|
|
34
34
|
|
|
35
|
-
### The recall latch
|
|
35
|
+
### The recall latch between drives
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
Each spawn is its own run: its Stage 1 writes its own latch, `.mem-state.json`, and its Finalize removes it with `mem_recall.py unlatch` ([cross-session recall](./cross-session-recall.md) has the lifecycle). A resume writes the latch again, under a fresh run id of its own, by re-running Stage 1's latch step; it never inherits one. (The story's baseline marker is the opposite case, re-read and never regenerated. Do not carry the latch's rule across to it.)
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
Worth knowing before you chain drives: **observed across a multi-drive day, a spawned session's own latch call was permission-denied.** That spawn then runs with no latch, so the guard's recall rules (claude-mem denied, the store and the latch protected) are off for it. It says so: the decision log carries `NOTE recall-read-refused` at Stage 1, and the run report `NOTE recall-latch-missing` at Finalize. Check each spawn's report for those tokens rather than assume the latch was there.
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
uv run <skill-root>/scripts/mem_recall.py latch \
|
|
45
|
-
--impl-artifacts <impl-artifacts> --run-id <run-id> \
|
|
46
|
-
--recall off --claude-mem-absent
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
That writes a latch recording claude-mem as absent with recall off, which restores fail-closed gating. Use the `--recall on --probe <probe.json>` form when recall is meant to be live. Otherwise accept that spawns 2..N run with recall gating silently off.
|
|
41
|
+
Do not write a latch from the parent between drives. The old workaround, `latch --claude-mem-absent`, is gone, and a latch the parent writes counts as live only until the next spawn's Stage 1 replaces it. If no spawn replaces it, it keeps denying in your own session until you delete it by hand.
|
|
50
42
|
|
|
51
43
|
## Reading the driver's stop reasons
|
|
52
44
|
|