@adamchanadam/agent-handoff-kit 0.3.41 → 0.3.43
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/LICENSE +21 -21
- package/README.en.md +81 -0
- package/README.md +38 -36
- package/bin/agent-handoff-kit.mjs +4664 -2544
- package/bin/installed-file-contract.mjs +74 -45
- package/bin/migration-baselines/official-origin-catalog.json +10039 -9828
- package/bin/official-origin-catalog.mjs +248 -192
- package/bin/prompt-mirror-core.mjs +84 -84
- package/bin/semantic-candidate.mjs +594 -0
- package/bin/upgrade-inventory.mjs +587 -0
- package/bin/user-rules-router.mjs +461 -0
- package/package.json +1 -13
- package/packs/agent-governance.md +103 -103
- package/packs/closeout.md +74 -72
- package/packs/coding.md +28 -28
- package/packs/communication.md +32 -30
- package/packs/integrations.md +251 -251
- package/packs/knowledge.md +5 -5
- package/packs/onboarding.md +214 -214
- package/packs/release.md +28 -28
- package/packs/research.md +30 -30
- package/packs/safety.md +29 -29
- package/packs/writing.md +36 -36
- package/runtime-core/AGENTS.core.md +115 -112
- package/runtime-core/CLAUDE.md +13 -13
- package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
- package/runtime-core/GEMINI.md +17 -17
- package/runtime-core/PROJECT_DECISIONS.md +43 -43
- package/runtime-core/PROJECT_INDEX.md +73 -73
- package/runtime-core/RULE_PACKS.md +14 -14
- package/runtime-core/SESSION_HANDOFF.md +42 -36
- package/runtime-core/SESSION_LOG.md +35 -35
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +5 -5
- package/runtime-core/USER_RULES.md +30 -0
- package/runtime-core/USER_RULES_ENTRY.md +7 -0
|
@@ -1,43 +1,43 @@
|
|
|
1
|
-
# Project Decisions Log
|
|
2
|
-
|
|
3
|
-
This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
|
|
4
|
-
|
|
5
|
-
Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
|
|
6
|
-
|
|
7
|
-
The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
|
|
8
|
-
|
|
9
|
-
Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
|
|
10
|
-
|
|
11
|
-
```text
|
|
12
|
-
- YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
|
|
16
|
-
|
|
17
|
-
This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
|
|
18
|
-
|
|
19
|
-
---
|
|
20
|
-
|
|
21
|
-
## Evolution Timeline
|
|
22
|
-
|
|
23
|
-
Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
|
|
24
|
-
|
|
25
|
-
(empty)
|
|
26
|
-
|
|
27
|
-
## Decisions Archive
|
|
28
|
-
|
|
29
|
-
Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
|
|
30
|
-
|
|
31
|
-
(empty)
|
|
32
|
-
|
|
33
|
-
## Architecture Choices
|
|
34
|
-
|
|
35
|
-
Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
|
|
36
|
-
|
|
37
|
-
(empty)
|
|
38
|
-
|
|
39
|
-
## Insights & Learnings
|
|
40
|
-
|
|
41
|
-
Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
|
|
42
|
-
|
|
43
|
-
(empty)
|
|
1
|
+
# Project Decisions Log
|
|
2
|
+
|
|
3
|
+
This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
|
|
4
|
+
|
|
5
|
+
Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
|
|
6
|
+
|
|
7
|
+
The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
|
|
8
|
+
|
|
9
|
+
Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
- YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
|
|
16
|
+
|
|
17
|
+
This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Evolution Timeline
|
|
22
|
+
|
|
23
|
+
Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
|
|
24
|
+
|
|
25
|
+
(empty)
|
|
26
|
+
|
|
27
|
+
## Decisions Archive
|
|
28
|
+
|
|
29
|
+
Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
|
|
30
|
+
|
|
31
|
+
(empty)
|
|
32
|
+
|
|
33
|
+
## Architecture Choices
|
|
34
|
+
|
|
35
|
+
Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
|
|
36
|
+
|
|
37
|
+
(empty)
|
|
38
|
+
|
|
39
|
+
## Insights & Learnings
|
|
40
|
+
|
|
41
|
+
Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
|
|
42
|
+
|
|
43
|
+
(empty)
|
|
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
6
6
|
|
|
7
7
|
| Field | Value | Last verified |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
| Agent Handoff Kit template version | 0.3.
|
|
9
|
+
| Agent Handoff Kit template version | 0.3.43 | current template version |
|
|
10
10
|
| Runtime | TBD | TBD |
|
|
11
11
|
| Framework | TBD | TBD |
|
|
12
12
|
| Package manager | TBD | TBD |
|
|
@@ -20,13 +20,13 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
20
20
|
|---|---|---|
|
|
21
21
|
| `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
|
|
22
22
|
| `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
|
|
23
|
-
| `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |
|
|
24
|
-
| `START_NEXT_SESSION_PROMPT.txt` | portable generated mirror of the handoff opening-message block; `dev/SESSION_HANDOFF.md` remains authoritative | fallback when the next agent is not yet operating in this root; not an additional local startup read |
|
|
23
|
+
| `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |
|
|
24
|
+
| `START_NEXT_SESSION_PROMPT.txt` | portable generated mirror of the handoff opening-message block; `dev/SESSION_HANDOFF.md` remains authoritative | fallback when the next agent is not yet operating in this root; not an additional local startup read |
|
|
25
25
|
| `src/` | application source | coding task |
|
|
26
26
|
| `tests/` | tests | coding/QC |
|
|
27
27
|
| `docs/` | user or product docs | doc/public behavior change |
|
|
28
|
-
| `dev/` | governance state | read the handoff at startup; other files are task-routed or closeout-routed |
|
|
29
|
-
| `dev/rules/closeout.md` | full closeout contract | clear end-of-session or handoff intent only |
|
|
28
|
+
| `dev/` | governance state | read the handoff at startup; other files are task-routed or closeout-routed |
|
|
29
|
+
| `dev/rules/closeout.md` | full closeout contract | clear end-of-session or handoff intent only |
|
|
30
30
|
| `TBD` | local source-of-truth files | before tasks that depend on project facts |
|
|
31
31
|
| `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
|
|
32
32
|
|
|
@@ -36,10 +36,10 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
36
36
|
|---|---|---|
|
|
37
37
|
| App entry | TBD | TBD |
|
|
38
38
|
| Main config | TBD | TBD |
|
|
39
|
-
| Test suite | TBD | TBD |
|
|
40
|
-
| Runbook | TBD | TBD |
|
|
41
|
-
| Public docs | TBD | TBD |
|
|
42
|
-
| Generated Markdown review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated Markdown outputs, specs, runbooks, checklists, or research notes, classify each file as indexed / synced / temporary / one-time evidence before completion; other durable formats require human review because doctor scans Markdown only |
|
|
39
|
+
| Test suite | TBD | TBD |
|
|
40
|
+
| Runbook | TBD | TBD |
|
|
41
|
+
| Public docs | TBD | TBD |
|
|
42
|
+
| Generated Markdown review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated Markdown outputs, specs, runbooks, checklists, or research notes, classify each file as indexed / synced / temporary / one-time evidence before completion; other durable formats require human review because doctor scans Markdown only |
|
|
43
43
|
|
|
44
44
|
## Fact Base
|
|
45
45
|
|
|
@@ -53,68 +53,68 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
53
53
|
|
|
54
54
|
| Source | Role | Required before | Access method | `via` | Write-back rule | Last verified |
|
|
55
55
|
|---|---|---|---|---|---|---|
|
|
56
|
-
| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Google Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
|
|
56
|
+
| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Google Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
|
|
57
57
|
|
|
58
|
-
> `via` column discipline: every External Sources row must reference an entry name under `## Installed Integrations`, such as `Notion Connector` or `Google Drive Connector`, so the access path is explicit. Sources without a declared integration use `manual paste`. Doctor and release QA enforce cross-section consistency.
|
|
58
|
+
> `via` column discipline: every External Sources row must reference an entry name under `## Installed Integrations`, such as `Notion Connector` or `Google Drive Connector`, so the access path is explicit. Sources without a declared integration use `manual paste`. Doctor and release QA enforce cross-section consistency.
|
|
59
59
|
|
|
60
60
|
## Installed Integrations
|
|
61
61
|
|
|
62
|
-
> **Credential Separation Principle**: this section records only project usage and public reference coordinates such as Notion database names, URLs, or folder paths. It must never record API keys, OAuth tokens, or credential values. Credentials belong in AI runtime secure storage, OS credential stores, tool configuration, or user-managed secret stores. If an environment variable is used, record only the variable name, never the value. Before writing this section, self-check that no credential value is being persisted. Doctor scans this section, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes such as `sk-`, `ntn_`, `ya29.`, `xoxp-`, `ghp_`, `sl.`, `AKIA`, and `AIza`.
|
|
63
|
-
|
|
64
|
-
> Purpose: tasks that use external tools read this section to understand declared capabilities and project roles. Declarations persist across sessions. A new session does not probe this table merely because it exists. `TBD`, examples, blanks, and placeholder-only rows are not installed integrations. Every real entry includes `Declared` and `Last Verified` so capability assumptions can be checked immediately before use.
|
|
65
|
-
|
|
66
|
-
### Connectors
|
|
67
|
-
|
|
68
|
-
| Tool | Project Usage | Access Scope | Specific Instance | Credential Reference (no value) | Declared | Last Verified |
|
|
69
|
-
|------|---------------|--------------|-------------------|---------------------|----------|---------------|
|
|
70
|
-
| TBD | TBD, for example an index of source paths or persistent reference storage | read / read+write | TBD, for example database name + URL or folder path | TBD, for example `AI tool secure storage` / `OS credential store` | TBD | TBD |
|
|
71
|
-
|
|
72
|
-
### MCPs
|
|
73
|
-
|
|
74
|
-
| Server | Source | Project Usage | Credential Reference (no value) | Declared | Last Verified |
|
|
75
|
-
|--------|--------|---------------|---------------------|----------|---------------|
|
|
76
|
-
| TBD | TBD, for example GitHub repository URL | TBD | TBD, for example `tool config + env var name only` / `user-managed secret store` | TBD | TBD |
|
|
77
|
-
|
|
78
|
-
### Plugins
|
|
79
|
-
|
|
80
|
-
| Name | Bundle Content (Skills + MCP + hooks) | When Triggered | Last Verified |
|
|
81
|
-
|------|----------------------------------------|----------------|---------------|
|
|
82
|
-
| TBD | TBD | TBD | TBD |
|
|
83
|
-
|
|
84
|
-
### Skills
|
|
85
|
-
|
|
86
|
-
| Name | Source | When Triggered | Last Verified |
|
|
87
|
-
|------|--------|----------------|---------------|
|
|
88
|
-
| TBD | TBD, for example plugin bundle or user-level install | TBD | TBD |
|
|
89
|
-
|
|
90
|
-
### Source-of-truth Architecture
|
|
91
|
-
|
|
92
|
-
> When a project uses several integrations as a source-of-truth system, for example Notion index + local primary sources + Google Drive reference mirror, this table records each layer's role so agents do not cross write boundaries.
|
|
93
|
-
|
|
94
|
-
| Layer | Surface (specific instance) | Role | Write Direction |
|
|
95
|
-
|-------|--------------------------|------|-----------------|
|
|
96
|
-
| Source of truth | TBD, for example local `~/project/reference/` | Original auditable reference content | User-controlled placement; agent does not write directly unless explicitly authorized |
|
|
97
|
-
| Index | TBD, for example Notion database `Project Index` | Metadata, summaries, and tags for each source file | Agent may read/write through a verified Connector |
|
|
98
|
-
| Persistent mirror | TBD, for example Drive folder `Project Reference/` | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically |
|
|
99
|
-
| Working draft | TBD, for example local `~/project/output/` | Agent task output | Agent may read and write local files under normal safety rules |
|
|
100
|
-
|
|
101
|
-
## Tool Operation References
|
|
102
|
-
|
|
103
|
-
Use this section for project-local runbooks or verified procedures for runtime-controlled tools such as browser validation, screenshots, DevTools, Playwright, crawlers, notebooks, desktop app automation, MCP/plugin helpers, or raw CLI/SDK operations.
|
|
104
|
-
|
|
105
|
-
Do not store credential values or machine-private paths here. Local machine-only references may be listed only when the project explicitly depends on them, and the scope / limits must say they are not portable.
|
|
106
|
-
|
|
107
|
-
| Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |
|
|
108
|
-
|---|---|---|---|---|---|
|
|
109
|
-
| TBD | TBD | TBD | TBD | TBD | TBD |
|
|
110
|
-
| Local HTML / app browser validation | TBD, for example project runbook or official browser-tool docs | Before validating local HTML, static app, generated guide, screenshot, click flow, or visual QA | TBD, include source and date | Prefer short-lived loopback localhost service when `file://` is blocked; record click/text/screenshot evidence and cleanup result; do not mutate user browser profiles or extension state | TBD |
|
|
111
|
-
|
|
112
|
-
## Local QC Commands
|
|
113
|
-
|
|
114
|
-
| Check | Command | Run before | Last verified |
|
|
115
|
-
|---|---|---|---|
|
|
116
|
-
| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
|
|
117
|
-
| Project governance check | Check newly created Markdown against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. Review non-Markdown durable outputs manually. | closeout / durable file changes | unverified until project-specific command exists |
|
|
62
|
+
> **Credential Separation Principle**: this section records only project usage and public reference coordinates such as Notion database names, URLs, or folder paths. It must never record API keys, OAuth tokens, or credential values. Credentials belong in AI runtime secure storage, OS credential stores, tool configuration, or user-managed secret stores. If an environment variable is used, record only the variable name, never the value. Before writing this section, self-check that no credential value is being persisted. Doctor scans this section, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes such as `sk-`, `ntn_`, `ya29.`, `xoxp-`, `ghp_`, `sl.`, `AKIA`, and `AIza`.
|
|
63
|
+
|
|
64
|
+
> Purpose: tasks that use external tools read this section to understand declared capabilities and project roles. Declarations persist across sessions. A new session does not probe this table merely because it exists. `TBD`, examples, blanks, and placeholder-only rows are not installed integrations. Every real entry includes `Declared` and `Last Verified` so capability assumptions can be checked immediately before use.
|
|
65
|
+
|
|
66
|
+
### Connectors
|
|
67
|
+
|
|
68
|
+
| Tool | Project Usage | Access Scope | Specific Instance | Credential Reference (no value) | Declared | Last Verified |
|
|
69
|
+
|------|---------------|--------------|-------------------|---------------------|----------|---------------|
|
|
70
|
+
| TBD | TBD, for example an index of source paths or persistent reference storage | read / read+write | TBD, for example database name + URL or folder path | TBD, for example `AI tool secure storage` / `OS credential store` | TBD | TBD |
|
|
71
|
+
|
|
72
|
+
### MCPs
|
|
73
|
+
|
|
74
|
+
| Server | Source | Project Usage | Credential Reference (no value) | Declared | Last Verified |
|
|
75
|
+
|--------|--------|---------------|---------------------|----------|---------------|
|
|
76
|
+
| TBD | TBD, for example GitHub repository URL | TBD | TBD, for example `tool config + env var name only` / `user-managed secret store` | TBD | TBD |
|
|
77
|
+
|
|
78
|
+
### Plugins
|
|
79
|
+
|
|
80
|
+
| Name | Bundle Content (Skills + MCP + hooks) | When Triggered | Last Verified |
|
|
81
|
+
|------|----------------------------------------|----------------|---------------|
|
|
82
|
+
| TBD | TBD | TBD | TBD |
|
|
83
|
+
|
|
84
|
+
### Skills
|
|
85
|
+
|
|
86
|
+
| Name | Source | When Triggered | Last Verified |
|
|
87
|
+
|------|--------|----------------|---------------|
|
|
88
|
+
| TBD | TBD, for example plugin bundle or user-level install | TBD | TBD |
|
|
89
|
+
|
|
90
|
+
### Source-of-truth Architecture
|
|
91
|
+
|
|
92
|
+
> When a project uses several integrations as a source-of-truth system, for example Notion index + local primary sources + Google Drive reference mirror, this table records each layer's role so agents do not cross write boundaries.
|
|
93
|
+
|
|
94
|
+
| Layer | Surface (specific instance) | Role | Write Direction |
|
|
95
|
+
|-------|--------------------------|------|-----------------|
|
|
96
|
+
| Source of truth | TBD, for example local `~/project/reference/` | Original auditable reference content | User-controlled placement; agent does not write directly unless explicitly authorized |
|
|
97
|
+
| Index | TBD, for example Notion database `Project Index` | Metadata, summaries, and tags for each source file | Agent may read/write through a verified Connector |
|
|
98
|
+
| Persistent mirror | TBD, for example Drive folder `Project Reference/` | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically |
|
|
99
|
+
| Working draft | TBD, for example local `~/project/output/` | Agent task output | Agent may read and write local files under normal safety rules |
|
|
100
|
+
|
|
101
|
+
## Tool Operation References
|
|
102
|
+
|
|
103
|
+
Use this section for project-local runbooks or verified procedures for runtime-controlled tools such as browser validation, screenshots, DevTools, Playwright, crawlers, notebooks, desktop app automation, MCP/plugin helpers, or raw CLI/SDK operations.
|
|
104
|
+
|
|
105
|
+
Do not store credential values or machine-private paths here. Local machine-only references may be listed only when the project explicitly depends on them, and the scope / limits must say they are not portable.
|
|
106
|
+
|
|
107
|
+
| Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |
|
|
108
|
+
|---|---|---|---|---|---|
|
|
109
|
+
| TBD | TBD | TBD | TBD | TBD | TBD |
|
|
110
|
+
| Local HTML / app browser validation | TBD, for example project runbook or official browser-tool docs | Before validating local HTML, static app, generated guide, screenshot, click flow, or visual QA | TBD, include source and date | Prefer short-lived loopback localhost service when `file://` is blocked; record click/text/screenshot evidence and cleanup result; do not mutate user browser profiles or extension state | TBD |
|
|
111
|
+
|
|
112
|
+
## Local QC Commands
|
|
113
|
+
|
|
114
|
+
| Check | Command | Run before | Last verified |
|
|
115
|
+
|---|---|---|---|
|
|
116
|
+
| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
|
|
117
|
+
| Project governance check | Check newly created Markdown against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. Review non-Markdown durable outputs manually. | closeout / durable file changes | unverified until project-specific command exists |
|
|
118
118
|
|
|
119
119
|
## Workspace Identity
|
|
120
120
|
|
|
@@ -135,9 +135,9 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
|
135
135
|
| API behavior | TBD | tests + docs sync |
|
|
136
136
|
| UI behavior | TBD | build + visual/manual check |
|
|
137
137
|
| Data model | TBD | migration/checks |
|
|
138
|
-
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
139
|
-
| Generated Markdown | `docs/`, `outputs/`, root Markdown files, project-specific reference folders | classify as indexed / synced / temporary / one-time evidence; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable; review other formats manually |
|
|
140
|
-
| Closeout/startup contract | `AGENTS.md`, `dev/rules/closeout.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | hot-path reads stay minimal; lifecycle state agrees; log has no full prompt; prompt mirror regenerated from handoff at closeout |
|
|
138
|
+
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
139
|
+
| Generated Markdown | `docs/`, `outputs/`, root Markdown files, project-specific reference folders | classify as indexed / synced / temporary / one-time evidence; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable; review other formats manually |
|
|
140
|
+
| Closeout/startup contract | `AGENTS.md`, `dev/rules/closeout.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | hot-path reads stay minimal; lifecycle state agrees; log has no full prompt; prompt mirror regenerated from handoff at closeout |
|
|
141
141
|
|
|
142
142
|
## External Services
|
|
143
143
|
|
|
@@ -145,6 +145,6 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
|
145
145
|
|---|---|---|---|
|
|
146
146
|
| TBD | TBD | TBD | TBD |
|
|
147
147
|
|
|
148
|
-
## Maintenance Rule
|
|
149
|
-
|
|
150
|
-
Update this file when stack, commands, directory roles, entry points, external services, runtime-controlled tool operation references, workspace identity, durable runbooks, or governance file map changes.
|
|
148
|
+
## Maintenance Rule
|
|
149
|
+
|
|
150
|
+
Update this file when stack, commands, directory roles, entry points, external services, runtime-controlled tool operation references, workspace identity, durable runbooks, or governance file map changes.
|
|
@@ -2,24 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|
Read only the packs needed for the current task.
|
|
4
4
|
|
|
5
|
-
| Task signal | Pack | Purpose |
|
|
6
|
-
|---|---|---|
|
|
7
|
-
| Clear end-of-session or handoff intent: "收工" / "wrap up" / "closeout" / "handoff" / "Wrap up Agent Handoff", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |
|
|
8
|
-
| Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install or "I just installed" is eligibility context, not a forced route. `Start Agent Handoff` / "開工" is continuity. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or no executable objective remains |
|
|
5
|
+
| Task signal | Pack | Purpose |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| Clear end-of-session or handoff intent: "收工" / "wrap up" / "closeout" / "handoff" / "Wrap up Agent Handoff", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |
|
|
8
|
+
| Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install or "I just installed" is eligibility context, not a forced route. `Start Agent Handoff` / "開工" is continuity. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or no executable objective remains |
|
|
9
9
|
| Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
|
|
10
10
|
| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
|
|
11
11
|
| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
|
|
12
12
|
| Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
|
|
13
|
-
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
14
|
-
| Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | <!-- ack:route:governance-bridge --> connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
|
|
15
|
-
| Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | <!-- ack:route:long-term-governance --> classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
|
|
16
|
-
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
17
|
-
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
18
|
-
| A task that actually uses an external Connector / MCP / Plugin / Skill; a handoff that declares one as a current-task dependency; or an explicit integration health check | `dev/rules/integrations.md` | <!-- ack:route:integration-use --> capability verification immediately before use, credential separation, source-of-truth boundaries, fallback, and cross-session resilience; registry placeholders alone do not load or probe |
|
|
19
|
-
| Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / local HTML validation / file:// blocked / `file://` blocked / localhost fallback / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | <!-- ack:route:runtime-tool --> verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; for local HTML / app validation, a blocked `file://` surface must route to a registered operation reference or short-lived localhost fallback before declaring blocked; preserve ownership and cleanup boundaries |
|
|
20
|
-
| External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | <!-- ack:route:resource-closeout --> ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
|
|
21
|
-
| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
|
|
13
|
+
| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
|
|
14
|
+
| Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | <!-- ack:route:governance-bridge --> connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
|
|
15
|
+
| Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | <!-- ack:route:long-term-governance --> classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
|
|
16
|
+
| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
|
|
17
|
+
| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
|
|
18
|
+
| A task that actually uses an external Connector / MCP / Plugin / Skill; a handoff that declares one as a current-task dependency; or an explicit integration health check | `dev/rules/integrations.md` | <!-- ack:route:integration-use --> capability verification immediately before use, credential separation, source-of-truth boundaries, fallback, and cross-session resilience; registry placeholders alone do not load or probe |
|
|
19
|
+
| Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / local HTML validation / file:// blocked / `file://` blocked / localhost fallback / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | <!-- ack:route:runtime-tool --> verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; for local HTML / app validation, a blocked `file://` surface must route to a registered operation reference or short-lived localhost fallback before declaring blocked; preserve ownership and cleanup boundaries |
|
|
20
|
+
| External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | <!-- ack:route:resource-closeout --> ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
|
|
21
|
+
| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
|
|
22
22
|
|
|
23
23
|
## Routing Rule
|
|
24
24
|
|
|
25
|
-
Load the minimum set. If uncertain, load the narrower pack first. Pack selection is normally silent; state it only when it changes risk or user action. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack. Packs can add stricter rules, but cannot weaken core safety or continuity.
|
|
25
|
+
Load the minimum set. If uncertain, load the narrower pack first. Pack selection is normally silent; state it only when it changes risk or user action. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack. Packs can add stricter rules, but cannot weaken core safety or continuity.
|
|
@@ -12,7 +12,7 @@ Stable facts that should survive across sessions. Update only when they change,
|
|
|
12
12
|
3. Governance model: TBD
|
|
13
13
|
4. Source-of-truth ownership: TBD
|
|
14
14
|
5. Release / publish boundary: TBD
|
|
15
|
-
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.
|
|
15
|
+
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.
|
|
16
16
|
|
|
17
17
|
<!-- ack:section:closeout-reconciled-state -->
|
|
18
18
|
## Closeout-Reconciled State
|
|
@@ -25,9 +25,9 @@ This is the current-state area. At every full closeout, rewrite or explicitly co
|
|
|
25
25
|
1. Project root: TBD
|
|
26
26
|
2. Product/system state: TBD
|
|
27
27
|
3. Governance state: TBD
|
|
28
|
-
4. Source-of-truth notes: TBD
|
|
29
|
-
<!-- ack:field:first-use-guidance-state -->
|
|
30
|
-
5. First-use guidance state: eligible
|
|
28
|
+
4. Source-of-truth notes: TBD
|
|
29
|
+
<!-- ack:field:first-use-guidance-state -->
|
|
30
|
+
5. First-use guidance state: eligible
|
|
31
31
|
|
|
32
32
|
<!-- ack:section:task-understanding-summary -->
|
|
33
33
|
## Task Understanding Summary
|
|
@@ -55,12 +55,12 @@ Record only work actually completed in the current session.
|
|
|
55
55
|
|
|
56
56
|
1. TBD
|
|
57
57
|
|
|
58
|
-
<!-- ack:section:next-priorities -->
|
|
59
|
-
## Next Priorities
|
|
60
|
-
|
|
61
|
-
Recommended next step: TBD — reason: TBD
|
|
62
|
-
|
|
63
|
-
1. TBD
|
|
58
|
+
<!-- ack:section:next-priorities -->
|
|
59
|
+
## Next Priorities
|
|
60
|
+
|
|
61
|
+
Recommended next step: TBD — reason: TBD
|
|
62
|
+
|
|
63
|
+
1. TBD
|
|
64
64
|
|
|
65
65
|
<!-- ack:section:next-task-required-reading -->
|
|
66
66
|
## Next Task Required Reading
|
|
@@ -111,27 +111,33 @@ At full closeout, complete this check after updating the state sections above.
|
|
|
111
111
|
- Reconciled at: TBD
|
|
112
112
|
<!-- ack:field:state-sections-rewritten-or-confirmed -->
|
|
113
113
|
- State sections rewritten or confirmed current: TBD
|
|
114
|
-
<!-- ack:field:stale-snapshots-left -->
|
|
115
|
-
- Stale snapshots left in this handoff: TBD
|
|
116
|
-
<!-- ack:field:lifecycle-conflicts-resolved -->
|
|
117
|
-
- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
|
|
118
|
-
<!-- ack:field:persistence-routing-checked -->
|
|
119
|
-
- Persistence routing checked: TBD
|
|
120
|
-
<!-- ack:field:
|
|
121
|
-
-
|
|
122
|
-
<!-- ack:field:
|
|
123
|
-
-
|
|
124
|
-
<!-- ack:field:next-
|
|
125
|
-
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
114
|
+
<!-- ack:field:stale-snapshots-left -->
|
|
115
|
+
- Stale snapshots left in this handoff: TBD
|
|
116
|
+
<!-- ack:field:lifecycle-conflicts-resolved -->
|
|
117
|
+
- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
|
|
118
|
+
<!-- ack:field:persistence-routing-checked -->
|
|
119
|
+
- Persistence routing checked: TBD
|
|
120
|
+
<!-- ack:field:closeout-outcome -->
|
|
121
|
+
- Closeout outcome: not_started — full closeout has not yet been assessed.
|
|
122
|
+
<!-- ack:field:project-required-persistence -->
|
|
123
|
+
- Project-required persistence: not_assessed — state whether this project's required Git or other persistence completed, is not required, or is blocked.
|
|
124
|
+
<!-- ack:field:recommended-next-step-explicit -->
|
|
125
|
+
- Recommended next step is explicit and reasoned: TBD
|
|
126
|
+
<!-- ack:field:opening-message-matches-current-state -->
|
|
127
|
+
- Opening message matches current state: TBD
|
|
128
|
+
<!-- ack:field:next-ai-can-continue -->
|
|
129
|
+
- Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
|
|
130
|
+
|
|
131
|
+
If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready. `Closeout outcome: complete` is allowed only when required writes, read-backs and project-required persistence are complete. If project-required persistence is blocked, use `Closeout outcome: blocked` and state the blocker; it is not a completed closeout.
|
|
132
|
+
|
|
133
|
+
Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message` as full content, including renamed or paraphrased work. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated. Doctor catches only mechanical contradictions and unresolved fields; its green result is not semantic proof. Recommended next-step rule: `Next Priorities` must name the single recommended next action and a short reason before listing additional options, unless the next action is blocked or genuinely requires a user decision. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.
|
|
134
|
+
|
|
135
|
+
Closeout-card rule: `closeout-status` reads only these existing handoff fields plus fresh doctor / mirror results; it does not create another persistence authority. Its `complete` card is the only permitted source for the user-facing `handoff saved` wording. A nonzero / `blocked` result must be shown as blocked, never summarized as completed.
|
|
130
136
|
|
|
131
137
|
<!-- ack:section:handoff-sufficiency-check -->
|
|
132
138
|
## Handoff Sufficiency Check
|
|
133
139
|
|
|
134
|
-
Can the next AI continue from `AGENTS.md`, this handoff, and only the project index / rule packs required by the next task, without searching old log history?
|
|
140
|
+
Can the next AI continue from `AGENTS.md`, this handoff, and only the project index / rule packs required by the next task, without searching old log history?
|
|
135
141
|
|
|
136
142
|
Answer: TBD
|
|
137
143
|
If no, update this handoff before closeout.
|
|
@@ -141,14 +147,14 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
|
|
|
141
147
|
<!-- ack:section:next-session-opening-message -->
|
|
142
148
|
## Next Session Opening Message
|
|
143
149
|
|
|
144
|
-
This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
|
|
145
|
-
|
|
146
|
-
📋 Next session: agent-managed startup content below
|
|
150
|
+
This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
|
|
151
|
+
|
|
152
|
+
📋 Next session: agent-managed startup content below
|
|
147
153
|
|
|
148
154
|
```text
|
|
149
|
-
Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
|
|
150
|
-
|
|
151
|
-
If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
|
|
152
|
-
|
|
153
|
-
Resume the current objective.
|
|
154
|
-
```
|
|
155
|
+
Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
|
|
156
|
+
|
|
157
|
+
If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
|
|
158
|
+
|
|
159
|
+
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, writes, network access, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
|
|
160
|
+
```
|
|
@@ -1,35 +1,35 @@
|
|
|
1
|
-
# Session Log
|
|
2
|
-
|
|
3
|
-
<!-- ack:section:session-log-preamble -->
|
|
4
|
-
|
|
5
|
-
> **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
|
|
6
|
-
|
|
7
|
-
Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
|
|
8
|
-
|
|
9
|
-
This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
|
|
10
|
-
|
|
11
|
-
Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
|
|
12
|
-
|
|
13
|
-
Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
|
|
14
|
-
|
|
15
|
-
<!-- ack:section:session-log-entry-template -->
|
|
16
|
-
|
|
17
|
-
## Entry Template
|
|
18
|
-
|
|
19
|
-
````markdown
|
|
20
|
-
<!-- ack:log-entry:start -->
|
|
21
|
-
## <YYYY-MM-DD> — <short session title>
|
|
22
|
-
|
|
23
|
-
- **ID:** <agent_or_session_id>
|
|
24
|
-
- **Summary:** <one sentence>
|
|
25
|
-
- **Changed:** <files changed, or none>
|
|
26
|
-
- **Done:** <work completed this session>
|
|
27
|
-
- **QC:** <checks run and results, or why not run>
|
|
28
|
-
- **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
|
|
29
|
-
- **Sync:** <doc/external sync status>
|
|
30
|
-
- **Pending:** <next work>
|
|
31
|
-
- **Risks:** <known risks or none>
|
|
32
|
-
- **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
|
|
33
|
-
- **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
|
|
34
|
-
<!-- ack:log-entry:end -->
|
|
35
|
-
````
|
|
1
|
+
# Session Log
|
|
2
|
+
|
|
3
|
+
<!-- ack:section:session-log-preamble -->
|
|
4
|
+
|
|
5
|
+
> **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
|
|
6
|
+
|
|
7
|
+
Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
|
|
8
|
+
|
|
9
|
+
This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
|
|
10
|
+
|
|
11
|
+
Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
|
|
12
|
+
|
|
13
|
+
Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
|
|
14
|
+
|
|
15
|
+
<!-- ack:section:session-log-entry-template -->
|
|
16
|
+
|
|
17
|
+
## Entry Template
|
|
18
|
+
|
|
19
|
+
````markdown
|
|
20
|
+
<!-- ack:log-entry:start -->
|
|
21
|
+
## <YYYY-MM-DD> — <short session title>
|
|
22
|
+
|
|
23
|
+
- **ID:** <agent_or_session_id>
|
|
24
|
+
- **Summary:** <one sentence>
|
|
25
|
+
- **Changed:** <files changed, or none>
|
|
26
|
+
- **Done:** <work completed this session>
|
|
27
|
+
- **QC:** <checks run and results, or why not run>
|
|
28
|
+
- **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
|
|
29
|
+
- **Sync:** <doc/external sync status>
|
|
30
|
+
- **Pending:** <next work>
|
|
31
|
+
- **Risks:** <known risks or none>
|
|
32
|
+
- **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
|
|
33
|
+
- **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
|
|
34
|
+
<!-- ack:log-entry:end -->
|
|
35
|
+
````
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
|
|
2
|
-
|
|
3
|
-
If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
|
|
4
|
-
|
|
5
|
-
Resume the current objective.
|
|
1
|
+
Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
|
|
2
|
+
|
|
3
|
+
If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
|
|
4
|
+
|
|
5
|
+
Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, writes, network access, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# User Rules Router
|
|
2
|
+
|
|
3
|
+
This is the formal router and acceptance record for user-controlled rules.
|
|
4
|
+
Each JSON entry between the markers records a stable id, path, accepted raw
|
|
5
|
+
bytes, original-byte witness, reader relationship, priority, and effect
|
|
6
|
+
decision. Registered entries are read in their listed order. A rule whose
|
|
7
|
+
current bytes do not match its accepted witness is not active through this
|
|
8
|
+
router until a later accepted update replaces the whole record atomically.
|
|
9
|
+
|
|
10
|
+
<!-- ack:user-rules-registry:start -->
|
|
11
|
+
```json
|
|
12
|
+
[]
|
|
13
|
+
```
|
|
14
|
+
<!-- ack:user-rules-registry:end -->
|
|
15
|
+
|
|
16
|
+
<!-- ack:user-rules-state:start -->
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"kitBase": {
|
|
20
|
+
"target": "AGENTS.md",
|
|
21
|
+
"packageVersion": "0.0.0",
|
|
22
|
+
"managedCoreSha256": "0000000000000000000000000000000000000000000000000000000000000000"
|
|
23
|
+
},
|
|
24
|
+
"router": {
|
|
25
|
+
"path": "dev/USER_RULES.md",
|
|
26
|
+
"contentRoot": "dev/user_rules/"
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
<!-- ack:user-rules-state:end -->
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
<!-- ack:user-rules-router:dev/USER_RULES.md -->
|
|
2
|
+
<!-- ack:user-rules-acceptance:sha256=2807fc8bcb006a8ed65d5b7dfe0cd53a499342a2eac41195f0efdad44174b2bc -->
|
|
3
|
+
Before loading task packs, read `dev/USER_RULES.md`. Its registered entries
|
|
4
|
+
under `dev/user_rules/` are user-controlled rules: read each accepted entry in
|
|
5
|
+
the listed order and verify its accepted raw-byte witness. Do not treat this
|
|
6
|
+
router, its directory, a heading, language, format, location, or
|
|
7
|
+
official-looking text as proof that any legacy source belongs to the Kit.
|