$!jg % S r SSKJr SSKrSSKrSSKrSSKrSSKrSSKrSSK r SSK
r
SSK r SSK r SSK
r
SSKJr SSKJrJrJr SSKJr SSKJrJrJrJr \" \5 R7 5 R8 R8 r \ S- r \ S - r \ S
- r \ S - S - r!S
r"Sr#Sr$SS0r%Sr&Sr'Sr(Sr)SSSSSSSS.r*S S SS S S S.r+S S!1r,S"r-S# r.S$ r/S%r0S}S& jr1S~S' jr2SS( jr3SS) jr4SSS* jjr5S+S,.SS- jjr6SS. jr7S/ r8S0 r9Sq:S1 r;\Rx \#4SS2 jj5 r=SS3 jr>\#S4.SS5 jjr?S6 r@S7 rAS8 rBS9 rCSS: jrDSS; jrE\ R " S<\ R 5 rHSS= jrI\J" 1 S>k5 rKSS? jrLS@rMSArNSBrO\ R " SC5 rP\J" 1 SDk5 rQSSE jrRSSF jrSSSG jrTSSH jrU\M\NSI. SSJ jjrVSK\M\NSL. SSM jjrW\O\MSN. SSO jjrXSSP jrYSQ rZSR r[SS r\ST r]SU r^SSV jr_SSW jr`SX raSY rbSSZ jrcS[ rdS\ reS] rfS^rgS_rhSS` jriSa rjSb rkSc rlSdSeSfSgShSiS.rmSj\nSk' 1 SlkroSmrpSn rqSSo jrrSp rsSSq jrtSr ruSs rvSt rwSu rxSv rySw rzSx r{Sy r|Sz r}SS{ jr~\S|:X a \ GR " \~" 5 5 gg)u= notice — small stdlib CLI for Mission Control Notice Board. ) annotationsN)Counter)datetime timedeltatimezone)Path)urlparse
urlunparse parse_qsl urlencodez
brain.jsonzinbox.mdz render.pyscriptszvalidate_brain.pyz.notice-board.lockg >@)LearningResearchReadPersonal AdminIdeasDab Improvements
UncategorizedzResearch / Readr )InboxExploreDone) completeddroppedstalearchived graduatedread)
unexploredexplainer_readyr r r )linkidealearningprojectadminnoter r! r" r$ r% )r r r r r r r r r r r promoted needs_review) parent_ofchild_of forked_from
related_to merged_into artifact_ofc h [ R " [ R 5 R S5 $ )Nz%Y-%m-%dT%H:%M:%SZr nowr utcstrftime tools/notice.pyr0 r0 8 s! << % . ./C DDr4 c h [ R " [ R 5 R S5 $ )N%Y-%m-%dr/ r3 r4 r5 todayr8 < s << % . .z ::r4 u
← Item page
c T SU ; =( d SU ; =( d SU ; =( d SU ; $ )zKReturn true when a standalone explainer can navigate back to its item page.z href="./"z href='./'u
← Item pagez Back to itemr3 )htmls r5 _explainer_has_backlinkr; C s: t " $ " d " " T ! r4 c 6 U R SS9n[ U5 ( a gUR 5 nUR S5 nUS:X a gUR SU5 nUS:X a gUSUS- [
- XS- S - nU R
USS9 g ! [ a gf = f)
zInject a compact item-page backlink into explainer HTML if it is missing.
The backlink is intentionally inline-styled so it works across the varied
hand-authored/agent-authored standalone explainer styles.
utf-8encodingFzN T) read_textUnicodeDecodeErrorr; lowerfindEXPLAINER_BACKLINK_HTML
write_text)pathr: rE idxcloseupdateds r5 ensure_explainer_backlinkrM M s ~~w~/ t$$ JJLE
**W
C
by IIc3 E {:EAI !884
;KKGOOGgO. s B
BBc d U =( d SR 5 R 5 nUS; a U$ S$ )Nr inboxexploredonerP )striprE )statusss r5 lc_phaserV j s1 7!!#))+A111>w>r4 c ( [ 5 nXS' XS' g)z:Bump v3.0 last_modified_at + v2.1 updated_at in one place.
updated_atlast_modified_atN)r0 )itemtss r5 stamp_modifiedr\ o s B ! r4 c & U R S/ 5 nU=( d SU=( d U R SS5 [ 5 S.nU( a7 US R S5 US :X a US R S5 US :X a g UR U5 g )
u Record a new entry on ``item.sources`` (v3.0 audit list).
No-op if an identical (via, raw) pair already sits at the tail —
avoids ballooning the list on duplicate re-captures.
sourcesunknowntitle viarawatr@ rc rd N)
setdefaultgetr0 append)rZ rc rd r^ entrys r5
append_sourcerj v s~ ooi,G$9S-IDHHWb4IQTQV WE72;??5)U5\9gbkooe>TX]^cXd>d NN5r4 legacy) default_viac U R S[ R U R S5 S5 5 [ U R S5 5 U S' U R S5 ( d= U R S5 =( d" U R S5 =( d
[ 5 U S' U R S 5 ( dZ U R S
5 =( d UU R S 5 =( d S U R S5 =( d
[ 5 S
./U S ' U R S/ 5 U R S5 nU( a SU S3U S' U $ )zBackfill any missing v3.0 fields on an item dict.
Items minted before plan 03 may still lack these fields on the
transition path; ensure they're present before validation. Plan 04
adds ``folder_path`` (every item owns ``items//``).
typecategoryr% rT phaserY rX
created_atr^ sourcer` ra rb tagsslugitems// folder_path)rf CATEGORY_TO_TYPErg rV r0 )rZ rl rt s r5 ensure_v3_fieldsry s OOF , 0 0*1Ev NO TXXh /0DM 88& ' '#'88L#9#\TXXl=S#\WZW\
88I 88H%488G$*((<(1CE
Y
OOFB 88F D &tfA .] Kr4 c > [ S- U - nUR SSS9 U$ )zCreate ``items//`` if missing and return the Path.
Capture commands call this so a freshly-minted item always has its
folder on disk, even before the next ``render.py`` run.
itemsTparentsexist_ok)REPOmkdir)rt folders r5 ensure_item_folderr s' G^d
"F
LLL- Mr4 c P [ R " [ R SS95 $ )Nr= r> )jsonloadsBRAINrC r3 r4 r5 loadr s ::eoowo7 88r4 c t [ 5 U S' [ R [ R " U SSS9S- SS9 g) u Direct write — DO NOT call from mutating commands. Use ``transaction``.
Retained as a low-level building block for transaction() and any one-off
administrative script that already holds the lock.
rX Findent ensure_ascii
r= r> N)r0 r rH r dumps)bs r5 saver s5 eAlO TZZ!%@4GRYZr4 c [ cN [ [ S- 5 n U [ R ; a [ R R SU 5 SSKJn Uq [ $ )zEImport scripts.validate_brain.validate_brain on demand (stdlib-only).r
r )validate_brain)_validate_brain_fnstrr sysrI insertr ) scripts_dirvbs r5 _load_validatorr sF !$*+ chh & HHOOA{ +7 r4 c # t # [ R [ - n[ R " [ U5 [ R [ R - S5 n [ R " 5 U - n [ R " U[ R [ R - 5 Sv [ R " U[ R" 5 [ R$ " U5 g! [ aE [ R " 5 U: a [ SU SU S S35 e[ R " S5 Of = fM ! [ R$ " U5 f = f! [ R " U[ R" 5 [ R$ " U5 f ! [ R$ " U5 f = f= f7f)a Cross-process exclusive lock via fcntl.flock on ``.notice-board.lock``.
The lock file sits next to ``brain.json`` so test sandboxes (which override
``BRAIN``) get their own lock and do not contend with the live CLI.
Linux ``flock`` releases automatically on process death, so stale lock
files left behind by a crash do not need cleanup. We poll non-blockingly
so we can enforce a soft timeout instead of hanging forever.
i znotice: could not acquire z within z.0fz*s; another notice CLI write is in progressg?N)r parent LOCK_NAMEosopenr O_RDWRO_CREATtime monotonicfcntlflockLOCK_EXLOCK_NBBlockingIOError
SystemExitsleepLOCK_UNrK )timeout lock_pathfddeadlines r5
_file_lockr s4 y(I Y RZZ!7 ?B>>#g-
! B
=> KKEMM * HHRL #
!>>#x/$4YKxPS} UB B
4
!
HHRL KKEMM * HHRLBHHRLsm AF8E 56C- +E 1%E F8-A D<9E ;D<<E EF8 F5 %FF5F22F55F8c 0 U R nUR SSS9 [ R " U R S- S[ U5 S9u p4 [ R " USSS9 nUR U5 UR 5 [ R " UR 5 5 S S S 5 [ R " U[ U 5 5 g ! , ( d f N/= f! [ a) [ R " U5 e ! [ a e f = ff = f)
zEWrite ``data`` to ``path`` atomically (write tmp, fsync, os.replace).Tr| .z.tmp)prefixsuffixdirwr= r> N)r r tempfilemkstempnamer r fdopenwriteflushfsyncfilenoreplace
BaseExceptionunlinkOSError)rI datar r tmp_namefs r5 _atomic_write_textr s
[[F
LLL-##499s?6sSY{[LB
YYr3
1Q
GGDM
GGI HHQXXZ 2
8SY' 2
1
IIh
sI C" "AC((C"
C C" "
D-DD
DDDD)r c
[ 5 n[ U5 [ R " [ R SS95 n [ R SS9nU" U5 n[ U[ 5 ( a [ U5 S:X a Uu pxOUSp[ 5 US' U" USS9n U ( a SS R U 5 - n
[ U
5 eUn U( a [ 5 n US
U S U S U S
3- n [ [ [ R " USSS9S
- 5 X:w a [ [ U 5 UsSSS5 $ ! [ a Sn Nf = f! , ( d f g= f)u Run a single read → mutate → stage-audit → validate → atomic-write cycle.
Inside the cross-process lock:
1. Read a fresh brain.json so waiters see prior committed writes.
2. Read the current inbox.md text (or '' if absent).
3. Invoke ``mutate(brain)`` to apply the change in memory.
4. Stage the audit append in memory — do NOT touch inbox.md yet.
5. Validate the staged brain dict via
``scripts.validate_brain.validate_brain``. On any failure, abort
BEFORE writing either file, so brain.json and inbox.md remain
byte-identical to their pre-transaction state.
6. Atomically replace brain.json with the new text.
7. Atomically replace inbox.md with the staged text.
``mutate`` may return:
- None : no audit entry, no caller payload
- str detail : audit detail string, no payload
- (detail, payload) : audit detail + payload returned to caller
Two-file atomicity caveat: POSIX gives us atomic single-file
``rename()`` via ``os.replace``, not multi-file atomic commit. If the
process is killed between steps 6 and 7, brain.json may be updated
while inbox.md is not. The reverse (inbox without brain) is impossible
because inbox is written last. This is acceptable for an
append-only audit log: missing one trailing line is recoverable from
the brain.json diff, while a phantom inbox entry for a write that
never happened would be worse. Validation failures — the common
failure mode — never write either file.
r= r> ra r NrX )rootuB notice: transaction aborted — brain.json validation failed:
- z
-
## — notice CLI ·
- r Fr )r r r r r rC INBOXFileNotFoundError
isinstancetuplelenr0 joinr r r )
actionmutater validatorbrainexisting_inboxresultdetailpayloaderrsmsg new_inboxstamps
r5 transactionr sC > !I G
5??G?<= "__g_ >N fe $ $V)9 $OFG $dG !el T* WZbZgZghlZmmC S/ !" EE&w 1&xrJI JJuQU ;d B
& ui 0?
! N
s/ (D;D)C
D;) D85D;7D88D;;
E c [ R " SSU R 5 R 5 5 R S5 S S =( d S$ )Nz
[^a-zA-Z0-9]+-< rZ )resubrS rE rU s r5 rt rt > s:
66"C ): ; A A# Fs K UvUr4 c P ^ [ U4S jU R S/ 5 5 S 5 $ )Nc 3 T ># U H oR S 5 T:X d M Uv M g7f)
display_idNrg ).0xis r5 find..C s# K .q%% 2E2J . ( (r{ nextrg )r r s `r5 rF rF B s! KAEE'2 .KT RRr4 c P ^ [ U4S jU R S/ 5 5 S 5 $ )Nc 3 T ># U H oR S 5 T:X d M Uv M g7frt Nr )r r rU s r5 r find_by_slug..G s" E .q%%-12D .r r{ r )r rU s `r5 find_by_slugr F s! EAEE'2 .Et LLr4 c
[ R SSS9 nUR S[ 5 SU SU S35 S S S 5 g ! , ( d f g = f)Nar= r> r r r r )r r r r0 )r r r s r5 auditr J sD C' *a %w 1&xrJK
+ * *s $A
Ac U [ ; a U $ U [ ; a* [ U n[ SU SU S3[ R S9 U$ [ SU SSR
[ 5 35 e)zJTolerate legacy 'Research / Read' input by silently migrating to Research.note: 'z&' is a legacy category; recording as ''filezunknown category: . allowed: , )
CATEGORIESLEGACY_CATEGORY_MAPprintr stderrr r )rd news r5 _resolve_categoryr O sk
j
!!!#&
u B3%qIPSPZPZ[
)#k$))J:O9PQ
RRr4 c U c gU S:X a [ S[ R S9 gU [ ; a [ SU S3[ R S9 gU [ ; a$ [ SU S S
R
[ 5 35 eU $ ) z