project-spec 0.0.0-stage → 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.
@@ -0,0 +1,545 @@
1
+ #!/usr/bin/env python3
2
+ """Plan and explicitly finish integrated project-knowledge reviews."""
3
+ import argparse
4
+ import contextlib
5
+ import datetime as dt
6
+ import hashlib
7
+ import html
8
+ import json
9
+ import os
10
+ from pathlib import Path
11
+ import shutil
12
+ import stat
13
+ import subprocess
14
+ import sys
15
+ import tempfile
16
+
17
+ import knowledge
18
+
19
+ PARTIAL_EXIT = 3 # a partial finish; 2 is argparse's usage error and 1 is any other failure
20
+
21
+
22
+ def digest(path):
23
+ return hashlib.sha256(path.read_bytes()).hexdigest() if path.is_file() else None
24
+
25
+
26
+ def git(repo, *args, binary=False):
27
+ p = subprocess.run(['git', '-C', str(repo), *args], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
28
+ if p.returncode:
29
+ raise ValueError('git ' + ' '.join(args) + ': ' + p.stderr.decode(errors='replace').strip())
30
+ return p.stdout if binary else p.stdout.decode('utf-8', 'surrogateescape').strip()
31
+
32
+
33
+ def atomic(path, data):
34
+ path.parent.mkdir(parents=True, exist_ok=True)
35
+ fd, name = tempfile.mkstemp(dir=path.parent, prefix='.sync-')
36
+ try:
37
+ with os.fdopen(fd, 'wb') as f:
38
+ f.write(data)
39
+ f.flush()
40
+ os.fsync(f.fileno())
41
+ os.replace(name, path)
42
+ finally:
43
+ if os.path.exists(name):
44
+ os.unlink(name)
45
+
46
+
47
+ def safe_bytes(text):
48
+ # Paths that are not valid UTF-8 arrive as lone surrogates; show them as \udcXX escapes.
49
+ return text.encode('utf-8', 'backslashreplace')
50
+
51
+
52
+ def jsonbytes(value):
53
+ return (json.dumps(value, ensure_ascii=True, indent=2, sort_keys=True) + '\n').encode()
54
+
55
+
56
+ def relevant(path, vault_rel):
57
+ p = Path(path)
58
+ parts = p.parts
59
+ bundle_metadata = vault_rel.startswith('knowledge/') and path in {'knowledge/README.md', 'knowledge/.gitignore'}
60
+ return bool(parts) and not bundle_metadata and not knowledge.credential_path(path) and not (path == vault_rel or path.startswith(vault_rel + '/')) and not (path == 'knowledge/tooling/project-knowledge' or path.startswith('knowledge/tooling/project-knowledge/')) and not any(knowledge.fold(x) in {'.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '__pycache__'} for x in parts)
61
+
62
+
63
+ def housekeeping(path, vault_rel):
64
+ """Paths a sync never queues because they are the vault, the portable skill copy or their wrapper files."""
65
+ if vault_rel.startswith('knowledge/') and path in {'knowledge/README.md', 'knowledge/.gitignore'}:
66
+ return True
67
+ return any(path == base or path.startswith(base + '/') for base in (vault_rel, 'knowledge/tooling/project-knowledge'))
68
+
69
+
70
+ def retarget_hint(repo, vault, target):
71
+ """If HEAD moved past target only through excluded paths, say how to retarget; otherwise None."""
72
+ head = git(repo, 'rev-parse', 'HEAD^{commit}')
73
+ if head == target or subprocess.run(['git', '-C', str(repo), 'merge-base', '--is-ancestor', target, head]).returncode:
74
+ return None
75
+ try:
76
+ vault_rel = vault.relative_to(repo).as_posix()
77
+ except ValueError:
78
+ return None
79
+ for line in git(repo, 'rev-list', '--reverse', '--parents', target + '..' + head).splitlines():
80
+ commit, *parents = line.split()
81
+ if parents and any(not housekeeping(p, vault_rel) for row in changes(repo, parents[0], commit) for p in row['paths']):
82
+ return None
83
+ return (f'plan target {target} is not HEAD {head}, but every commit in between touches only excluded paths (the vault, the portable skill copy, '
84
+ f'their wrapper files). First set review_target in the run page to the new HEAD (review_target: {head}; review_base stays), '
85
+ 'then re-run "scan --write-status" (the plan records the run page\'s bytes, so the page must be edited before the scan), '
86
+ 'regenerate the receipt with "receipt", fill in the dispositions and run finish again. Do not commit the vault in between: that would move HEAD again.')
87
+
88
+
89
+ def changes(repo, left, right):
90
+ raw = git(repo, 'diff', '--name-status', '-z', '-M', left, right, '--', binary=True).split(b'\0')
91
+ rows = []
92
+ i = 0
93
+ while i < len(raw) and raw[i]:
94
+ status = os.fsdecode(raw[i]); i += 1
95
+ count = 2 if status[0] in 'RC' else 1
96
+ paths = [os.fsdecode(x) for x in raw[i:i + count]]; i += count
97
+ rows.append({'status': status, 'paths': paths})
98
+ return rows
99
+
100
+
101
+ def dirty(repo):
102
+ raw = git(repo, 'status', '--porcelain=v1', '-z', '--untracked-files=all', binary=True).split(b'\0')
103
+ paths = []
104
+ i = 0
105
+ while i < len(raw) and raw[i]:
106
+ item = os.fsdecode(raw[i]); i += 1
107
+ paths.append(item[3:])
108
+ if 'R' in item[:2] or 'C' in item[:2]:
109
+ paths.append(os.fsdecode(raw[i])); i += 1
110
+ return sorted(set(paths))
111
+
112
+
113
+ def normalized(path):
114
+ return Path(path).as_posix()
115
+
116
+
117
+ class Evidence:
118
+ """Resolve each evidence path once so matching is dictionary/set lookup, not repeated stat calls."""
119
+
120
+ def __init__(self, repo):
121
+ self.repo = repo
122
+ self._keys = {}
123
+
124
+ def keys(self, path):
125
+ # Casefold is intentionally conservative even on case-sensitive volumes; it
126
+ # also preserves impact when a formerly cited path has been deleted.
127
+ got = self._keys.get(path)
128
+ if got is None:
129
+ inode = None
130
+ try:
131
+ info = knowledge.safe_path(self.repo, path).stat()
132
+ inode = (info.st_dev, info.st_ino)
133
+ except (OSError, ValueError):
134
+ pass
135
+ got = self._keys[path] = (normalized(path).casefold(), inode)
136
+ return got
137
+
138
+ def group(self, paths):
139
+ names, inodes = set(), set()
140
+ for path in paths:
141
+ name, inode = self.keys(path)
142
+ names.add(name)
143
+ if inode is not None:
144
+ inodes.add(inode)
145
+ return names, inodes
146
+
147
+ def matches(self, group, path):
148
+ name, inode = self.keys(path)
149
+ return name in group[0] or (inode is not None and inode in group[1])
150
+
151
+
152
+ def same_evidence(repo, left, right):
153
+ evidence = Evidence(repo)
154
+ return evidence.matches(evidence.group([right]), left)
155
+
156
+
157
+ def validate_selected_evidence(repo, vault, selected, target):
158
+ """Compare selected working-tree evidence directly with target tree blobs."""
159
+ loaded, _, errors, _, _ = knowledge.load_vault(repo, vault, freshness=False)
160
+ if errors:
161
+ raise ValueError('structural errors while checking evidence: ' + '; '.join(errors))
162
+ by_id = {note['meta']['id']: note for note in loaded}
163
+ for ident in selected:
164
+ note = by_id.get(ident)
165
+ if not note:
166
+ raise ValueError('selected note missing: ' + ident)
167
+ for source in note['meta']['sources']:
168
+ evidence = knowledge.safe_path(repo, source)
169
+ if knowledge.credential_path(source) or knowledge.credential_path(evidence.resolve().relative_to(repo).as_posix()):
170
+ raise ValueError('credential evidence is forbidden: ' + ident)
171
+ if evidence.resolve() != repo / normalized(source):
172
+ raise ValueError('affected note cites aliased evidence; use its canonical path: ' + ident)
173
+ try:
174
+ mode = evidence.lstat().st_mode
175
+ except FileNotFoundError:
176
+ if knowledge.tolerates_missing_source(note['meta'], by_id):
177
+ continue
178
+ raise ValueError('affected note cites missing evidence: ' + ident)
179
+ if not stat.S_ISREG(mode):
180
+ raise ValueError('affected note evidence must be a regular file: ' + ident)
181
+ # Literal pathspecs prevent special filename syntax from widening lookup.
182
+ raw = git(repo, '--literal-pathspecs', 'ls-tree', '-z', target, '--', source, binary=True)
183
+ entries = [entry for entry in raw.split(b'\0') if entry]
184
+ if len(entries) != 1:
185
+ raise ValueError('affected note cites evidence not tracked in target: ' + ident + ': ' + source)
186
+ header, sep, name = entries[0].partition(b'\t')
187
+ fields = header.split()
188
+ if not sep or name != os.fsencode(source) or len(fields) != 3 or fields[0] not in (b'100644', b'100755') or fields[1] != b'blob':
189
+ raise ValueError('affected note evidence is not a regular tracked target file: ' + ident + ': ' + source)
190
+ blob = git(repo, 'cat-file', 'blob', fields[2].decode('ascii'), binary=True)
191
+ if hashlib.sha256(evidence.read_bytes()).digest() != hashlib.sha256(blob).digest():
192
+ raise ValueError('affected note cites dirty evidence or checkout bytes differ from target blob (e.g. CRLF or smudge): ' + ident + ': ' + source)
193
+
194
+
195
+ def scan(repo, vault, target):
196
+ if Path(git(repo, 'rev-parse', '--show-toplevel')).resolve() != repo:
197
+ raise ValueError('repo must be the worktree root')
198
+ if not vault.is_relative_to(repo) or vault == repo:
199
+ raise ValueError('vault must be inside this worktree')
200
+ vr = vault.relative_to(repo).as_posix()
201
+ cursorpath = vault / '.knowledge/review.json'
202
+ cursor = json.loads(cursorpath.read_text())
203
+ if cursor.get('schema') != 1 or not isinstance(cursor.get('ref'), str) or not isinstance(cursor.get('reviewed_through'), str):
204
+ raise ValueError('invalid review cursor')
205
+ head = git(repo, 'rev-parse', 'HEAD^{commit}')
206
+ branch_proc = subprocess.run(['git', '-C', str(repo), 'symbolic-ref', '-q', 'HEAD'], capture_output=True, text=True)
207
+ branch = branch_proc.stdout.strip() or '(detached)'
208
+ base = git(repo, 'rev-parse', cursor['reviewed_through'] + '^{commit}')
209
+ tip = git(repo, 'rev-parse', (target or 'HEAD') + '^{commit}')
210
+ blockers = []
211
+ if git(repo, 'rev-parse', '--is-shallow-repository') == 'true':
212
+ blockers.append('shallow history cannot establish complete coverage')
213
+ if subprocess.run(['git', '-C', str(repo), 'merge-base', '--is-ancestor', base, tip]).returncode:
214
+ blockers.append('review cursor is not an ancestor of target')
215
+ if branch != cursor['ref']:
216
+ blockers.append('checkout is not the cursor branch')
217
+ if git(repo, 'diff', '--name-only', '--diff-filter=U', '-z', binary=True):
218
+ blockers.append('worktree has unresolved merge conflicts')
219
+ if tip != head:
220
+ blockers.append('target is not checked out at HEAD; remote evidence cannot be accepted')
221
+ # One call lists the whole range with parents; each line is "commit parent...".
222
+ listing = git(repo, 'rev-list', '--reverse', '--parents', base + '..' + tip).splitlines() if not any('ancestor' in b for b in blockers) else []
223
+ commits = [line.split()[0] for line in listing]
224
+ rows = []
225
+ for line in listing:
226
+ commit, *parents = line.split()
227
+ if parents:
228
+ rows.extend({'commit': commit, **row} for row in changes(repo, parents[0], commit))
229
+ paths = sorted({p for row in rows for p in row['paths'] if relevant(p, vr)})
230
+ rows = [{**row, 'paths': [p for p in row['paths'] if relevant(p, vr)]} for row in rows if any(relevant(p, vr) for p in row['paths'])]
231
+ dirty_paths = [p for p in dirty(repo) if relevant(p, vr)]
232
+ notes, edges, errors, warnings, baseline = knowledge.load_vault(repo, vault)
233
+ evidence = Evidence(repo)
234
+ changed = evidence.group(paths)
235
+ affected = {n['meta']['id']: n for n in notes if any(evidence.matches(changed, source) for source in list(n['meta']['sources']) + list(baseline.get(n['meta']['id'], {})))}
236
+ sources = sorted({p for n in notes for p in n['meta']['sources']} | set(paths) | set(dirty_paths))
237
+ source_hashes = {}
238
+ skipped_sources = []
239
+ for source in sources:
240
+ try:
241
+ path = knowledge.safe_path(repo, source)
242
+ resolved = path.resolve().relative_to(repo).as_posix()
243
+ if knowledge.credential_path(source) or knowledge.credential_path(resolved):
244
+ skipped_sources.append(source)
245
+ continue
246
+ source_hashes[source] = digest(path)
247
+ except (ValueError, OSError):
248
+ skipped_sources.append(source)
249
+ dirty_group = evidence.group(dirty_paths)
250
+ dirty_affected = sorted(n['meta']['id'] for n in notes if any(evidence.matches(dirty_group, source) for source in n['meta']['sources']))
251
+ note_hashes = {n['meta']['id']: {'path': n['path'], 'sha256': digest(vault / n['path']), 'sources': n['meta']['sources'], 'areas': n['meta']['areas']} for n in notes}
252
+ mapped = evidence.group({normalized(p) for n in affected.values() for p in list(n['meta']['sources']) + list(baseline.get(n['meta']['id'], {}))})
253
+ return {'schema': 1, 'scanned_at': dt.datetime.now(dt.timezone.utc).isoformat(), 'repo': str(repo), 'vault': str(vault), 'git_dir': git(repo, 'rev-parse', '--absolute-git-dir'), 'branch': branch, 'head': head, 'target': tip, 'base': base, 'cursor_sha256': digest(cursorpath), 'baseline_sha256': digest(vault / '.knowledge/sources.json'), 'commits': commits, 'changes': rows, 'paths': paths, 'dirty': dirty_paths, 'dirty_affected_notes': dirty_affected, 'skipped_sources': skipped_sources, 'affected_notes': sorted(affected), 'affected_areas': sorted({a for n in affected.values() for a in n['meta']['areas']}), 'unmapped': [path for path in paths if not evidence.matches(mapped, path)], 'source_hashes': source_hashes, 'notes': note_hashes, 'errors': errors, 'warnings': warnings, 'blockers': blockers, 'state': 'blocked' if blockers or errors else ('pending' if paths or dirty_paths or warnings else 'ready')}
254
+
255
+
256
+ @contextlib.contextmanager
257
+ def lock(vault):
258
+ path = knowledge.output_path(vault, '.knowledge/sync.lock')
259
+ path.parent.mkdir(parents=True, exist_ok=True)
260
+ try:
261
+ fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
262
+ except FileExistsError:
263
+ raise ValueError('knowledge sync lock already exists')
264
+ try:
265
+ os.close(fd)
266
+ yield
267
+ finally:
268
+ path.unlink()
269
+
270
+
271
+ def status(vault, plan):
272
+ data = jsonbytes(plan)
273
+ state = {'ready': 'ready', 'pending': 'needs review', 'blocked': 'blocked'}[plan['state']]
274
+ if plan['state'] == 'pending' and not plan['paths'] and not plan['warnings']:
275
+ state = 'local changes pending'
276
+ lines = ['State: ' + state, 'Scanned: ' + plan['scanned_at'],
277
+ 'Branch: ' + plan['branch'] + ' at ' + plan['head'],
278
+ 'Commit range: ' + plan['base'] + '..' + plan['target'], '',
279
+ f"Integrated changes awaiting review: {len(plan['paths'])} paths; {len(plan['affected_notes'])} affected notes.",
280
+ f"Uncommitted working-tree changes: {len(plan['dirty'])} paths; {len(plan['dirty_affected_notes'])} affected notes.", '',
281
+ 'An empty commit queue does not mean the entire project has been researched.', '',
282
+ 'Blockers and errors:']
283
+ lines += ['- ' + x for x in plan['blockers'] + plan['errors']] or ['- None']
284
+ lines += ['', 'Source freshness warnings:'] + (['- ' + x for x in plan['warnings']] or ['- None'])
285
+ lines += ['', 'Changes without linked notes:'] + (['- ' + x for x in plan['unmapped']] or ['- None'])
286
+ lines += ['', 'Notes affected by working-tree changes:'] + (['- ' + x for x in plan['dirty_affected_notes']] or ['- None'])
287
+ lines += ['', 'Skipped unsafe sources:'] + (['- ' + x for x in plan['skipped_sources']] or ['- None'])
288
+ lines += ['', 'Changed paths in commits:'] + (['- ' + x for x in plan['paths']] or ['- None'])
289
+ lines += ['', 'Uncommitted changes:'] + (['- ' + x for x in plan['dirty']] or ['- None'])
290
+ lines += ['', 'Affected notes:'] + (['- ' + x for x in plan['affected_notes']] or ['- None'])
291
+ text = '# Knowledge sync status\n\n' + '\n'.join(lines) + '\n'
292
+ page = ('<!doctype html><html lang="en"><meta charset="utf-8">'
293
+ '<meta name="viewport" content="width=device-width, initial-scale=1">'
294
+ '<title>Knowledge sync status</title><style>body{font:16px/1.6 system-ui,sans-serif;'
295
+ 'max-width:70rem;margin:auto;padding:1.5rem;color:#222}pre{font:inherit;white-space:pre-wrap;'
296
+ 'overflow-wrap:anywhere}a{color:#164cb5}</style><h1>Knowledge sync status</h1>'
297
+ '<p>To read the spec, run <code>knowledge.py serve --repo .</code></p><pre>' + html.escape('\n'.join(lines)) + '</pre></html>')
298
+ for name, content in [('.knowledge/sync-plan.json', data), ('.knowledge/sync-status.md', safe_bytes(text)), ('sync.html', safe_bytes(page))]:
299
+ atomic(knowledge.output_path(vault, name), content)
300
+
301
+
302
+ def finish(repo, vault, plan_path, review_path):
303
+ """Return (message, exit code): 0 when the checkpoint advanced or nothing was pending, PARTIAL_EXIT (3, distinct from argparse's usage error 2) for a partial finish."""
304
+ plan_bytes = plan_path.read_bytes()
305
+ plan, review = json.loads(plan_bytes), json.loads(review_path.read_bytes())
306
+ if review.get('plan_sha256') != hashlib.sha256(plan_bytes).hexdigest():
307
+ raise ValueError('review does not match exact plan bytes')
308
+ with lock(vault):
309
+ now = scan(repo, vault, plan['target'])
310
+ if now['head'] != plan['head']:
311
+ hint = retarget_hint(repo, vault, plan['target'])
312
+ if hint:
313
+ raise ValueError(hint)
314
+ for key in ('repo', 'vault', 'git_dir', 'branch', 'head', 'target', 'base', 'cursor_sha256', 'baseline_sha256', 'commits', 'changes', 'paths', 'dirty', 'source_hashes', 'affected_notes', 'affected_areas', 'dirty_affected_notes', 'unmapped', 'skipped_sources'):
315
+ if now[key] != plan[key]:
316
+ raise ValueError('plan changed: ' + key)
317
+ if now['blockers'] or now['errors']:
318
+ raise ValueError('scan has blockers or structural errors: ' + '; '.join(now['blockers'] + now['errors']))
319
+ paths, notes = review.get('paths'), review.get('notes')
320
+ if not isinstance(paths, dict) or set(paths) != set(plan['paths']) or not isinstance(notes, dict) or set(notes) != set(plan['affected_notes']):
321
+ raise ValueError('receipt must cover exactly all integrated paths and affected notes')
322
+ for path, decision in paths.items():
323
+ if not isinstance(decision, dict) or decision.get('status') not in ('reviewed', 'excluded', 'deferred') or not isinstance(decision.get('reason'), str) or not decision['reason'].strip():
324
+ raise ValueError('path needs reviewed/excluded/deferred decision and reason: ' + path)
325
+ if path in plan['dirty'] and decision['status'] != 'deferred':
326
+ raise ValueError('dirty integrated path must be deferred (or cleaned and rescanned): ' + path)
327
+ ev = Evidence(repo)
328
+ excluded = ev.group([path for path, decision in paths.items() if decision['status'] == 'excluded'])
329
+ deferred_paths = {path: decision['reason'].strip() for path, decision in paths.items() if decision['status'] == 'deferred'}
330
+ deferred_group = ev.group(deferred_paths)
331
+ dirty_now = ev.group(now['dirty'])
332
+ baseline_file = vault / '.knowledge/sources.json'
333
+ baseline = json.loads(baseline_file.read_text()) if baseline_file.is_file() else {}
334
+ accepted, deferred_notes = [], {}
335
+ for ident, old in plan['notes'].items():
336
+ current = now['notes'].get(ident)
337
+ if current is None or current['path'] != old['path']:
338
+ raise ValueError('note set or path changed: ' + ident)
339
+ if ident in notes:
340
+ decision = notes[ident]
341
+ if not isinstance(decision, dict) or decision.get('status') not in ('updated', 'unchanged', 'deferred') or decision.get('expected_sha256') != current['sha256']:
342
+ raise ValueError('note requires updated/unchanged/deferred decision with expected hash: ' + ident)
343
+ if decision['status'] == 'deferred':
344
+ if not isinstance(decision.get('reason'), str) or not decision['reason'].strip():
345
+ raise ValueError('deferred note needs a reason: ' + ident)
346
+ deferred_notes[ident] = decision['reason'].strip()
347
+ continue
348
+ if decision['status'] == 'unchanged' and current != old:
349
+ raise ValueError('unchanged note was modified: ' + ident)
350
+ if any(ev.matches(excluded, source) for source in current['sources']):
351
+ raise ValueError('affected note cites excluded evidence: ' + ident)
352
+ for source in current['sources']:
353
+ evidence = knowledge.safe_path(repo, source)
354
+ if evidence.resolve() != repo / normalized(source):
355
+ raise ValueError('affected note cites aliased evidence; use its canonical path: ' + ident)
356
+ if ev.matches(dirty_now, source):
357
+ raise ValueError('affected note cites dirty evidence (mark the note deferred): ' + ident)
358
+ for source in list(current['sources']) + list(baseline.get(ident, {})):
359
+ if ev.matches(deferred_group, source):
360
+ raise ValueError('affected note cites a deferred path (mark the note deferred): ' + ident + ': ' + source)
361
+ if any(s not in plan['source_hashes'] or plan['source_hashes'][s] != now['source_hashes'].get(s) for s in current['sources']):
362
+ raise ValueError('new or changed source requires rescan: ' + ident)
363
+ accepted.append(ident)
364
+ elif current != old:
365
+ raise ValueError('unreviewed note changed: ' + ident)
366
+ if set(now['notes']) != set(plan['notes']):
367
+ raise ValueError('note set changed; rescan required')
368
+ validate_selected_evidence(repo, vault, accepted, plan['target'])
369
+ if not plan['paths']:
370
+ return 'no substantive integrated paths; cursor unchanged', 0
371
+ run_path = review.get('run_path')
372
+ if not isinstance(run_path, str) or not run_path.startswith('runs/') or not run_path.endswith('.md'):
373
+ raise ValueError('receipt requires a runs/*.md run_path')
374
+ run = knowledge.output_path(vault, run_path)
375
+ planned_run = next((n for n in plan['notes'].values() if n['path'] == run_path), None)
376
+ current_run = next((n for n in now['notes'].values() if n['path'] == run_path), None)
377
+ if not run.is_file() or not planned_run or not current_run or review.get('run_sha256') != digest(run) or planned_run['sha256'] != digest(run):
378
+ raise ValueError('run must exist at scan time and match its receipt hash')
379
+ run_notes, _, _, _, _ = knowledge.load_vault(repo, vault, freshness=False)
380
+ run_note = next((n for n in run_notes if n['path'] == run_path), None)
381
+ if not run_note or run_note['meta']['type'] != 'run' or run_note['meta'].get('review_base') != plan['base'] or run_note['meta'].get('review_target') != plan['target']:
382
+ raise ValueError('run note must identify the exact reviewed base and target')
383
+ partial = bool(deferred_paths or deferred_notes)
384
+ with tempfile.TemporaryDirectory(prefix='knowledge-sync-') as temp:
385
+ staged = Path(temp) / 'vault'
386
+ shutil.copytree(vault, staged, symlinks=True)
387
+ if accepted and knowledge.main(['snapshot', '--repo', str(repo), '--vault', str(staged), '--notes', *sorted(accepted)]) != 0:
388
+ raise ValueError('snapshot validation failed')
389
+ if knowledge.main(['check', '--repo', str(repo), '--vault', str(staged)]) != 0:
390
+ raise ValueError('structural check failed')
391
+ # Validate all output destinations before publishing anything.
392
+ outputs = ['.knowledge/sources.json', '.knowledge/review.json']
393
+ destinations = [knowledge.output_path(vault, p) for p in outputs]
394
+ cursor = json.loads((vault / '.knowledge/review.json').read_text())
395
+ checkpoint = cursor['reviewed_through']
396
+ cursor['reviewed_through'] = plan['target']; cursor['run_path'] = run_path
397
+ latest = scan(repo, vault, plan['target'])
398
+ for key in ('head', 'branch', 'cursor_sha256', 'baseline_sha256', 'source_hashes', 'dirty', 'notes'):
399
+ if latest[key] != now[key]:
400
+ raise ValueError('review changed before publication: ' + key)
401
+ validate_selected_evidence(repo, vault, accepted, plan['target'])
402
+ staged_baseline = json.loads((staged / '.knowledge/sources.json').read_text())
403
+ for ident in accepted:
404
+ expected = {source: now['source_hashes'][source] for source in now['notes'][ident]['sources'] if now['source_hashes'].get(source) is not None}
405
+ if staged_baseline.get(ident) != expected:
406
+ raise ValueError('staged evidence changed during snapshot: ' + ident)
407
+ backups = {dest: dest.read_bytes() if dest.exists() else None for dest in destinations}
408
+ written = []
409
+ try:
410
+ for name, dest in zip(outputs[:-1], destinations[:-1]):
411
+ atomic(dest, (staged / name).read_bytes()); written.append(dest)
412
+ if not partial: # the checkpoint moves only when nothing applicable is deferred
413
+ atomic(destinations[-1], jsonbytes(cursor)); written.append(destinations[-1])
414
+ except OSError:
415
+ for dest in reversed(written):
416
+ if backups[dest] is None:
417
+ dest.unlink(missing_ok=True)
418
+ else:
419
+ atomic(dest, backups[dest])
420
+ raise
421
+ if partial:
422
+ lines = [f'partial: accepted {len(accepted)} notes; deferred {len(deferred_paths)} paths, {len(deferred_notes)} notes; checkpoint stays at {checkpoint}']
423
+ lines += [f'deferred path {p}: {r}' for p, r in sorted(deferred_paths.items())]
424
+ lines += [f'deferred note {n}: {r}' for n, r in sorted(deferred_notes.items())]
425
+ return '\n'.join(lines), PARTIAL_EXIT
426
+ return 'review checkpoint advanced to ' + plan['target'], 0
427
+
428
+
429
+ def receipt(repo, vault, plan_path, out, run=None):
430
+ """Write a review receipt with every hash filled in and each status/reason left empty.
431
+
432
+ An existing receipt keeps the statuses and reasons already entered for entries that still apply.
433
+ """
434
+ plan_bytes = plan_path.read_bytes()
435
+ plan = json.loads(plan_bytes)
436
+ if plan.get('vault') != str(vault):
437
+ raise ValueError('plan was written for a different vault')
438
+ hint = retarget_hint(repo, vault, plan['target'])
439
+ if hint:
440
+ raise ValueError(hint)
441
+ previous = {}
442
+ if out.exists():
443
+ previous = json.loads(out.read_bytes())
444
+ if not isinstance(previous, dict):
445
+ raise ValueError('existing receipt is not a JSON object')
446
+ old_paths = previous.get('paths') if isinstance(previous.get('paths'), dict) else {}
447
+ old_notes = previous.get('notes') if isinstance(previous.get('notes'), dict) else {}
448
+
449
+ def kept(table, key, field):
450
+ entry = table.get(key)
451
+ value = entry.get(field) if isinstance(entry, dict) else None
452
+ return value if isinstance(value, str) else ''
453
+
454
+ plan_hash = hashlib.sha256(plan_bytes).hexdigest()
455
+ same_plan = previous.get('plan_sha256') == plan_hash # path dispositions belong to the plan they reviewed
456
+ def entered(table, key):
457
+ return bool(kept(table, key, 'status'))
458
+
459
+ count = {'kept_paths': 0, 'reset_paths': 0, 'kept_notes': 0, 'reset_notes': [], 'dropped_paths': 0, 'dropped_notes': 0}
460
+ for p in plan['paths']:
461
+ if entered(old_paths, p):
462
+ count['kept_paths' if same_plan else 'reset_paths'] += 1
463
+ count['dropped_paths'] = sum(1 for p in old_paths if p not in plan['paths'] and entered(old_paths, p))
464
+ count['dropped_notes'] = sum(1 for n in old_notes if n not in plan['affected_notes'] and entered(old_notes, n))
465
+ result = {'plan_sha256': plan_hash,
466
+ 'paths': {p: {'status': kept(old_paths, p, 'status') if same_plan else '', 'reason': kept(old_paths, p, 'reason') if same_plan else ''} for p in plan['paths']},
467
+ 'notes': {}}
468
+ for ident in plan['affected_notes']:
469
+ file = knowledge.safe_path(vault, plan['notes'][ident]['path'])
470
+ current = digest(file)
471
+ # A note disposition belongs to the exact bytes that were reviewed.
472
+ keep = kept(old_notes, ident, 'expected_sha256') == current
473
+ result['notes'][ident] = {'status': kept(old_notes, ident, 'status') if keep else '', 'expected_sha256': current}
474
+ if keep and kept(old_notes, ident, 'reason'):
475
+ result['notes'][ident]['reason'] = kept(old_notes, ident, 'reason')
476
+ if entered(old_notes, ident):
477
+ if keep:
478
+ count['kept_notes'] += 1
479
+ else:
480
+ count['reset_notes'].append(ident)
481
+ if run is not None:
482
+ run_path = run.resolve().relative_to(vault).as_posix() if run.is_absolute() else run.as_posix()
483
+ elif plan['paths']:
484
+ loaded, _, _, _, _ = knowledge.load_vault(repo, vault, freshness=False)
485
+ found = [n['path'] for n in loaded if n['meta']['type'] == 'run' and n['path'].startswith('runs/')
486
+ and n['meta'].get('review_base') == plan['base'] and n['meta'].get('review_target') == plan['target']]
487
+ if len(found) != 1:
488
+ raise ValueError(f'found {len(found)} run notes for this range; pass --run runs/NAME.md')
489
+ run_path = found[0]
490
+ else:
491
+ run_path = None
492
+ if run_path is not None:
493
+ if not run_path.startswith('runs/') or not run_path.endswith('.md'):
494
+ raise ValueError('run must be a runs/*.md path inside the vault')
495
+ file = knowledge.output_path(vault, run_path)
496
+ if not file.is_file():
497
+ raise ValueError('run note does not exist: ' + run_path)
498
+ result['run_path'] = run_path
499
+ result['run_sha256'] = digest(file)
500
+ atomic(out, jsonbytes(result))
501
+ message = f"receipt written: fill status and reason for {len(result['paths'])} paths and status for {len(result['notes'])} notes"
502
+ if any(count[k] for k in ('kept_paths', 'reset_paths', 'kept_notes', 'reset_notes', 'dropped_paths', 'dropped_notes')):
503
+ reset_paths = f" ({'plan changed since the receipt was written'})" if count['reset_paths'] else ''
504
+ reset_notes = f" (note file changed: {', '.join(count['reset_notes'])})" if count['reset_notes'] else ''
505
+ message += (f"\ndispositions kept: {count['kept_paths']} paths, {count['kept_notes']} notes; "
506
+ f"reset: {count['reset_paths']} paths{reset_paths}, {len(count['reset_notes'])} notes{reset_notes}; "
507
+ f"dropped (no longer in the plan): {count['dropped_paths']} paths, {count['dropped_notes']} notes")
508
+ return message
509
+
510
+
511
+ def main():
512
+ parser = argparse.ArgumentParser()
513
+ subs = parser.add_subparsers(dest='command', required=True)
514
+ rp = subs.add_parser('receipt')
515
+ rp.add_argument('--repo', required=True, type=Path); rp.add_argument('--vault', required=True, type=Path)
516
+ rp.add_argument('--plan', required=True, type=Path); rp.add_argument('--out', required=True, type=Path)
517
+ rp.add_argument('--run', type=Path)
518
+ for name in ('scan', 'finish'):
519
+ p = subs.add_parser(name); p.add_argument('--repo', required=True, type=Path); p.add_argument('--vault', required=True, type=Path)
520
+ if name == 'scan':
521
+ p.add_argument('--target'); p.add_argument('--write-status', action='store_true'); p.add_argument('--json', action='store_true')
522
+ else:
523
+ p.add_argument('--plan', required=True, type=Path); p.add_argument('--review', required=True, type=Path)
524
+ args = parser.parse_args(); repo = args.repo.resolve(); vault = args.vault.resolve()
525
+ if args.command == 'receipt':
526
+ print(receipt(repo, vault, args.plan, args.out, args.run))
527
+ elif args.command == 'scan':
528
+ report = scan(repo, vault, args.target)
529
+ if args.write_status:
530
+ with lock(vault): status(vault, report)
531
+ if not args.json:
532
+ print('plan_sha256:', digest(vault / '.knowledge/sync-plan.json'))
533
+ print(json.dumps(report, ensure_ascii=True, indent=2) if args.json else f"{report['state']}: {len(report['paths'])} integrated paths, {len(report['affected_notes'])} affected notes, {len(report['blockers']) + len(report['errors'])} blockers/errors")
534
+ else:
535
+ message, code = finish(repo, vault, args.plan, args.review)
536
+ print(message)
537
+ return code
538
+ return 0
539
+
540
+
541
+ if __name__ == '__main__':
542
+ try:
543
+ sys.exit(main())
544
+ except (OSError, ValueError, KeyError, TypeError, json.JSONDecodeError) as exc:
545
+ print('ERROR:', exc, file=sys.stderr); sys.exit(1)