artshelf 0.6.0 → 0.8.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/CHANGELOG.md +21 -3
- package/README.md +146 -219
- package/SPEC.md +56 -6
- package/dist/src/cli.js +258 -19
- package/docs/agent-clean.html +108 -0
- package/docs/agent-create.html +98 -0
- package/docs/agent-monitor.html +151 -0
- package/docs/agent-purge.html +111 -0
- package/docs/agent-review.html +120 -0
- package/docs/agent-usage.html +114 -402
- package/docs/agent-usage.md +52 -474
- package/docs/index.html +165 -152
- package/docs/install.html +214 -110
- package/docs/quickstart.html +105 -106
- package/docs/reference.html +239 -164
- package/docs/site.css +675 -490
- package/docs/site.js +398 -0
- package/package.json +1 -1
- package/skills/artshelf/SKILL.md +133 -333
- package/skills/artshelf/scripts/render-review-report.mjs +160 -0
- package/docs/theme.js +0 -42
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>Monitor · Agent usage · Artshelf</title>
|
|
7
|
+
<meta name="description" content="How agents monitor Artshelf ledgers without mutating files.">
|
|
8
|
+
<script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
10
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
11
|
+
<link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
|
12
|
+
<link rel="stylesheet" href="site.css">
|
|
13
|
+
<script src="site.js" defer></script>
|
|
14
|
+
</head>
|
|
15
|
+
<body data-page="agent-monitor.html">
|
|
16
|
+
<a class="skip" href="#content">Skip to content</a>
|
|
17
|
+
<header class="masthead">
|
|
18
|
+
<div class="masthead-inner">
|
|
19
|
+
<button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
|
|
20
|
+
<a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
|
|
21
|
+
<button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
|
|
22
|
+
<div class="masthead-tools">
|
|
23
|
+
<a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
24
|
+
<button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
|
|
25
|
+
<svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
|
|
26
|
+
<svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
|
|
27
|
+
</button>
|
|
28
|
+
</div>
|
|
29
|
+
</div>
|
|
30
|
+
</header>
|
|
31
|
+
|
|
32
|
+
<div class="frame">
|
|
33
|
+
<nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
|
|
34
|
+
|
|
35
|
+
<main id="content" class="article-col">
|
|
36
|
+
<article>
|
|
37
|
+
<p class="kicker"><span class="n">4.2</span>Agents · Monitor</p>
|
|
38
|
+
<h1>Surface attention without touching artifacts.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
Monitor jobs answer one question: does any ledger need attention?
|
|
41
|
+
They read, summarize, and stop.
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
<section>
|
|
45
|
+
<h2>Signals</h2>
|
|
46
|
+
<ul class="boundary-list">
|
|
47
|
+
<li>
|
|
48
|
+
<span class="stamp readonly">Quiet</span>
|
|
49
|
+
<span>Registry ok, affected ledgers zero, no old trash. Send nothing unless a summary was requested.</span>
|
|
50
|
+
</li>
|
|
51
|
+
<li>
|
|
52
|
+
<span class="stamp approval">Attention</span>
|
|
53
|
+
<span>Due, manual-review, missing-path, or purge candidates exist. Report ledger path and plan id.</span>
|
|
54
|
+
</li>
|
|
55
|
+
<li>
|
|
56
|
+
<span class="stamp refused">Repair</span>
|
|
57
|
+
<span>Registry stale, ledger invalid, or path state unsafe. Fix discovery before anything else.</span>
|
|
58
|
+
</li>
|
|
59
|
+
</ul>
|
|
60
|
+
</section>
|
|
61
|
+
|
|
62
|
+
<section>
|
|
63
|
+
<h2>Ledger registry</h2>
|
|
64
|
+
<p>
|
|
65
|
+
One registry lets an agent review known project ledgers without moving
|
|
66
|
+
records into a global ledger. Reports should include the ledger path and
|
|
67
|
+
plan id when attention exists.
|
|
68
|
+
</p>
|
|
69
|
+
<pre><code><span class="c"># register a project ledger so --all review can see it</span>
|
|
70
|
+
artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo
|
|
71
|
+
|
|
72
|
+
<span class="c"># list registered ledgers and their health</span>
|
|
73
|
+
artshelf ledgers list --json
|
|
74
|
+
|
|
75
|
+
<span class="c"># review and due-check every registered ledger at once</span>
|
|
76
|
+
artshelf review --all --json
|
|
77
|
+
artshelf due --all --json
|
|
78
|
+
|
|
79
|
+
<span class="c"># find records this agent owns, across ledgers</span>
|
|
80
|
+
artshelf find --all --owner <agent-or-runtime> --json</code></pre>
|
|
81
|
+
<div class="callout" data-kind="note">
|
|
82
|
+
<span class="callout-label">Note</span>
|
|
83
|
+
<p><code>--all</code> is for discovery and review. It is never permission to mutate files.</p>
|
|
84
|
+
</div>
|
|
85
|
+
</section>
|
|
86
|
+
|
|
87
|
+
<section>
|
|
88
|
+
<h2>Scheduled review</h2>
|
|
89
|
+
<ul>
|
|
90
|
+
<li><strong>Read-only.</strong> Validate, status, due, review, doctor, and trash list are fine.</li>
|
|
91
|
+
<li><strong>Quiet by default.</strong> Send nothing when the review is clean unless a summary was requested.</li>
|
|
92
|
+
<li><strong>No network mode.</strong> Set <code>ARTSHELF_NO_UPDATE_CHECK=1</code> when jobs must avoid npm update checks and cache writes.</li>
|
|
93
|
+
<li><strong>Never schedule execution.</strong> Scheduled jobs must not run cleanup execute or trash purge execute.</li>
|
|
94
|
+
</ul>
|
|
95
|
+
<pre><code><span class="c"># ledger health, current ledger or all registered ledgers</span>
|
|
96
|
+
artshelf validate --json
|
|
97
|
+
artshelf validate --all --json
|
|
98
|
+
|
|
99
|
+
<span class="c"># what is due, kept, or missing</span>
|
|
100
|
+
artshelf due --json
|
|
101
|
+
artshelf due --all --json
|
|
102
|
+
|
|
103
|
+
<span class="c"># the full read-only pass: validate + due + plan preview</span>
|
|
104
|
+
artshelf review --all --json
|
|
105
|
+
|
|
106
|
+
<span class="c"># CLI version, paths, registry health, safety posture</span>
|
|
107
|
+
artshelf doctor --json
|
|
108
|
+
|
|
109
|
+
<span class="c"># lightweight counts, cron-friendly</span>
|
|
110
|
+
artshelf status --all --json</code></pre>
|
|
111
|
+
</section>
|
|
112
|
+
|
|
113
|
+
<section>
|
|
114
|
+
<h2>Plan previews</h2>
|
|
115
|
+
<pre><code><span class="c"># preview cleanup and register a plan, current ledger or all</span>
|
|
116
|
+
artshelf cleanup --dry-run --json
|
|
117
|
+
artshelf cleanup --dry-run --all --json
|
|
118
|
+
|
|
119
|
+
<span class="c"># what is sitting in trash, and how old it is</span>
|
|
120
|
+
artshelf trash list --ledger <ledger-path> --json
|
|
121
|
+
artshelf trash list --all --json
|
|
122
|
+
|
|
123
|
+
<span class="c"># preview an age-based purge for one explicit ledger</span>
|
|
124
|
+
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json</code></pre>
|
|
125
|
+
<p>
|
|
126
|
+
Dry-runs may write reusable plan files when entries exist. No-op dry-runs
|
|
127
|
+
report <code>not-created</code>. Matching cleanup dry-runs reuse the existing plan id.
|
|
128
|
+
</p>
|
|
129
|
+
</section>
|
|
130
|
+
|
|
131
|
+
<section>
|
|
132
|
+
<h2>Hard boundary</h2>
|
|
133
|
+
<p>Do not scan arbitrary filesystem locations unless the user opted into that discovery scope.</p>
|
|
134
|
+
<div class="callout" data-kind="boundary">
|
|
135
|
+
<span class="callout-label">Never scheduled</span>
|
|
136
|
+
<p>These two commands require exact human approval and must never run from a monitor job:</p>
|
|
137
|
+
</div>
|
|
138
|
+
<pre><code><span class="c"># mutating commands: approval only, never from a schedule</span>
|
|
139
|
+
artshelf cleanup --execute --plan-id <id>
|
|
140
|
+
artshelf trash purge --execute --plan-id <id></code></pre>
|
|
141
|
+
</section>
|
|
142
|
+
</article>
|
|
143
|
+
<footer class="pager" id="pager"></footer>
|
|
144
|
+
</main>
|
|
145
|
+
|
|
146
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
147
|
+
</div>
|
|
148
|
+
|
|
149
|
+
<footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
|
|
150
|
+
</body>
|
|
151
|
+
</html>
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>Purge · Agent usage · Artshelf</title>
|
|
7
|
+
<meta name="description" content="How agents purge Artshelf trash: physical deletion only from a separate, separately reviewed purge plan.">
|
|
8
|
+
<script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
10
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
11
|
+
<link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
|
12
|
+
<link rel="stylesheet" href="site.css">
|
|
13
|
+
<script src="site.js" defer></script>
|
|
14
|
+
</head>
|
|
15
|
+
<body data-page="agent-purge.html">
|
|
16
|
+
<a class="skip" href="#content">Skip to content</a>
|
|
17
|
+
<header class="masthead">
|
|
18
|
+
<div class="masthead-inner">
|
|
19
|
+
<button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
|
|
20
|
+
<a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
|
|
21
|
+
<button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
|
|
22
|
+
<div class="masthead-tools">
|
|
23
|
+
<a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
24
|
+
<button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
|
|
25
|
+
<svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
|
|
26
|
+
<svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
|
|
27
|
+
</button>
|
|
28
|
+
</div>
|
|
29
|
+
</div>
|
|
30
|
+
</header>
|
|
31
|
+
|
|
32
|
+
<div class="frame">
|
|
33
|
+
<nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
|
|
34
|
+
|
|
35
|
+
<main id="content" class="article-col">
|
|
36
|
+
<article>
|
|
37
|
+
<p class="kicker"><span class="n">4.5</span>Agents · Purge</p>
|
|
38
|
+
<h1>Delete for real, from its own reviewed plan.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
Purge is the only stage that physically deletes. Clean trashes; purge
|
|
41
|
+
empties the trash — and only from a separate plan a human reviewed and
|
|
42
|
+
approved. Trashed records stay discoverable until you deliberately
|
|
43
|
+
remove them.
|
|
44
|
+
</p>
|
|
45
|
+
|
|
46
|
+
<section>
|
|
47
|
+
<h2>Purge boundary</h2>
|
|
48
|
+
<ul class="boundary-list">
|
|
49
|
+
<li>
|
|
50
|
+
<span class="stamp readonly">Allowed freely</span>
|
|
51
|
+
<span><code>trash list</code> and <code>trash purge --dry-run</code> — discover and preview, moving nothing.</span>
|
|
52
|
+
</li>
|
|
53
|
+
<li>
|
|
54
|
+
<span class="stamp approval">Needs approval</span>
|
|
55
|
+
<span><code>trash purge --execute --plan-id</code> for one reviewed purge plan, on one ledger.</span>
|
|
56
|
+
</li>
|
|
57
|
+
<li>
|
|
58
|
+
<span class="stamp refused">Refused</span>
|
|
59
|
+
<span>No global purge — <code>--all</code> is not supported for purge — and no piggybacking on the cleanup plan that trashed the file.</span>
|
|
60
|
+
</li>
|
|
61
|
+
</ul>
|
|
62
|
+
<div class="callout" data-kind="boundary">
|
|
63
|
+
<span class="callout-label">Hard boundary</span>
|
|
64
|
+
<p>
|
|
65
|
+
The purge plan is always separate from the cleanup plan and separately
|
|
66
|
+
reviewed. Physical deletion never happens as a side effect of cleanup.
|
|
67
|
+
</p>
|
|
68
|
+
</div>
|
|
69
|
+
</section>
|
|
70
|
+
|
|
71
|
+
<section>
|
|
72
|
+
<h2>Preview, then purge</h2>
|
|
73
|
+
<p>
|
|
74
|
+
Purge runs the loop one more time: list what is in trash, preview an
|
|
75
|
+
age-based purge plan to get a purge plan id, then execute only that id
|
|
76
|
+
after a human approves it.
|
|
77
|
+
</p>
|
|
78
|
+
<pre><code><span class="c"># what is in trash for this ledger</span>
|
|
79
|
+
artshelf trash list --ledger <ledger-path> --json
|
|
80
|
+
|
|
81
|
+
<span class="c"># preview an age-based purge and get a purge plan id</span>
|
|
82
|
+
artshelf trash purge --older-than 7d --dry-run --ledger <ledger-path> --json
|
|
83
|
+
|
|
84
|
+
<span class="c"># delete for real, only with the reviewed purge plan id</span>
|
|
85
|
+
artshelf trash purge --execute --plan-id <purge-plan-id> --ledger <ledger-path> --json</code></pre>
|
|
86
|
+
<p>The approval wording for a purge:</p>
|
|
87
|
+
<pre><code>approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id></code></pre>
|
|
88
|
+
</section>
|
|
89
|
+
|
|
90
|
+
<section>
|
|
91
|
+
<h2>Verify quiet</h2>
|
|
92
|
+
<p>
|
|
93
|
+
After a purge executes, confirm the trash is empty and the shelf is
|
|
94
|
+
quiet with <code>artshelf trash list --all --json</code> and
|
|
95
|
+
<code>artshelf review --all --json</code>.
|
|
96
|
+
</p>
|
|
97
|
+
<p>
|
|
98
|
+
Purge writes a receipt and records it as an <code>owner=artshelf</code>
|
|
99
|
+
artifact, so the deletion stays auditable even after the files are gone.
|
|
100
|
+
</p>
|
|
101
|
+
</section>
|
|
102
|
+
</article>
|
|
103
|
+
<footer class="pager" id="pager"></footer>
|
|
104
|
+
</main>
|
|
105
|
+
|
|
106
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
107
|
+
</div>
|
|
108
|
+
|
|
109
|
+
<footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
|
|
110
|
+
</body>
|
|
111
|
+
</html>
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>Review · Agent usage · Artshelf</title>
|
|
7
|
+
<meta name="description" content="How agents turn Artshelf monitor output into decision packets.">
|
|
8
|
+
<script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
10
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
11
|
+
<link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
|
12
|
+
<link rel="stylesheet" href="site.css">
|
|
13
|
+
<script src="site.js" defer></script>
|
|
14
|
+
</head>
|
|
15
|
+
<body data-page="agent-review.html">
|
|
16
|
+
<a class="skip" href="#content">Skip to content</a>
|
|
17
|
+
<header class="masthead">
|
|
18
|
+
<div class="masthead-inner">
|
|
19
|
+
<button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
|
|
20
|
+
<a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
|
|
21
|
+
<button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
|
|
22
|
+
<div class="masthead-tools">
|
|
23
|
+
<a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
24
|
+
<button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
|
|
25
|
+
<svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
|
|
26
|
+
<svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
|
|
27
|
+
</button>
|
|
28
|
+
</div>
|
|
29
|
+
</div>
|
|
30
|
+
</header>
|
|
31
|
+
|
|
32
|
+
<div class="frame">
|
|
33
|
+
<nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
|
|
34
|
+
|
|
35
|
+
<main id="content" class="article-col">
|
|
36
|
+
<article>
|
|
37
|
+
<p class="kicker"><span class="n">4.3</span>Agents · Review</p>
|
|
38
|
+
<h1>Turn raw counts into a decision packet.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
Review is where a human enters the loop. Show what is ready for approval,
|
|
41
|
+
what needs a closer look, what is blocked, and the safety line.
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
<section>
|
|
45
|
+
<h2>Daily review workflow</h2>
|
|
46
|
+
<ol>
|
|
47
|
+
<li>Read <code>ledgers list</code>, <code>review --all</code>, and <code>trash list --all</code>.</li>
|
|
48
|
+
<li>Run explicit-ledger purge dry-runs only when old trash needs review.</li>
|
|
49
|
+
<li>Classify each candidate: <code>trash-safe</code>, <code>needs-human-review</code>, <code>resolve-candidate</code>, or <code>registry-problem</code>.</li>
|
|
50
|
+
<li>Ask only with exact ledger path, reviewed plan id, or ids.</li>
|
|
51
|
+
</ol>
|
|
52
|
+
</section>
|
|
53
|
+
|
|
54
|
+
<section>
|
|
55
|
+
<h2>Review plan report schema</h2>
|
|
56
|
+
<p>Construct an <code>ArtshelfReviewReport</code> JSON packet first, then render a compact decision card.</p>
|
|
57
|
+
<p>
|
|
58
|
+
Use <a href="schemas/artshelf-review-report.schema.json">schemas/artshelf-review-report.schema.json</a>
|
|
59
|
+
and <a href="examples/artshelf-review-report.json">examples/artshelf-review-report.json</a>.
|
|
60
|
+
The portable skill also ships <code>scripts/render-review-report.mjs</code>;
|
|
61
|
+
keep <code>decisionSummary</code> in the audit packet while
|
|
62
|
+
<code>decisionGroups</code> drive its visible counts and sections.
|
|
63
|
+
Emojis are encouraged only in host-specific wrappers, not the renderer.
|
|
64
|
+
</p>
|
|
65
|
+
<pre><code>Artshelf daily review
|
|
66
|
+
Status: <ok|attention needed>; registry <ok|attention>
|
|
67
|
+
|
|
68
|
+
Ready for approval: <n>
|
|
69
|
+
Needs review first: <n>
|
|
70
|
+
Blocked: <n>
|
|
71
|
+
|
|
72
|
+
Recommended action
|
|
73
|
+
<one short sentence>.
|
|
74
|
+
|
|
75
|
+
Ready for approval
|
|
76
|
+
1. <label>
|
|
77
|
+
Why: <reason>
|
|
78
|
+
Action: <next step>
|
|
79
|
+
approve artshelf cleanup ledger <ledger-path> plan <plan-id>
|
|
80
|
+
|
|
81
|
+
Needs review first
|
|
82
|
+
1. <label>
|
|
83
|
+
Why: <reason>
|
|
84
|
+
Suggested next step: <next step>
|
|
85
|
+
|
|
86
|
+
Blocked
|
|
87
|
+
<none, or blocker and repair step>
|
|
88
|
+
|
|
89
|
+
Safety
|
|
90
|
+
Dry-run only. No execute, resolve, or delete ran.</code></pre>
|
|
91
|
+
</section>
|
|
92
|
+
|
|
93
|
+
<section>
|
|
94
|
+
<h2>Approval wording</h2>
|
|
95
|
+
<p>
|
|
96
|
+
Keep the full JSON as the audit packet. Do not paste the whole packet into chat unless the user
|
|
97
|
+
asks for it. Always include the exact approval target in the message body as a fallback.
|
|
98
|
+
</p>
|
|
99
|
+
<pre><code>approve artshelf cleanup ledger <ledger-path> plan <plan-id>
|
|
100
|
+
approve artshelf trash purge ledger <ledger-path> plan <purge-plan-id>
|
|
101
|
+
approve artshelf resolve missing ledger <ledger-path> ids <id...></code></pre>
|
|
102
|
+
<div class="callout" data-kind="boundary">
|
|
103
|
+
<span class="callout-label">Hard boundary</span>
|
|
104
|
+
<p>
|
|
105
|
+
Never execute from a read-only preview id. Never generate a fresh plan and
|
|
106
|
+
execute it in the same step. After any approved action, verify quiet with
|
|
107
|
+
<code>artshelf review --all --json</code>.
|
|
108
|
+
</p>
|
|
109
|
+
</div>
|
|
110
|
+
</section>
|
|
111
|
+
</article>
|
|
112
|
+
<footer class="pager" id="pager"></footer>
|
|
113
|
+
</main>
|
|
114
|
+
|
|
115
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
116
|
+
</div>
|
|
117
|
+
|
|
118
|
+
<footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
|
|
119
|
+
</body>
|
|
120
|
+
</html>
|