kairos-chain 3.58.2 → 3.59.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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +83 -0
- data/lib/kairos_mcp/version.rb +1 -1
- data/templates/knowledge/project_orientation_report/assets/report_template.html +214 -0
- data/templates/knowledge/project_orientation_report/project_orientation_report.md +257 -0
- data/templates/knowledge/project_orientation_report/references/worked_example.md +106 -0
- data/templates/knowledge/project_orientation_report/scripts/check_report.py +658 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_all_exempt.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_comment_details.html +34 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_details_open.html +34 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_dot_svg.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_em_font_size.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_empty_visuals.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_hidden_headings.html +1 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_missing_section.html +28 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_placeholder.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_stylesheet_pre.html +33 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_summary_content.html +32 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_svg_overflow_rect.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_svg_smuggle.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_svg_transform.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_token_forms.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_too_long.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_translate_one_arg.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/bad_whitespace_pre.html +34 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/good_declared_tokens.html +32 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/good_minimal.html +31 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/good_nine_sections.html +34 -0
- data/templates/knowledge/project_orientation_report/test/fixtures/good_tspan.html +31 -0
- data/templates/knowledge/project_orientation_report/test/test_check_report.py +136 -0
- data/templates/skillsets/project_manager/config/pm.yml +3 -1
- data/templates/skillsets/project_manager/lib/project_manager/digest.rb +77 -11
- data/templates/skillsets/project_manager/lib/project_manager/parsed_time.rb +77 -0
- data/templates/skillsets/project_manager/lib/project_manager/store.rb +23 -5
- data/templates/skillsets/project_manager/lib/project_manager.rb +1 -0
- data/templates/skillsets/project_manager/plugin/SKILL.md +13 -5
- data/templates/skillsets/project_manager/plugin/agents/secretary.md +54 -23
- data/templates/skillsets/project_manager/skillset.json +1 -1
- data/templates/skillsets/project_manager/test/test_project_manager.rb +460 -3
- data/templates/skillsets/project_manager/tools/pm_digest.rb +13 -1
- metadata +29 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 104bc21b4db1c6c438f5e18767df43571d318f5637a878e626f22433b3d46b69
|
|
4
|
+
data.tar.gz: 57edf1d45e47e26f444e794c5b1e7be1be1e01cbbbd7ed831201265f8bfc18c1
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 8c0e5a937839894abada8bf37ad6b226d1b5d357e4a08f2a7a50d0cfac6fbd2aa5fc0fc455729996ef090610e9a19bf7c4be3f368ded7bf44d7c86a7735e3d58
|
|
7
|
+
data.tar.gz: 490cdba379a4c395cfd704e7e4e96f4f8ee170225afb55d5f7f2c63adbe1f904e09e6b1f5bb4c856fe6b4a44b675e2e07f80ff79294c5f719cd6b5afa5c4088d
|
data/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,89 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
|
|
|
4
4
|
|
|
5
5
|
This project follows [Semantic Versioning](https://semver.org/).
|
|
6
6
|
|
|
7
|
+
## [3.59.0] - 2026-08-05
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- **`project_manager` names what no bucket covered (SkillSet 0.3.0).** `pm_digest`
|
|
12
|
+
sorted open items into four buckets and reported the remainder as a count called
|
|
13
|
+
`healthy_count`. Dormancy is computed at high salience only, so a normal- or
|
|
14
|
+
low-salience item with no deadline was counted but never named, however long it
|
|
15
|
+
sat. On the operator's own store that was 12 of 22 open items, the oldest
|
|
16
|
+
untouched for 98 days, and nothing in the digest would ever have raised them.
|
|
17
|
+
|
|
18
|
+
The digest now returns `uncovered_count` and `uncovered_stale`. The latter names
|
|
19
|
+
every uncovered item the store already calls dormant, in full and oldest first,
|
|
20
|
+
ties broken by id — in full rather than a top-N because untouched items advance
|
|
21
|
+
in lockstep, so a fixed cut omits the same work every day forever. The secretary
|
|
22
|
+
agent reads the list out after the buckets with no next step attached: it is a
|
|
23
|
+
list of what nothing raised, not a bucket to act on. `healthy_count` survives as
|
|
24
|
+
a deprecated alias, because the name is wrong — the number mixes work that is
|
|
25
|
+
fine with work nobody is watching. Bucket membership is otherwise unchanged.
|
|
26
|
+
|
|
27
|
+
Hardening found while reviewing it, all reachable through the tool surface.
|
|
28
|
+
`pm_item` writes `due` and `touched_at` through with no validation and every
|
|
29
|
+
reader assumed `Time.parse` would succeed, so one bad value replaced the whole
|
|
30
|
+
digest — or the whole deadline query — with an error object. Both now read
|
|
31
|
+
through `ProjectManager.parse_time`, which answers nil for a malformed string, a
|
|
32
|
+
non-string and an out-of-range field alike. The same discipline covers
|
|
33
|
+
caller-supplied numbers in `whole_number`, including the `pm.yml` thresholds and
|
|
34
|
+
the `digest:` mapping they sit in, so an operator typo in the one file
|
|
35
|
+
`skillset upgrade` never repairs falls back to defaults instead of disabling the
|
|
36
|
+
digest. `summarize` also carries the raw `touched_at` now, so a consumer can tell
|
|
37
|
+
a missing marker from an unreadable one — the secretary is required to word them
|
|
38
|
+
differently and previously had to guess.
|
|
39
|
+
|
|
40
|
+
Eight review rounds against a frozen target, closed by exhaustion rather than by
|
|
41
|
+
threshold: the last round's findings were pre-existing SkillSet defects outside
|
|
42
|
+
the target, not defects in this change. The recurring mistake worth recording is
|
|
43
|
+
that seven consecutive rounds each found the same shape — a guard placed one step
|
|
44
|
+
short of where the value enters — at the call site instead of the source, at two
|
|
45
|
+
of three exception classes, at a config hash's values instead of the hash, and at
|
|
46
|
+
the hash instead of the read that produces it.
|
|
47
|
+
|
|
48
|
+
- **`project_orientation_report` L1 knowledge.** A fixed procedure for producing a
|
|
49
|
+
one-page HTML report that explains where a single thread of work stands, written
|
|
50
|
+
for a reader who has not followed it. Ten invariants, a fixed eight-section order,
|
|
51
|
+
three collapsed appendices, and SVG rules; the checkable part is enforced by
|
|
52
|
+
`scripts/check_report.py` (standard library only, exit 0 on pass).
|
|
53
|
+
|
|
54
|
+
The two invariants that carry the most weight are non-obvious. The writer must
|
|
55
|
+
not hold the session context that produced the work — a writer who knows
|
|
56
|
+
everything skips premises without noticing, so the report is written by a
|
|
57
|
+
context-blank process given only the artifacts. And a section that explains a
|
|
58
|
+
*change* must carry one worked example from start to finish, because a reader
|
|
59
|
+
forced to re-learn the setup at every section stops following at the first switch.
|
|
60
|
+
|
|
61
|
+
The design was not validated by a design review. It was validated by building
|
|
62
|
+
four prototypes on the same subject and having a human read each one: invariants
|
|
63
|
+
7, 8, 9, 10 and the SVG rules all came out of those judgments and none of them
|
|
64
|
+
came out of the design table. `references/worked_example.md` records which
|
|
65
|
+
prototype failed how.
|
|
66
|
+
|
|
67
|
+
The checker itself went through two rounds of multi-LLM review, neither of which
|
|
68
|
+
approved it, and the shape of what they found is why it ships as it does. The
|
|
69
|
+
first version matched tags with regular expressions, so every content check was
|
|
70
|
+
defeated by moving content into a region the pattern did not scan — wrapping the
|
|
71
|
+
failing example in `<details open>` turned it into a pass. It now builds a
|
|
72
|
+
document tree and measures rendered text, so relocating content no longer helps.
|
|
73
|
+
The second round found a further class: a report could declare every section
|
|
74
|
+
exempt and pass as a blank page, a one-argument `translate` silently moved
|
|
75
|
+
nothing, and a relative font unit was read as a tiny absolute size. Those are
|
|
76
|
+
closed, and each is now a fixture.
|
|
77
|
+
|
|
78
|
+
What is deliberately not closed is stated in the script and in the skill: this
|
|
79
|
+
is a lint over the ways an author gets a wrong answer while writing normally,
|
|
80
|
+
not a boundary against someone determined to pass an unreadable report. Text
|
|
81
|
+
drawn by a stylesheet, an `<iframe srcdoc>`, or a full-width spelling of a
|
|
82
|
+
forbidden label all get through, and closing that class needs a renderer rather
|
|
83
|
+
than a parser. A pass means a handful of known ways of being unreadable are
|
|
84
|
+
absent; whether the report can actually be understood in one pass stays a human
|
|
85
|
+
judgement. `test/` ships 22 fixtures and a runner so the boundary is checkable
|
|
86
|
+
rather than asserted — 18 that must fail, each naming the check that must catch
|
|
87
|
+
it, and 4 that must pass, because closing an evasion is trivial if the gate is
|
|
88
|
+
allowed to reject everything.
|
|
89
|
+
|
|
7
90
|
## [3.58.2] - 2026-08-03
|
|
8
91
|
|
|
9
92
|
### Fixed
|
data/lib/kairos_mcp/version.rb
CHANGED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="ja">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<!-- Tokens that LOOK work-internal but are ordinary vocabulary (A4, Q3, gpt-5).
|
|
7
|
+
Declaring one is a decision; leaving this empty is the default. -->
|
|
8
|
+
<meta name="orientation-allowed-tokens" content="">
|
|
9
|
+
<title>作業名 — 現状レポート</title>
|
|
10
|
+
<style>
|
|
11
|
+
:root {
|
|
12
|
+
--ink: #23262b;
|
|
13
|
+
--muted: #5f6672;
|
|
14
|
+
--line: #d5d9e0;
|
|
15
|
+
--panel: #f7f8fa;
|
|
16
|
+
--accent: #b3402f;
|
|
17
|
+
}
|
|
18
|
+
body {
|
|
19
|
+
font-family: "Hiragino Sans", "Noto Sans JP", "Yu Gothic", ui-sans-serif, sans-serif;
|
|
20
|
+
color: var(--ink);
|
|
21
|
+
background: #fff;
|
|
22
|
+
line-height: 1.9;
|
|
23
|
+
font-size: 16.5px;
|
|
24
|
+
max-width: 46rem;
|
|
25
|
+
margin: 0 auto;
|
|
26
|
+
padding: 2.5rem 1.2rem 5rem;
|
|
27
|
+
}
|
|
28
|
+
h1 { font-size: 1.5rem; line-height: 1.5; margin: 0 0 .4rem; }
|
|
29
|
+
h2 {
|
|
30
|
+
font-size: 1.13rem;
|
|
31
|
+
margin: 3rem 0 .9rem;
|
|
32
|
+
padding-bottom: .35rem;
|
|
33
|
+
border-bottom: 2px solid var(--line);
|
|
34
|
+
}
|
|
35
|
+
p { margin: .9rem 0; }
|
|
36
|
+
.stamp {
|
|
37
|
+
background: var(--panel);
|
|
38
|
+
border: 1px solid var(--line);
|
|
39
|
+
border-radius: 6px;
|
|
40
|
+
padding: .8rem 1rem;
|
|
41
|
+
font-size: .87rem;
|
|
42
|
+
color: var(--muted);
|
|
43
|
+
line-height: 1.8;
|
|
44
|
+
}
|
|
45
|
+
.stamp b { color: var(--ink); font-weight: 600; }
|
|
46
|
+
table { border-collapse: collapse; width: 100%; margin: 1.2rem 0; font-size: .93rem; }
|
|
47
|
+
th, td { border: 1px solid var(--line); padding: .5rem .7rem; text-align: left; vertical-align: top; }
|
|
48
|
+
th { background: var(--panel); font-weight: 600; }
|
|
49
|
+
figure { margin: 1.4rem 0; }
|
|
50
|
+
figcaption { font-size: .85rem; color: var(--muted); margin-top: .5rem; }
|
|
51
|
+
svg { display: block; margin: 0 auto; }
|
|
52
|
+
.mark { color: var(--accent); font-weight: 600; }
|
|
53
|
+
details {
|
|
54
|
+
margin-top: 3rem;
|
|
55
|
+
border-top: 1px solid var(--line);
|
|
56
|
+
padding-top: 1rem;
|
|
57
|
+
}
|
|
58
|
+
summary { cursor: pointer; font-weight: 600; }
|
|
59
|
+
@media print {
|
|
60
|
+
body { max-width: none; font-size: 11pt; }
|
|
61
|
+
details { page-break-before: always; }
|
|
62
|
+
details[open] summary { list-style: none; }
|
|
63
|
+
}
|
|
64
|
+
</style>
|
|
65
|
+
</head>
|
|
66
|
+
<body>
|
|
67
|
+
|
|
68
|
+
<!-- 節0 表紙。条件2 — 時点を名指しする。図表は不要、時点の枠がその代わり。
|
|
69
|
+
data-visual="none" が「この節に図表が無いのは意図的だ」という宣言。
|
|
70
|
+
宣言の無い節は図表を要求される -->
|
|
71
|
+
<h1 data-visual="none">《作業名》 — 現状レポート</h1>
|
|
72
|
+
<p>《この 1 枚は何の話か。1 文で》</p>
|
|
73
|
+
<div class="stamp">
|
|
74
|
+
<b>生成</b> 《YYYY-MM-DD HH:MM》 ／
|
|
75
|
+
<b>git</b> 《short commit》 ／
|
|
76
|
+
<b>chain の高さ</b> 《length》<br>
|
|
77
|
+
<b>読んだ入力</b> 《n 件。一覧は付録 C》
|
|
78
|
+
</div>
|
|
79
|
+
|
|
80
|
+
<!-- 節1 登場人物。作業の内部ではなく、作業に入る前の前提だけ。SVG 必須 -->
|
|
81
|
+
<h2>登場人物</h2>
|
|
82
|
+
<p>《誰が誰に何を渡すのか。ここでは仕組みを書かない》</p>
|
|
83
|
+
<figure>
|
|
84
|
+
<!--
|
|
85
|
+
箱の幅の決め方。SVG の text は折り返さないので、書き手が計算する。
|
|
86
|
+
|
|
87
|
+
日本語 1 文字 ≈ font-size × 1.0 半角英数 1 文字 ≈ font-size × 0.55
|
|
88
|
+
|
|
89
|
+
font-size 14 なら日本語 1 文字が 14px。下の箱は幅 220px なので **15 文字**まで。
|
|
90
|
+
超えるときは、箱を広げるか、下のように <tspan> で行を分ける。
|
|
91
|
+
1 行に収める必要はない。収まらない行を 1 本の text に押し込むのが失敗の形。
|
|
92
|
+
検収スクリプトは、各行を親の <rect> と照合して溢れを落とす。
|
|
93
|
+
-->
|
|
94
|
+
<svg viewBox="0 0 760 210" style="width:100%;max-width:760px;height:auto" role="img">
|
|
95
|
+
<title>《図の内容を 1 文で。読み上げ用》</title>
|
|
96
|
+
<defs>
|
|
97
|
+
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
|
|
98
|
+
markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
|
99
|
+
<path d="M 0 0 L 10 5 L 0 10 z" fill="#5f6672"/>
|
|
100
|
+
</marker>
|
|
101
|
+
</defs>
|
|
102
|
+
<rect x="10" y="60" width="220" height="76" rx="6" fill="#f7f8fa" stroke="#5f6672"/>
|
|
103
|
+
<text font-size="14" text-anchor="middle"
|
|
104
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#23262b">
|
|
105
|
+
<tspan x="120" y="94">《登場人物 1 の名前》</tspan>
|
|
106
|
+
<tspan x="120" y="116">《長ければ 2 行目へ》</tspan>
|
|
107
|
+
</text>
|
|
108
|
+
<rect x="270" y="60" width="220" height="76" rx="6" fill="#f7f8fa" stroke="#5f6672"/>
|
|
109
|
+
<text font-size="14" text-anchor="middle"
|
|
110
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#23262b">
|
|
111
|
+
<tspan x="380" y="94">《登場人物 2 の名前》</tspan>
|
|
112
|
+
<tspan x="380" y="116">《長ければ 2 行目へ》</tspan>
|
|
113
|
+
</text>
|
|
114
|
+
<rect x="530" y="60" width="220" height="76" rx="6" fill="#f7f8fa" stroke="#5f6672"/>
|
|
115
|
+
<text font-size="14" text-anchor="middle"
|
|
116
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#23262b">
|
|
117
|
+
<tspan x="640" y="94">《登場人物 3 の名前》</tspan>
|
|
118
|
+
<tspan x="640" y="116">《長ければ 2 行目へ》</tspan>
|
|
119
|
+
</text>
|
|
120
|
+
<line x1="230" y1="98" x2="265" y2="98" stroke="#5f6672" marker-end="url(#arrow)"/>
|
|
121
|
+
<line x1="490" y1="98" x2="525" y2="98" stroke="#5f6672" marker-end="url(#arrow)"/>
|
|
122
|
+
<text x="248" y="46" text-anchor="middle" font-size="11"
|
|
123
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#5f6672">《渡すもの》</text>
|
|
124
|
+
<text x="508" y="46" text-anchor="middle" font-size="11"
|
|
125
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#5f6672">《渡すもの》</text>
|
|
126
|
+
</svg>
|
|
127
|
+
<figcaption>《図の説明。1 行》</figcaption>
|
|
128
|
+
</figure>
|
|
129
|
+
|
|
130
|
+
<!-- 節2 何が壊れていたか。条件8 — 実際の入力と出力の値を 1 組 -->
|
|
131
|
+
<h2>何が壊れていたか</h2>
|
|
132
|
+
<p>《具体的に何が起きたのか》</p>
|
|
133
|
+
<table>
|
|
134
|
+
<tr><th>入力</th><th>出た結果</th></tr>
|
|
135
|
+
<tr><td>《実際に与えた値》</td><td>《実際に返った値》</td></tr>
|
|
136
|
+
</table>
|
|
137
|
+
|
|
138
|
+
<!-- 節3 直そうとして何が起きたか。条件10 — 追う例を決め、時点ごとの扱いを 1 枚の表に -->
|
|
139
|
+
<h2>直そうとして何が起きたか</h2>
|
|
140
|
+
<p>《経緯を 1 本の線で。以下は追いかける例》</p>
|
|
141
|
+
<table>
|
|
142
|
+
<tr><th>時点</th><th>《追う例 その 1》</th><th>《追う例 その 2》</th></tr>
|
|
143
|
+
<tr><td>《最初》</td><td>《どうなったか》</td><td>《どうなったか》</td></tr>
|
|
144
|
+
<tr><td>《修正 1》</td><td>《どうなったか》</td><td><span class="mark">《ここで開いた穴》</span></td></tr>
|
|
145
|
+
<tr><td>《最終》</td><td>《どうなったか》</td><td>《どうなったか》</td></tr>
|
|
146
|
+
</table>
|
|
147
|
+
|
|
148
|
+
<!-- 節4 どう閉じたか。条件10 — 節3 と同じ例で、前と後を対比する -->
|
|
149
|
+
<h2>どう閉じたか</h2>
|
|
150
|
+
<p>《最後にとった手と、その一言の理由》</p>
|
|
151
|
+
<figure>
|
|
152
|
+
<svg viewBox="0 0 700 220" style="width:100%;max-width:700px;height:auto" role="img">
|
|
153
|
+
<title>《前と後で、追っている例の扱いがどう変わったか》</title>
|
|
154
|
+
<rect x="20" y="20" width="320" height="180" rx="6" fill="#f7f8fa" stroke="#5f6672"/>
|
|
155
|
+
<text x="40" y="50" font-size="13"
|
|
156
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#23262b">《修正前》</text>
|
|
157
|
+
<text x="40" y="100" font-size="12"
|
|
158
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#23262b">《追う例 その 1 の扱い》</text>
|
|
159
|
+
<text x="40" y="130" font-size="12"
|
|
160
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#b3402f">《追う例 その 2 の扱い》</text>
|
|
161
|
+
<rect x="360" y="20" width="320" height="180" rx="6" fill="#f7f8fa" stroke="#5f6672"/>
|
|
162
|
+
<text x="380" y="50" font-size="13"
|
|
163
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#23262b">《修正後》</text>
|
|
164
|
+
<text x="380" y="100" font-size="12"
|
|
165
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#23262b">《追う例 その 1 の扱い》</text>
|
|
166
|
+
<text x="380" y="130" font-size="12"
|
|
167
|
+
font-family="Hiragino Sans, Noto Sans JP, sans-serif" fill="#23262b">《追う例 その 2 の扱い》</text>
|
|
168
|
+
</svg>
|
|
169
|
+
<figcaption>《なぜこれで閉じるのか。1 行》</figcaption>
|
|
170
|
+
</figure>
|
|
171
|
+
|
|
172
|
+
<!-- 節5 今どこ。数字は必ず分母つき -->
|
|
173
|
+
<h2>今どこ</h2>
|
|
174
|
+
<table>
|
|
175
|
+
<tr><th>項目</th><th>状態</th></tr>
|
|
176
|
+
<tr><td>《進んだところ》</td><td>《数字は分母つきで》</td></tr>
|
|
177
|
+
<tr><td>《止まっているところ》</td><td>《何待ちか》</td></tr>
|
|
178
|
+
</table>
|
|
179
|
+
|
|
180
|
+
<!-- 節6 決まっていないこと。条件6 — 作業側が未決と書き残したものだけ。提案を書かない -->
|
|
181
|
+
<h2 data-visual="none">決まっていないこと</h2>
|
|
182
|
+
<ul>
|
|
183
|
+
<li>《作業側が未決と書き残していること》</li>
|
|
184
|
+
</ul>
|
|
185
|
+
|
|
186
|
+
<!-- 節7 記録の食い違い。条件5 — どれかに寄せない。無ければ「食い違いなし」と明記 -->
|
|
187
|
+
<h2>記録の食い違い</h2>
|
|
188
|
+
<table>
|
|
189
|
+
<tr><th>記録が言っていること</th><th>実際</th></tr>
|
|
190
|
+
<tr><td>《どの記録が何と書いているか》</td><td>《確かめた結果》</td></tr>
|
|
191
|
+
</table>
|
|
192
|
+
|
|
193
|
+
<details>
|
|
194
|
+
<summary>付録 A — 符牒の対応表</summary>
|
|
195
|
+
<table>
|
|
196
|
+
<tr><th>元の記録の符牒</th><th>本体での呼び名</th></tr>
|
|
197
|
+
<tr><td>《符牒》</td><td>《日本語の呼び名》</td></tr>
|
|
198
|
+
</table>
|
|
199
|
+
</details>
|
|
200
|
+
|
|
201
|
+
<details>
|
|
202
|
+
<summary>付録 B — 網羅の記録</summary>
|
|
203
|
+
<p>《変更ファイル一覧、テストの内訳、実測値の全部。引き継ぎ用》</p>
|
|
204
|
+
</details>
|
|
205
|
+
|
|
206
|
+
<details>
|
|
207
|
+
<summary>付録 C — 読んだもの</summary>
|
|
208
|
+
<ul>
|
|
209
|
+
<li><code>《パス》</code> — 《そこから取った内容を一言》</li>
|
|
210
|
+
</ul>
|
|
211
|
+
</details>
|
|
212
|
+
|
|
213
|
+
</body>
|
|
214
|
+
</html>
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: project_orientation_report
|
|
3
|
+
description: Use mid-project to produce a one-page HTML report that explains where a single thread of work now stands, written for a reader who has not followed it — a context-blank writer, a fixed section order, SVG figures instead of ascii art, and a mechanical checker in scripts/ with an adversarial fixture corpus in test/.
|
|
4
|
+
version: 0.2.0
|
|
5
|
+
tags: [orientation, report, handoff, readability, html, svg, l2-to-human, fail-closed]
|
|
6
|
+
related: [instance_session_protocol, kairoschain_capability_boundary, context_graph_recall]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Project Orientation Report
|
|
10
|
+
|
|
11
|
+
作業が数日から数週間止まったあと、それを再開する人は毎回おなじ作業をしている。散らばった記録から
|
|
12
|
+
現状を組み立て直す作業である。この skill は、その組み立てを **1 枚の HTML** に固定して、
|
|
13
|
+
**その作業を追っていない読み手**が一度読んで現状を掴めるようにする。
|
|
14
|
+
|
|
15
|
+
対象は **一本の作業**であって、instance 全体ではない。
|
|
16
|
+
|
|
17
|
+
## いつ使うか
|
|
18
|
+
|
|
19
|
+
- 作業を中断するとき、または再開する前
|
|
20
|
+
- 他人（未来の自分を含む）に一本の作業を引き継ぐとき
|
|
21
|
+
- 記録が増えすぎて、どれが正本か分からなくなったとき
|
|
22
|
+
|
|
23
|
+
**使わない場面**: 作業の途中経過の共有、次にやることの相談。この skill は理解を供給する道具であって、
|
|
24
|
+
作業を進める道具ではない。
|
|
25
|
+
|
|
26
|
+
## 何を作るか
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
作業を1つ指定
|
|
30
|
+
│
|
|
31
|
+
▼
|
|
32
|
+
段1 種を決める 記録を1件、または作業名
|
|
33
|
+
段2 近傍を集める 記録どうしの関連をたどる（dream_scan の traverse）
|
|
34
|
+
段3 実体を足す git の差分と履歴、設計文書、chain の記録、作業項目
|
|
35
|
+
│
|
|
36
|
+
│ 成果物だけを渡す（会話の文脈は渡さない）
|
|
37
|
+
▼
|
|
38
|
+
文脈を持たない書き手が、決まった骨組みで書く
|
|
39
|
+
│
|
|
40
|
+
▼
|
|
41
|
+
1枚の HTML（本体 + 折りたたんだ付録）
|
|
42
|
+
│
|
|
43
|
+
▼
|
|
44
|
+
scripts/check_report.py で機械の検収
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## 不変条件
|
|
48
|
+
|
|
49
|
+
守るべき性質を述べる。機構の選択は実装に委ねる。
|
|
50
|
+
|
|
51
|
+
**1. 書き手は文脈を持たない。** レポートを書く主体は、その作業をしたセッションの会話文脈を
|
|
52
|
+
持ってはならない。渡してよいのは成果物だけ（記録のファイル、差分、設計文書）。
|
|
53
|
+
「前提知識のない読者を想定して書く」を演じさせるのではなく、**本当に前提知識のない書き手を用意する**。
|
|
54
|
+
全部知っている文脈から書くと、前提を無意識に飛ばす。行為者と記述者を分ける形は、
|
|
55
|
+
「自分の点検を判定に数えるな」と同じ構造である。
|
|
56
|
+
|
|
57
|
+
**2. 時点を名指しする。** 表紙に、生成時刻・git の commit・chain の高さ・読んだ入力の一覧を固定する。
|
|
58
|
+
書かないと、次に読んだとき「レポートが古い」のか「自分の理解が古い」のかを判別できない。
|
|
59
|
+
|
|
60
|
+
**3. すべての主張は入力を指す。** 本文のどの主張も、読んだ入力のどれかに対応づく。
|
|
61
|
+
対応づかないことは書かない。書き手の推測は「推測」と明示した箇所にだけ置く。
|
|
62
|
+
|
|
63
|
+
**4. 範囲は一本の作業。** 全体像を一枚に畳もうとすると必ず嘘になる。
|
|
64
|
+
|
|
65
|
+
**5. 記録どうしの食い違いを消さない。** 索引・記録・実際のコードが食い違っていたら、
|
|
66
|
+
どれかに寄せずに**食い違いとして本文に書く**。食い違いこそ再開時に一番効く情報である。
|
|
67
|
+
|
|
68
|
+
**6. レポートは判断しない。** 「次に何をすべきか」の提案を含めない。含めてよいのは
|
|
69
|
+
「作業側が未決だと書き残していること」だけ。
|
|
70
|
+
|
|
71
|
+
**7. 記録の符牒を本文に持ち込まない。** その作業の中でだけ通じる番号や記号を本文で使わない。
|
|
72
|
+
日本語の呼び名に置き換える。元の符牒が要るなら付録に対応表を 1 枚置く。
|
|
73
|
+
末尾に用語集を付けても足りない。読み手に本文と用語集を往復させる形は、
|
|
74
|
+
「他の文書を開かずに一度読んで意味が取れること」に反する。
|
|
75
|
+
|
|
76
|
+
**8. 散文だけの節を作らない。** どの節にも、図・表・実際の値による具体例のいずれかが 1 つ以上ある。
|
|
77
|
+
無ければその節はまだ書けていない。
|
|
78
|
+
|
|
79
|
+
**9. 人が読む本体と、網羅の付録を分ける。** 本体は一度で読み通せる長さに収める。
|
|
80
|
+
入りきらないものは削らずに付録へ落とす。付録は引き継ぎと、あとで細部を確かめる用途に使う。
|
|
81
|
+
|
|
82
|
+
**10. 変化を説明する節は、一つの同じ例を最後まで持ち回る。** 「何が壊れていたか」
|
|
83
|
+
「直そうとして何が起きたか」「どう閉じたか」は状態ではなく**変化**の説明である。
|
|
84
|
+
節ごとに例を替えない。最初に 1〜2 個の例を決め、以後その同じ例が各時点でどう扱われたかを追う。
|
|
85
|
+
理想は、変化の全体が**表 1 枚**に収まること（行が時点、列が追っている例）。
|
|
86
|
+
**抽象的な図（構造の増減、時系列の線）は具体例の代わりにならない。** 条件 8 が数える視覚要素として、
|
|
87
|
+
変化の節では**値の入った例**を数える。
|
|
88
|
+
|
|
89
|
+
## 本体の骨組み
|
|
90
|
+
|
|
91
|
+
文書の構成をなぞる順ではなく、**理解が組み上がる順**に並べる。節の順序は固定。
|
|
92
|
+
|
|
93
|
+
| 節 | 問いの形 | 必須の視覚要素 |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| 0 表紙 | この 1 枚は何の話か（1 文）。いつの時点か | 時点の枠 |
|
|
96
|
+
| 1 登場人物 | 誰が誰に何を渡すのか。**作業に入る前の前提だけ** | 図 1 枚。仕組みを書かない |
|
|
97
|
+
| 2 何が壊れていたか | 具体的に何が起きたのか | 実際の入力と出力の値を 1 組 |
|
|
98
|
+
| 3 直そうとして何が起きたか | 経緯を 1 本の線で | 追っている例が各時点でどうなったかの表 |
|
|
99
|
+
| 4 どう閉じたか | 最後にとった手と、その一言の理由 | 同じ例の前後の対比 |
|
|
100
|
+
| 5 今どこ | 進んだところと止まっているところ | 表 1 枚。数字は分母つき |
|
|
101
|
+
| 6 決まっていないこと | 作業側が未決と書き残していること | 箇条 |
|
|
102
|
+
| 7 記録の食い違い | 記録どうしが一致しない点 | 表 1 枚。無ければ「食い違いなし」と明記 |
|
|
103
|
+
|
|
104
|
+
節 1 の役割を取り違えやすい。ここは**その作業の内部の全体像**ではなく、
|
|
105
|
+
**作業に入る前に要る前提**を渡す節である。内部の全体像から始めると、読み手は最初の一歩で落ちる。
|
|
106
|
+
|
|
107
|
+
### 付録（`<details>` に入れる。検収の対象外）
|
|
108
|
+
|
|
109
|
+
| 付録 | 中身 |
|
|
110
|
+
|---|---|
|
|
111
|
+
| A 符牒の対応表 | 元の記録の符牒と、本体で使った日本語の呼び名の対応 |
|
|
112
|
+
| B 網羅の記録 | 変更ファイル一覧、テストの内訳、実測値の全部。引き継ぎ用 |
|
|
113
|
+
| C 読んだもの | ファイルパスと、そこから取った内容の一言 |
|
|
114
|
+
|
|
115
|
+
本体から付録への参照は「詳しくは付録 B」の 1 行にとどめる。本体の主張を付録へ逃がさない。
|
|
116
|
+
|
|
117
|
+
## 図の作り方
|
|
118
|
+
|
|
119
|
+
ASCII を `<pre>` に埋める形は採らない。行の折り返しと等幅の崩れで、読み手の環境で図がずれる。
|
|
120
|
+
|
|
121
|
+
| 図の中身 | 形 | 理由 |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| 関係・流れ・前後の対比（箱と矢印） | SVG | ずれない。矢印が引ける |
|
|
124
|
+
| 値の対応（入力と出力、時点ごとの判定） | HTML の表 | これは図ではない。表のほうが崩れず読み上げも通る |
|
|
125
|
+
|
|
126
|
+
SVG の制約。守らないと壊れる。
|
|
127
|
+
|
|
128
|
+
- `<svg viewBox="0 0 W H" style="width:100%;max-width:Wpx;height:auto">` の形にする
|
|
129
|
+
- `<foreignObject>` を使わない。印刷とブラウザで割れる
|
|
130
|
+
- **SVG の `<text>` は自動で折り返さない。** 文字列ごとに描画幅を見積もり、
|
|
131
|
+
親の箱と viewBox に収まることを書き手が計算で確かめる。
|
|
132
|
+
日本語 1 文字を font-size の 1.0 倍、半角英数を 0.55 倍で見積もる
|
|
133
|
+
- 強調は 1 色だけ。印刷して読めること。ダークモードの指定を入れない
|
|
134
|
+
- `<title>` を置く（読み上げ用）
|
|
135
|
+
|
|
136
|
+
`assets/report_template.html` が、この制約を満たした空の骨組みである。矢印の marker 定義も入っている。
|
|
137
|
+
|
|
138
|
+
## 手順
|
|
139
|
+
|
|
140
|
+
1. **範囲を決める。** 作業を一本選ぶ。関係する記録が十数件に収まらないなら、範囲が広すぎる。
|
|
141
|
+
2. **入力を集める。** 記録・差分・設計文書・chain の記録。集めた**パスの一覧**を作る。
|
|
142
|
+
これが条件 3 の対応先になる。
|
|
143
|
+
3. **時点を採る。** `git rev-parse --short HEAD` と `chain_status` の length を控える。
|
|
144
|
+
4. **文脈を持たない書き手に渡す。** 会話の経緯は渡さない。渡すものは次の 4 つで、これが全部。
|
|
145
|
+
- `assets/report_template.html` の**中身**（骨組み・体裁・矢印の定義・図の書き方の注記）
|
|
146
|
+
- **この文書の不変条件 10 個と骨組みの表**。4 つだけ抜き出して渡さない。10 個すべてを渡す
|
|
147
|
+
- **入力そのもの**。書き手がファイルを開ける立場なら、パスの一覧でよい。
|
|
148
|
+
開けない立場（別プロセスの `llm_call` など）なら、**中身を渡す**。
|
|
149
|
+
「パスを渡す」と「成果物を渡す」は別のことで、書き手の立場で決まる
|
|
150
|
+
- 段 3 で採った時点の値
|
|
151
|
+
5. **機械で検収する。** `python3 scripts/check_report.py REPORT.html`。
|
|
152
|
+
落ちた項目は書き直す。人が読む前に落とす。
|
|
153
|
+
6. **人が読む。** 通らなかった節が分かったら、**レポートではなくこの skill を直す**。
|
|
154
|
+
条件 7・8・9・10 はすべて、この段の判定から出た。
|
|
155
|
+
|
|
156
|
+
## レポート側が守る 2 つの約束ごと
|
|
157
|
+
|
|
158
|
+
機械が読むための印を 2 つ、レポートの HTML に入れる。
|
|
159
|
+
|
|
160
|
+
**図表の無い節は、見出しで宣言する。** `<h2 data-visual="none">決まっていないこと</h2>`。
|
|
161
|
+
宣言の無い節は図か表を要求される。位置で免除しない——節が 1 つ増えただけで免除が
|
|
162
|
+
隣の節へずれるため。
|
|
163
|
+
|
|
164
|
+
> この宣言は v0.2 で入った。**それ以前に書かれたレポートは、表紙と「決まっていないこと」の
|
|
165
|
+
> 見出しに属性を 1 つずつ足すまで落ちる。** 読み手に見えるものは変わらないので、
|
|
166
|
+
> 移行は 2 箇所の書き足しで済む。落ちたまま放置してよい（過去のレポートは記録であって、
|
|
167
|
+
> 通し続ける必要は無い）。
|
|
168
|
+
|
|
169
|
+
**符牒に見えるが違う語は、頭で宣言する。**
|
|
170
|
+
`<meta name="orientation-allowed-tokens" content="A4, Q3, gpt-5">`。
|
|
171
|
+
検出はわざと広くしてあるので、紙の大きさやモデル名のような無害な語も引っかかる。
|
|
172
|
+
それを消すには宣言を書く。**宣言を書くこと自体が規律**で、スクリプトの中の許可リストを
|
|
173
|
+
太らせるより安全である。組み込みの免除は層の名前 3 語だけ。
|
|
174
|
+
|
|
175
|
+
## 検収
|
|
176
|
+
|
|
177
|
+
`scripts/check_report.py` が測る。合格で終了コード 0、不合格で 1。
|
|
178
|
+
**測るのはタグではなく、読み手に見えている内容。**
|
|
179
|
+
|
|
180
|
+
| 検査 | 合格条件 |
|
|
181
|
+
|---|---|
|
|
182
|
+
| 未記入 | 《》で囲まれた placeholder が 0 個。未記入のテンプレートは通らない |
|
|
183
|
+
| 符牒 | 見えている文に、宣言されていない符牒が 0 個 |
|
|
184
|
+
| 整形済みの塊 | `<pre>` と `white-space: pre` が本体に 0 個 |
|
|
185
|
+
| 分量 | 見えている文が 6000 文字以内（`--max-body-chars` で変更可） |
|
|
186
|
+
| 節 | 8 節以上 |
|
|
187
|
+
| 視覚要素 | 宣言で免除されていない全節に、**中身のある**図か表がある（空の表は不可） |
|
|
188
|
+
| 図の収まり | すべての行が、囲んでいる `<rect>` に収まる。箱が無ければ図の枠に収まる |
|
|
189
|
+
|
|
190
|
+
「見えている内容」の定義がこの検収の要である。折りたたまれていない `<details open>` の中も、
|
|
191
|
+
`<svg>` の中の `<text>` も、読み手には見えているので本文に数える。`<script>` `<style>`
|
|
192
|
+
コメントは数えない。**内容を別の場所へ移しても検査から逃げられない。**
|
|
193
|
+
|
|
194
|
+
### この検収の適用範囲
|
|
195
|
+
|
|
196
|
+
**事故で起きる欠陥を捕まえる道具であって、悪意を防ぐ門ではない。** レポートを書くのは
|
|
197
|
+
利用者のために働く agent であって、検収をすり抜けようとする者ではない。
|
|
198
|
+
|
|
199
|
+
| 範囲内（普通に書いていて踏む） | 範囲外（意図してやれば通せる。すべて実証済み・容認） |
|
|
200
|
+
|---|---|
|
|
201
|
+
| ASCII 図、未記入の欄、箱から溢れる label | 別紙の CSS が `content:` で描く文字 |
|
|
202
|
+
| 測り方が拾えない書き方の `translate` | `<iframe srcdoc>` の中身 |
|
|
203
|
+
| `em` のような相対単位の font-size | 全角や幅ゼロ文字を混ぜた符牒 |
|
|
204
|
+
| 全部の節を免除にしてしまう | 禁止すべき符牒を自分で許可宣言する |
|
|
205
|
+
| 見出しを `display:none` で隠す | 入れ子の `<svg>` を親の外へ置く |
|
|
206
|
+
| 折りたたんだ付録の `<summary>` に本文を書く | `textLength` で描画幅を上書きする |
|
|
207
|
+
|
|
208
|
+
右の列を塞ぐには、解析ではなく**実際に描画する**必要がある。レビューを 2 周して、
|
|
209
|
+
毎回「示された抜け道は塞がり、新しい種類が見つかる」形になった。これは面が閉じていない
|
|
210
|
+
ことの兆候であって、道具の価値とは別の話である。左の列の失敗は、実際に人間の読み手が
|
|
211
|
+
踏んだものばかりで、そこを捕まえるだけで元は取れている。
|
|
212
|
+
|
|
213
|
+
### 検収が測っていないもの
|
|
214
|
+
|
|
215
|
+
不変条件は 10 個あり、**機械が見ているのは 3 個だけ**（符牒、視覚要素と分量、図の収まり）。
|
|
216
|
+
残る 7 個は人が守るしかない。
|
|
217
|
+
|
|
218
|
+
| 未検査の条件 | なぜ機械で測れないか |
|
|
219
|
+
|---|---|
|
|
220
|
+
| 1 書き手が文脈を持たない | 手順の話であって、成果物に痕跡が残らない |
|
|
221
|
+
| 2 時点を名指しする | 枠があることは測れるが、値が正しいかは測れない |
|
|
222
|
+
| 3 すべての主張が入力を指す | 主張と入力の対応づけを機械が判定できない |
|
|
223
|
+
| 4 範囲は一本の作業 | 一本かどうかを外から決められない |
|
|
224
|
+
| 5 食い違いを消さない | 消したことは、成果物からは見えない |
|
|
225
|
+
| 6 判断しない | 提案と事実の区別が形からはつかない |
|
|
226
|
+
| 10 同じ例を持ち回る | 同じ例かどうかを判定する方法が今のところ無い |
|
|
227
|
+
|
|
228
|
+
**合格は「読める」ことの証明ではない。** 落ちる形をいくつか塞いだ、という以上の意味はない。
|
|
229
|
+
最後は、この作業を知らない人が 1 回読んで、次に何が問題かを自分の言葉で言えるかで決まる。
|
|
230
|
+
|
|
231
|
+
## テスト
|
|
232
|
+
|
|
233
|
+
`test/test_check_report.py` が `test/fixtures/` の 14 件を走らせる。標準ライブラリだけで動く。
|
|
234
|
+
|
|
235
|
+
fixture は **2 方向**ある。10 件は「読めないのに通ってしまった形」で、すべて外部の評価者が
|
|
236
|
+
実際に実行して示した抜け道である。4 件は「読めるのに落とされた形」。
|
|
237
|
+
**塞ぐだけなら全部不合格にすれば達成できる**ので、両方向を同時に測る。
|
|
238
|
+
どの検査が捕まえるべきかも fixture ごとに宣言してあり、別の理由で落ちた場合はテストが赤くなる。
|
|
239
|
+
|
|
240
|
+
## 層について
|
|
241
|
+
|
|
242
|
+
「文脈を持たない書き手」は harness 側（Claude Code の subagent など）の機能であって、
|
|
243
|
+
KairosChain の機能ではない。KairosChain 単体で動かす場合は、
|
|
244
|
+
別プロセスの `llm_call` に成果物だけを渡す形に落ちる。**借り物であることを明記して使う。**
|
|
245
|
+
|
|
246
|
+
## 由来
|
|
247
|
+
|
|
248
|
+
2026-08-05。設計は `docs/drafts/project_orientation_report_skill_design_v0.1.md`（中身は v0.3。
|
|
249
|
+
開発リポジトリにのみ在り、gem には載らない）。
|
|
250
|
+
|
|
251
|
+
**設計レビューは回していない。** 代わりに試作を 4 回作って人間の読み手が判定し、そのたびに
|
|
252
|
+
条件を追加した。条件 7・8・9・10 と図の規約は、すべてその判定から出たもので、机上では出なかった。
|
|
253
|
+
|
|
254
|
+
**実装は 1 度 multi-LLM review に落ちている。** 4 者中 0 者が承認、深刻な指摘 14 件。
|
|
255
|
+
初版の検収スクリプトはタグを見ていたので、内容を除外領域へ移すだけで全部すり抜けられた。
|
|
256
|
+
評価者が実行して示した抜け道が、いま `test/fixtures/` の `bad_*` 10 件になっている。
|
|
257
|
+
経緯は `references/worked_example.md`。
|