Pipeline जो भी artifact बनाती है — वह कहाँ रहता है, उसे कौन validate करता है, और क्या delete करना सुरक्षित है।

Work directory (--work) वह जगह है जहाँ pipeline का बनाया हर artifact रहता है। जिस-जिस repository का दस्तावेज़ बना रहे हैं, हर एक के लिए एक।

<work>/
  phase1/
    graph.json          the call graph — everything downstream reads this
    functions.csv       every function, flat, for grepping or a spreadsheet
    graph.dot           Graphviz:  dot -Tsvg graph.dot -o graph.svg
    dropped-calls.json  calls we could NOT resolve, categorized — not hidden
    scan-coverage.json  files we could NOT read or fully parse — not counted as covered
  phase2/
    cards/<rel>.json    one card per source file, mirroring the source tree
    cards/_coverage.json  how many files got prose, and which did not
    cards/_rejected/    replies that produced no usable card (capped at 20)
    skeleton.yaml       the stage spine
    assignment.json     file → stage
    organization.yaml   intra-stage groups + reading order
    strategy.json       which strategy produced the above
  phase3/
    narration.json      stage and system prose
    registers.json      cross-stage state registers
    cache/              content-hash caches for prose and registers
  handbook/             the rendered output, once you run `render`
  run-manifest.json     model, phases, timings and token usage of the last good run

तीन properties जिन पर भरोसा करने लायक़ है

हर चीज़ पढ़ते समय schema-validated है

हर artifact में एक version field होता है और load होते समय वह zod से validate किया जाता है। Corrupt या hand-edited artifact ज़ोर से fail होता है और अपना नाम ख़ुद लेता है:

handbook: error: work/myrepo/phase2/skeleton.yaml: stages.3.id: Invalid

वह कभी किसी बाद के phase में नहीं फैलता।

दो जान-बूझकर रखे गए अपवाद — दोनों ढिलाई नहीं, resilience के बारे में हैं:

Cards — एक अकेली unparseable card file skip होती है, fatal नहीं। वरना cards directory में पड़ा एक बाहरी या आधा-synced JSON resume को, phases 2b/2c/3 को और हर model load को crash कर देता।
graph.json का languages metadata — optional है, क्योंकि यहाँ कोई artifact migration mechanism नहीं है और fidelity declarations के आने से पहले लिखा गया हर graph आगे भी validate होते रहना चाहिए। unparsedFiles भी इसी वजह से optional है: उसका न होना यह कहता है कि analysis इस record से पुरानी है, यह नहीं कि कुछ विफल ही नहीं हुआ।

हर write atomic है

पहले temp file में लिखो, फिर rename करो। Write के बीच में आया crash कभी आधी-लिखी artifact नहीं छोड़ता जिस पर अगला run अटक जाए।

generate और resync एक ही re-entrant directory lock लेते हैं। एक ही artifacts पर एक concurrent CLI run और Studio job की writes आपस में गुँथ जातीं; इसके बजाय दूसरे को एक साफ़ message के साथ refuse कर दिया जाता है।

क्या करना सुरक्षित है

Action	सुरक्षित?	Note
पूरी work dir delete करना	✅	इसके बाहर कुछ modify नहीं हुआ था। शुरू से regenerate करें।
इसे git में commit करना	✅	यह सब text है। यह review करने के काम आती है कि regeneration ने क्या बदला।
`phase3/cache/` delete करना	✅	अगले run पर पूरी re-narration की क़ीमत चुकानी होगी।
`phase2/cards/_rejected/` delete करना	✅	सिर्फ़ diagnostics। नए cards pass की शुरुआत में अपने-आप साफ़ हो जाता है।
`skeleton.yaml` hand-edit करना	✅	यह पढ़ते समय validate होता है, और `--skeleton` ठीक इसी के लिए मौजूद है।
`graph.json` hand-edit करना	⚠️	यह generated है। इसके बजाय `analyze` दोबारा चलाएँ।
`phase2/strategy.json` delete करना	⚠️	अगला run `file` पर गिर जाता है, जो शायद artifacts से मेल न खाए।
इसे publicly share करना	⚠️	Cards आपका source quote और describe करते हैं। इसे source की तरह ही treat करें।

इसे हाथ से पढ़ना

दिलचस्प चीज़ graph ही है:

# how big is this codebase, really
jq '.metadata | {files: (.scannedFiles|length), nInternalFunctions, nEdges}' phase1/graph.json

# the busiest functions — where a change is most likely to fan out
jq -r '.nodes | to_entries | map(select(.value.kind=="internal"))
       | sort_by(-.value.nCallers) | .[:15]
       | .[] | "\(.value.nCallers)\t\(.value.qualname)\t\(.value.file)"' phase1/graph.json

# what could not be resolved, by category
jq '.metadata.byCategory' phase1/dropped-calls.json

# which files the scan could not turn into facts, and why
jq '.metadata.byReason, .files' phase1/scan-coverage.json

# which files never got prose
jq '.missing' phase2/cards/_coverage.json

functions.csv भी इसी वजह से है — कभी-कभी सबसे तेज़ tool एक spreadsheet ही होती है।

दोनों coverage files अलग-अलग सवालों के जवाब देती हैं

_coverage.json इसका जवाब देती है कि "model किन files का वर्णन नहीं कर पाया?"। scan-coverage.json उसके नीचे बैठे सवाल का जवाब देती है: "parser किन files को शुरू में पढ़ ही नहीं पाया?" — unreadable, unparsable या partial में से एक reason के साथ।

पहली दो से कोई facts नहीं आते, इसलिए वे graph.json की scannedFiles से भी हटा दी जाती हैं: downstream कुछ भी ऐसी file का card लिखकर उसे described नहीं गिनता जिसे किसी ने खोला तक नहीं। partial files बनी रहती हैं — tree-sitter syntax error से उबर आया था, और उसे जो functions मिले वे असली हैं, बस अधूरे।

ख़ाली files array का मतलब है कि हर scanned file साफ़-साफ़ parse हुई। यह एक दावा है; artifact का सिरे से ग़ायब होना दावा नहीं।

और कहाँ-कहाँ लिखा जाता है

Handbooks work directory के बाहर ठीक दो जगह लिखता है, दोनों आपके चलाए command से opt-in:

<source>/.handbook-patches/ — apply इसे बनाता है; इसमें backups और उनके manifests रहते हैं। इसके भीतर अपने-आप एक .gitignore लिख दिया जाता है ताकि backups कभी git में न जाएँ।
$HOME/.handbook-studio/ — Studio की repository registry और उसकी auto-created work dirs। --state-dir से इसे कहीं और ले जाएँ।

वर्क डायरेक्टरी