Skip to content

Commit cbdb918

Browse files
clark-mackeyclark-mackey
committed
release: sync product/ from development
Stories 8.6-8.11 (session handoff, token self-assessment, verbosity, cross-refs, staleness detection, archival summaries). Epic 10 multi-agent guard clause in SESSION END. Updated templates (DEVLOG, CHANGELOG). Selective merge: product/ only, no project/ or logs/.
1 parent da984b3 commit cbdb918

File tree

6 files changed

+383
-24
lines changed

6 files changed

+383
-24
lines changed

‎product/ai-rules/augment/log-file-maintenance.md‎

Lines changed: 89 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,92 @@ This rule is ALWAYS active. Violations require immediate self-correction.
7878
## 🔄 SESSION START
7979

8080
**At start of EVERY session:**
81-
1. Read `logs/DEVLOG.md` → "Current Context" section
82-
2. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
81+
1. Read `logs/DEVLOG.md` → "Last Session" section (if exists) for handoff context
82+
2. Read `logs/DEVLOG.md` → "Current Context" section
83+
3. **Staleness check:** If `Last Updated` date is >7 days old, update Current Context BEFORE other work
84+
- Tell user: "Current Context is X days old. Updating before proceeding."
85+
- Update: version, phase, objectives, recent changes
86+
- Set new `Last Updated` date
87+
4. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
88+
89+
---
90+
91+
## 🔚 SESSION END
92+
93+
**⚠️ Multi-agent:** If you are a subagent or teammate (not the lead/primary agent), skip this section. Only the primary agent writes session handoffs.
94+
95+
**Before ending a session, write a handoff note:**
96+
97+
1. Update `logs/DEVLOG.md` → "Last Session" section (overwrite previous)
98+
2. Format (3 bullets max, <150 tokens):
99+
```
100+
## Last Session
101+
- **Done:** [What was completed this session]
102+
- **In Progress:** [What's partially done, current state]
103+
- **Next:** [What the next session should start with]
104+
- **Branch:** `branch-name` | **Last Commit:** `hash`
105+
```
106+
3. Stage and commit with other changes (or amend last commit)
107+
108+
---
109+
110+
## 📊 TOKEN SELF-ASSESSMENT
111+
112+
**Heuristic:** ~4 characters = 1 token. Use this to self-regulate without running scripts.
113+
114+
**Quick reference:**
115+
- 1 line (~80 chars) ≈ 20 tokens
116+
- 1 paragraph (~320 chars) ≈ 80 tokens
117+
- 1 CHANGELOG entry ≈ 60-80 tokens
118+
- 1 DEVLOG compact entry ≈ 50-80 tokens
119+
- 1 DEVLOG standard entry ≈ 150-250 tokens
120+
121+
**Budgets:**
122+
- CHANGELOG: <10,000 tokens
123+
- DEVLOG: <15,000 tokens
124+
- Combined: <25,000 tokens
125+
126+
**Before writing:** Estimate entry size. If file is near budget, archive oldest entries first.
127+
128+
---
129+
130+
## ✏️ ENTRY VERBOSITY
131+
132+
**Two DEVLOG entry formats:**
133+
134+
**Compact format** (default for routine work, ~50-80 tokens):
135+
```
136+
### YYYY-MM-DD: Title
137+
Why/what in 1-2 sentences. Context or rationale.
138+
Files: `file1.py`, `file2.py`
139+
```
140+
141+
**Standard format** (for major decisions, incidents, milestones, ~150-250 tokens):
142+
```
143+
### YYYY-MM-DD: Title
144+
**The Situation:** ...
145+
**The Decision:** ...
146+
**Why This Matters:** ...
147+
**Files Changed:** ...
148+
```
149+
150+
**Decision guide:** If it needs an ADR → use standard. Otherwise → compact.
151+
152+
---
153+
154+
## 🔗 CROSS-REFERENCES
155+
156+
**When writing entries that relate across files, add navigation hints:**
157+
158+
- CHANGELOG entry with a DEVLOG decision: append `→ DEVLOG YYYY-MM-DD`
159+
- DEVLOG entry referencing a specific version: append `→ CHANGELOG vX.Y.Z`
160+
161+
**Example:**
162+
```
163+
- Fixed token refresh bug. Files: `src/auth.js`. Commit: `abc123` → DEVLOG 2026-02-06
164+
```
165+
166+
Hints are optional - only add when a cross-reference exists.
83167

84168
---
85169

@@ -89,7 +173,9 @@ This rule is ALWAYS active. Violations require immediate self-correction.
89173

90174
**Action:** Archive OLDEST entries first until under budget
91175
1. Move oldest entries to `logs/archive/[FILENAME]-YYYY-MM.md`
92-
2. Re-run validation to confirm
176+
2. Add summary line to the Archive section of the source file:
177+
`- [FILENAME-YYYY-MM.md](archive/FILENAME-YYYY-MM.md) - Brief description of contents`
178+
3. Re-run validation to confirm
93179

94180
**Key:** Archive by TOKEN COUNT, not date. Recent entries may need archiving if over budget.
95181

‎product/ai-rules/claude-code/log-file-maintenance.md‎

Lines changed: 89 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,92 @@ This rule is ALWAYS active. Violations require immediate self-correction.
7878
## 🔄 SESSION START
7979

8080
**At start of EVERY session:**
81-
1. Read `logs/DEVLOG.md` → "Current Context" section
82-
2. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
81+
1. Read `logs/DEVLOG.md` → "Last Session" section (if exists) for handoff context
82+
2. Read `logs/DEVLOG.md` → "Current Context" section
83+
3. **Staleness check:** If `Last Updated` date is >7 days old, update Current Context BEFORE other work
84+
- Tell user: "Current Context is X days old. Updating before proceeding."
85+
- Update: version, phase, objectives, recent changes
86+
- Set new `Last Updated` date
87+
4. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
88+
89+
---
90+
91+
## 🔚 SESSION END
92+
93+
**⚠️ Multi-agent:** If you are a subagent or teammate (not the lead/primary agent), skip this section. Only the primary agent writes session handoffs.
94+
95+
**Before ending a session, write a handoff note:**
96+
97+
1. Update `logs/DEVLOG.md` → "Last Session" section (overwrite previous)
98+
2. Format (3 bullets max, <150 tokens):
99+
```
100+
## Last Session
101+
- **Done:** [What was completed this session]
102+
- **In Progress:** [What's partially done, current state]
103+
- **Next:** [What the next session should start with]
104+
- **Branch:** `branch-name` | **Last Commit:** `hash`
105+
```
106+
3. Stage and commit with other changes (or amend last commit)
107+
108+
---
109+
110+
## 📊 TOKEN SELF-ASSESSMENT
111+
112+
**Heuristic:** ~4 characters = 1 token. Use this to self-regulate without running scripts.
113+
114+
**Quick reference:**
115+
- 1 line (~80 chars) ≈ 20 tokens
116+
- 1 paragraph (~320 chars) ≈ 80 tokens
117+
- 1 CHANGELOG entry ≈ 60-80 tokens
118+
- 1 DEVLOG compact entry ≈ 50-80 tokens
119+
- 1 DEVLOG standard entry ≈ 150-250 tokens
120+
121+
**Budgets:**
122+
- CHANGELOG: <10,000 tokens
123+
- DEVLOG: <15,000 tokens
124+
- Combined: <25,000 tokens
125+
126+
**Before writing:** Estimate entry size. If file is near budget, archive oldest entries first.
127+
128+
---
129+
130+
## ✏️ ENTRY VERBOSITY
131+
132+
**Two DEVLOG entry formats:**
133+
134+
**Compact format** (default for routine work, ~50-80 tokens):
135+
```
136+
### YYYY-MM-DD: Title
137+
Why/what in 1-2 sentences. Context or rationale.
138+
Files: `file1.py`, `file2.py`
139+
```
140+
141+
**Standard format** (for major decisions, incidents, milestones, ~150-250 tokens):
142+
```
143+
### YYYY-MM-DD: Title
144+
**The Situation:** ...
145+
**The Decision:** ...
146+
**Why This Matters:** ...
147+
**Files Changed:** ...
148+
```
149+
150+
**Decision guide:** If it needs an ADR → use standard. Otherwise → compact.
151+
152+
---
153+
154+
## 🔗 CROSS-REFERENCES
155+
156+
**When writing entries that relate across files, add navigation hints:**
157+
158+
- CHANGELOG entry with a DEVLOG decision: append `→ DEVLOG YYYY-MM-DD`
159+
- DEVLOG entry referencing a specific version: append `→ CHANGELOG vX.Y.Z`
160+
161+
**Example:**
162+
```
163+
- Fixed token refresh bug. Files: `src/auth.js`. Commit: `abc123` → DEVLOG 2026-02-06
164+
```
165+
166+
Hints are optional - only add when a cross-reference exists.
83167

84168
---
85169

@@ -89,7 +173,9 @@ This rule is ALWAYS active. Violations require immediate self-correction.
89173

90174
**Action:** Archive OLDEST entries first until under budget
91175
1. Move oldest entries to `logs/archive/[FILENAME]-YYYY-MM.md`
92-
2. Re-run validation to confirm
176+
2. Add summary line to the Archive section of the source file:
177+
`- [FILENAME-YYYY-MM.md](archive/FILENAME-YYYY-MM.md) - Brief description of contents`
178+
3. Re-run validation to confirm
93179

94180
**Key:** Archive by TOKEN COUNT, not date. Recent entries may need archiving if over budget.
95181

‎product/starter-packs/augment/.augment/rules/log-file-maintenance.md‎

Lines changed: 89 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,92 @@ This rule is ALWAYS active. Violations require immediate self-correction.
8181

8282
**At start of EVERY session:**
8383
1. Read `.logfile-config.yml` → `paths.devlog` to find DEVLOG
84-
2. Read DEVLOG → "Current Context" section
85-
3. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
84+
2. Read DEVLOG → "Last Session" section (if exists) for handoff context
85+
3. Read DEVLOG → "Current Context" section
86+
4. **Staleness check:** If `Last Updated` date is >7 days old, update Current Context BEFORE other work
87+
- Tell user: "Current Context is X days old. Updating before proceeding."
88+
- Update: version, phase, objectives, recent changes
89+
- Set new `Last Updated` date
90+
5. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
91+
92+
---
93+
94+
## 🔚 SESSION END
95+
96+
**⚠️ Multi-agent:** If you are a subagent or teammate (not the lead/primary agent), skip this section. Only the primary agent writes session handoffs.
97+
98+
**Before ending a session, write a handoff note:**
99+
100+
1. Update DEVLOG → "Last Session" section (overwrite previous)
101+
2. Format (3 bullets max, <150 tokens):
102+
```
103+
## Last Session
104+
- **Done:** [What was completed this session]
105+
- **In Progress:** [What's partially done, current state]
106+
- **Next:** [What the next session should start with]
107+
- **Branch:** `branch-name` | **Last Commit:** `hash`
108+
```
109+
3. Stage and commit with other changes (or amend last commit)
110+
111+
---
112+
113+
## 📊 TOKEN SELF-ASSESSMENT
114+
115+
**Heuristic:** ~4 characters = 1 token. Use this to self-regulate without running scripts.
116+
117+
**Quick reference:**
118+
- 1 line (~80 chars) ≈ 20 tokens
119+
- 1 paragraph (~320 chars) ≈ 80 tokens
120+
- 1 CHANGELOG entry ≈ 60-80 tokens
121+
- 1 DEVLOG compact entry ≈ 50-80 tokens
122+
- 1 DEVLOG standard entry ≈ 150-250 tokens
123+
124+
**Budgets:**
125+
- CHANGELOG: <10,000 tokens
126+
- DEVLOG: <15,000 tokens
127+
- Combined: <25,000 tokens
128+
129+
**Before writing:** Estimate entry size. If file is near budget, archive oldest entries first.
130+
131+
---
132+
133+
## ✏️ ENTRY VERBOSITY
134+
135+
**Two DEVLOG entry formats:**
136+
137+
**Compact format** (default for routine work, ~50-80 tokens):
138+
```
139+
### YYYY-MM-DD: Title
140+
Why/what in 1-2 sentences. Context or rationale.
141+
Files: `file1.py`, `file2.py`
142+
```
143+
144+
**Standard format** (for major decisions, incidents, milestones, ~150-250 tokens):
145+
```
146+
### YYYY-MM-DD: Title
147+
**The Situation:** ...
148+
**The Decision:** ...
149+
**Why This Matters:** ...
150+
**Files Changed:** ...
151+
```
152+
153+
**Decision guide:** If it needs an ADR → use standard. Otherwise → compact.
154+
155+
---
156+
157+
## 🔗 CROSS-REFERENCES
158+
159+
**When writing entries that relate across files, add navigation hints:**
160+
161+
- CHANGELOG entry with a DEVLOG decision: append `→ DEVLOG YYYY-MM-DD`
162+
- DEVLOG entry referencing a specific version: append `→ CHANGELOG vX.Y.Z`
163+
164+
**Example:**
165+
```
166+
- Fixed token refresh bug. Files: `src/auth.js`. Commit: `abc123` → DEVLOG 2026-02-06
167+
```
168+
169+
Hints are optional - only add when a cross-reference exists.
86170

87171
---
88172

@@ -92,7 +176,9 @@ This rule is ALWAYS active. Violations require immediate self-correction.
92176

93177
**Action:** Archive OLDEST entries first until under budget
94178
1. Move oldest entries to archive folder (see `.logfile-config.yml`)
95-
2. Re-run validation to confirm
179+
2. Add summary line to the Archive section of the source file:
180+
`- [FILENAME-YYYY-MM.md](archive/FILENAME-YYYY-MM.md) - Brief description of contents`
181+
3. Re-run validation to confirm
96182

97183
**Key:** Archive by TOKEN COUNT, not date. Recent entries may need archiving if over budget.
98184

0 commit comments

Comments
 (0)