zam-core 0.6.3 → 0.7.1

package/.agent/skills/zam/SKILL.md

@@ -125,7 +125,11 @@ For **review/conceptual** sessions, use `--summary` to avoid spoiling answers:
 ```bash
 zam card due --user <username> --summary
 ```
-For **executable/task** sessions, the full listing is fine since the agent needs to plan.
+For **executable/task** sessions, the full listing is fine since the agent needs to plan. Also query ZAM for tokens relevant to the current task to weave them into the session:
+```bash
+echo '{"context":"<1-2 sentence description of the current task>"}' | zam bridge relevant-tokens --user <username>
+```
+If relevant tokens are returned, weave them into the planning session (e.g. "We will be working on task T; you already know X, which applies here").
 
 Classify session type:
 - **Executable** — real commands, code, or file edits (e.g. "set up Homebrew", "commit this change")
@@ -141,7 +145,13 @@ Decompose into a dependency-ordered list of knowledge tokens.
 ```bash
 zam token find --query "<keywords>"
 ```
-Only register genuinely new concepts. Reuse existing slugs where the concept matches.
+Only register genuinely new concepts. Reuse existing slugs where the concept matches. Note that `zam token find` matches paraphrases semantically.
+
+After deduplication and before registering a new token, check for existing semantically related tokens that could be prerequisites ("foundations"):
+```bash
+echo '{"concept":"<concept>","question":"<question>","domain":"<domain>"}' | zam bridge suggest-foundations
+```
+Present non-flagged suggestions to the user ("Related existing concept X — link it as a foundation?"); on approval link via the existing prereq path after registering.
 
 **Register tokens and prerequisites:**
 
@@ -367,6 +377,12 @@ A token should be decomposed when ALL of the following hold:
 After a rating of 1, pause. Do not just re-ask the same question or move on.
 Ask yourself: **"What would the user have needed to know to answer this?"**
 
+Always check for existing related foundation tokens first:
+```bash
+echo '{"slug":"<failed-token-slug>"}' | zam bridge suggest-foundations
+```
+Offer existing tokens returned as suggestions to the user first (linking them feeds the existing `confirmFoundations` path with `exists: true` and `slug`). Only generate NEW foundation proposals via the LLM for gaps that the suggestions do not cover.
+
 | Symptom | Missing foundation | Create Bloom 1-2 token for |
 |---------|-------------------|---------------------------|
 | Couldn't name key terms | Factual recall | Definitions, terminology |
@@ -486,7 +502,7 @@ stick → `ge-aufklaerung` reappears — this time with a fighting chance.
 - **Never create more than 10 new tokens in a single session** — if a rating of 1
   reveals massive gaps, prioritize the 3 most urgent foundations and let the rest
   emerge in subsequent sessions
-- **Always dedup before registering** — `zam token find --query "<keywords>"`
+- **Always dedup before registering** — `zam token find --query "<keywords>"`. Note that `zam token find` matches paraphrases semantically, and that `add-token` returns `possible_duplicates` which the agent must surface to the user.
 - **Do not split Bloom 1-2 tokens** — they are already atomic; if the user fails
   them, the fix is re-exposure and practice, not further decomposition
 - A rating of 1 on a Bloom 1 token means the user needs simpler wording or a

package/.agents/skills/zam/SKILL.md

@@ -156,7 +156,11 @@ For **review/conceptual** sessions, use `--summary` to avoid spoiling answers:
 ```bash
 zam card due --user <username> --summary
 ```
-For **executable/task** sessions, the full listing is fine since the agent needs to plan.
+For **executable/task** sessions, the full listing is fine since the agent needs to plan. Also query ZAM for tokens relevant to the current task to weave them into the session:
+```bash
+echo '{"context":"<1-2 sentence description of the current task>"}' | zam bridge relevant-tokens --user <username>
+```
+If relevant tokens are returned, weave them into the planning session (e.g. "We will be working on task T; you already know X, which applies here").
 
 Classify session type:
 - **Executable** — real commands, code, or file edits (e.g. "set up Homebrew", "commit this change")
@@ -172,7 +176,13 @@ Decompose into a dependency-ordered list of knowledge tokens.
 ```bash
 zam token find --query "<keywords>"
 ```
-Only register genuinely new concepts. Reuse existing slugs where the concept matches.
+Only register genuinely new concepts. Reuse existing slugs where the concept matches. Note that `zam token find` matches paraphrases semantically.
+
+After deduplication and before registering a new token, check for existing semantically related tokens that could be prerequisites ("foundations"):
+```bash
+echo '{"concept":"<concept>","question":"<question>","domain":"<domain>"}' | zam bridge suggest-foundations
+```
+Present non-flagged suggestions to the user ("Related existing concept X — link it as a foundation?"); on approval link via the existing prereq path after registering.
 
 **Register tokens and prerequisites:**
 
@@ -463,6 +473,12 @@ A token should be decomposed when ALL of the following hold:
 After a rating of 1, pause. Do not just re-ask the same question or move on.
 Ask yourself: **"What would the user have needed to know to answer this?"**
 
+Always check for existing related foundation tokens first:
+```bash
+echo '{"slug":"<failed-token-slug>"}' | zam bridge suggest-foundations
+```
+Offer existing tokens returned as suggestions to the user first (linking them feeds the existing `confirmFoundations` path with `exists: true` and `slug`). Only generate NEW foundation proposals via the LLM for gaps that the suggestions do not cover.
+
 | Symptom | Missing foundation | Create Bloom 1-2 token for |
 |---------|-------------------|---------------------------|
 | Couldn't name key terms | Factual recall | Definitions, terminology |
@@ -582,7 +598,7 @@ stick → `ge-aufklaerung` reappears — this time with a fighting chance.
 - **Never create more than 10 new tokens in a single session** — if a rating of 1
   reveals massive gaps, prioritize the 3 most urgent foundations and let the rest
   emerge in subsequent sessions
-- **Always dedup before registering** — `zam token find --query "<keywords>"`
+- **Always dedup before registering** — `zam token find --query "<keywords>"`. Note that `zam token find` matches paraphrases semantically, and that `add-token` returns `possible_duplicates` which the agent must surface to the user.
 - **Do not split Bloom 1-2 tokens** — they are already atomic; if the user fails
   them, the fix is re-exposure and practice, not further decomposition
 - A rating of 1 on a Bloom 1 token means the user needs simpler wording or a

package/.claude/skills/zam/SKILL.md

@@ -125,7 +125,11 @@ For **review/conceptual** sessions, use `--summary` to avoid spoiling answers:
 ```bash
 zam card due --user <username> --summary
 ```
-For **executable/task** sessions, the full listing is fine since the agent needs to plan.
+For **executable/task** sessions, the full listing is fine since the agent needs to plan. Also query ZAM for tokens relevant to the current task to weave them into the session:
+```bash
+echo '{"context":"<1-2 sentence description of the current task>"}' | zam bridge relevant-tokens --user <username>
+```
+If relevant tokens are returned, weave them into the planning session (e.g. "We will be working on task T; you already know X, which applies here").
 
 Classify session type:
 - **Executable** — real commands, code, or file edits (e.g. "set up Homebrew", "commit this change")
@@ -141,7 +145,13 @@ Decompose into a dependency-ordered list of knowledge tokens.
 ```bash
 zam token find --query "<keywords>"
 ```
-Only register genuinely new concepts. Reuse existing slugs where the concept matches.
+Only register genuinely new concepts. Reuse existing slugs where the concept matches. Note that `zam token find` matches paraphrases semantically.
+
+After deduplication and before registering a new token, check for existing semantically related tokens that could be prerequisites ("foundations"):
+```bash
+echo '{"concept":"<concept>","question":"<question>","domain":"<domain>"}' | zam bridge suggest-foundations
+```
+Present non-flagged suggestions to the user ("Related existing concept X — link it as a foundation?"); on approval link via the existing prereq path after registering.
 
 **Register tokens and prerequisites:**
 
@@ -367,6 +377,12 @@ A token should be decomposed when ALL of the following hold:
 After a rating of 1, pause. Do not just re-ask the same question or move on.
 Ask yourself: **"What would the user have needed to know to answer this?"**
 
+Always check for existing related foundation tokens first:
+```bash
+echo '{"slug":"<failed-token-slug>"}' | zam bridge suggest-foundations
+```
+Offer existing tokens returned as suggestions to the user first (linking them feeds the existing `confirmFoundations` path with `exists: true` and `slug`). Only generate NEW foundation proposals via the LLM for gaps that the suggestions do not cover.
+
 | Symptom | Missing foundation | Create Bloom 1-2 token for |
 |---------|-------------------|---------------------------|
 | Couldn't name key terms | Factual recall | Definitions, terminology |
@@ -486,7 +502,7 @@ stick → `ge-aufklaerung` reappears — this time with a fighting chance.
 - **Never create more than 10 new tokens in a single session** — if a rating of 1
   reveals massive gaps, prioritize the 3 most urgent foundations and let the rest
   emerge in subsequent sessions
-- **Always dedup before registering** — `zam token find --query "<keywords>"`
+- **Always dedup before registering** — `zam token find --query "<keywords>"`. Note that `zam token find` matches paraphrases semantically, and that `add-token` returns `possible_duplicates` which the agent must surface to the user.
 - **Do not split Bloom 1-2 tokens** — they are already atomic; if the user fails
   them, the fix is re-exposure and practice, not further decomposition
 - A rating of 1 on a Bloom 1 token means the user needs simpler wording or a