agentleFS
samwelmungasamwelmunga/jenga-npm/.agents/skills/j-uncharted/SKILL.md

j.uncharted

Skill0 starsChanged 23 days agoApache-2.0View on GitHub

Investigate code that has no Jenga board provenance — a foreign file, an external source being pulled in, or an entire pre-existing codebase — and give it a consistent understanding document plus proper board representation.

  • Deletes or force-pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

30 rules. About 0 are common, 10 are distinctive, and 20 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 20

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every mode runs the same shared investigative engine and emits the same understanding document.

    line 45
  2. Very specific:

    If the mode is one of segment, import, onboard, or refresh, dispatch to that section below.

    line 64
  3. Distinctive:

    If the mode is missing or unrecognised, do not guess.

    line 65
  4. Distinctive:

    If a mode is given but its target is missing, ask for the target the same way — a numbered list of plausible candidates where they can be …

    line 66
  5. Very specific:

    All three modes call the same engine rather than reimplementing analysis.

    line 73
  6. Very specific:

    Do not restate in prose what these scripts do step by step, and do not reimplement their logic inline.

    line 109
  7. Very specific:

    Every mode produces exactly one document per target, rendered from skills/j-uncharted/assets/UNDERSTANDING_DOC_TEMPLATE.md.

    line 117
  8. Distinctive:

    Read the document and the stderr notices.

    line 143
  9. Distinctive:

    Leave the headings alone.

    line 146
  10. Very specific:

    Read ignored (already excluded by .gitignore, or matching the fixed vendor/generated pattern list — see the script's own header for the …

    line 185
  11. Very specific:

    Write the node directly with a hedged, low-confidence description, reusing the exact hedging convention the Human-Oracle-Availability …

    line 250
  12. Very specific:

    Call elicitation-state.sh converge directly — do not call elicitation-state.sh turn for this node.

    line 251
  13. Very specific:

    Step 0 — choose a mode: If --mode is given, skip straight to that mode's subsection below.

    line 328
  14. Very specific:

    Call the engine once, unwrapped.

    line 378
  15. Distinctive:

    Step 7 — Write the accepted items to the board: Only reachable from option 1, and only after any blocking Open Question is resolved.

    line 416
  16. Distinctive:

    Step 3 — Convergence loop: Run the shared Convergence Loop procedure above.

    line 452
  17. Very specific:

    Run segment's Step 1 (resolve-segment-target.sh) against $DESTINATION for its board-linkage status.

    line 607
  18. Very specific:

    Run segment's Step 2 (run-engine.sh --mode segment "$DESTINATION" --origin "imported from $(echo "$SUMMARY_JSON" | jq -r .source)") — …

    line 610
  19. Very specific:

    Read PROVENANCE_JSON's license, spdx_identifiers, copyright, and git_origin sections, plus overall.message, and fold every finding — and …

    line 616
  20. Very specific:

    Verifying the read-only guarantee: After a full onboard run (discovery → cap → epic generation) against a repository containing application …

    line 818
  21. Very specific:

    Every line must start with a path under project/.

    line 825
  22. Distinctive:

    Either section has real, non-stub content: Never overwrite it by default.

    line 913
  23. Distinctive:

    Ask this once per affected section if only one of the two is non-stub, or once covering both if both are.

    line 925
  24. Very specific:

    Step D — Write, scoped to exactly what was confirmed: Only the scrum-master writes, only to project/PROJECT_SUMMARY.md, and only the …

    line 933
  25. Very specific:

    refresh introduces no new understanding mechanism: Every node, epic, story, and task it writes goes through exactly the same write paths …

    line 969
  26. Very specific:

    Read find-scan-baseline.sh's and diff-since-baseline.sh's own header comments before invoking either — their exact flag names and exit-code …

    line 978
  27. Very specific:

    Exit 0, "source": "inferred": No scan-record exists, but a provenance: backfilled epic or an [ARCH]-tagged board item whose docs: …

    line 1002
  28. Very specific:

    unchanged candidates are skipped entirely: No Familiarity Check, no Directory Triage entry, no prompt of any kind — they never enter the …

    line 1042
  29. Very specific:

    If the item is already in a terminal status (Passed, Passed with remarks, Rejected, Done, Blocked), set reopened_on/reopened_reason per the …

    line 1088
  30. Distinctive:

    Never invent findings: If

    line 1176

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Uncharted — Investigative Workflow for Foreign & Pre-Existing Code

skills/j-uncharted/ is the canonical, hand-edited directory for this skill, per CLAUDE.md's "The Canonical Naming Contract" (the E50 reopening of 2026-09-09, which promoted skills/j-uncharted/ from generated twin to sole canonical form). The j- prefix is there for collision safety — a real directory under a distinct name, so a host tool shipping its own same-named built-in command cannot shadow it (Claude Code's native skill resolution is a literal-string, directory-name-based match; see project/documentation/skill-authoring.md's "Invocation Convention").

⚠️ scripts/generate-j-alias.sh was retired by E50_S14 and no longer exists — there is nothing to run. This file was previously generated from a bare skills/uncharted/SKILL.md source; E50_S15 deleted that directory. This file is now the sole canonical, hand-edited source for this skill — edit it directly.

/uncharted is the entry point for code with no board provenance — code that was never planned, decomposed, or executed through the Jenga workflow.

It fills a gap the existing investigative skills leave open:

SkillInvestigatesRequires
/deep-diveideas and proposalsno code target
/improvethe current codebasean explicit goal
/redoprior implementationsexisting board history
/unchartedcode with no board historynothing but a target

Every mode runs the same shared investigative engine and emits the same understanding document. The modes differ only in scale and in what happens after the analysis.


Invocation Contract

/uncharted <mode> [target]
ModeScaleWhat it doesImplemented by
segmentone file, directory, or featureTwo explicit modes since E20_S08_T03: --mode delivery (default, unchanged) analyses a target already in the repo and proposes a standard epic/story/task; --mode investigate opens a conversational architecture-investigation flow instead. See segment below for the mode choice.E40_S02 / E20_S08_T03
importan external sourceAcquires a git URL, an out-of-repo path, or a pasted snippet into the repo at a user-confirmed location, then hands off to segment.E40_S03
onboardthe whole codebaseConversational by default since E20_S08_T03: discovery scripts seed a human-in-the-loop elicitation that writes [ARCH]-tagged board items and coarse graph nodes. --legacy reproduces the original fully-automated, zero-prompt, capped-backfilled-epic pass unchanged. Board/graph-only — never touches application code, in either mode.E40_S04 / E20_S08_T03
refreshthe delta since a prior scanIncremental re-scan for an already-onboarded codebase. Locates a baseline (a committed scan-record, or one inferred from board evidence, or — if neither exists — falls back to a full onboard run), diffs the codebase against it, and routes only changed/new candidates through onboard's own mechanics — same bare-vs---legacy split, same Convergence Loop, same backfilled-epic writer. removed candidates are never silently dropped: their graph node(s) are marked superseded and the corresponding board item is flagged for review. Board/graph-only — never touches application code, in either mode. See refresh below.E40_S07

Dispatch rules:

  1. If the mode is one of segment, import, onboard, or refresh, dispatch to that section below.
  2. If the mode is missing or unrecognised, do not guess. Present the four modes as a numbered choice list with a free-text option last, per the Interaction Pattern in CLAUDE.md.
  3. If a mode is given but its target is missing, ask for the target the same way — a numbered list of plausible candidates where they can be inferred, free-text last.
  4. Never widen scope across modes in one invocation. Two, and only two, handoffs are part of a mode's own contract rather than a violation of this rule: import may hand off to segment (E40_S03_T03), and refresh may fall back to running onboard in full when no baseline exists for the requested root (see refresh below, and onboard's own Invocation Contract row). Nothing else chains implicitly.

Shared Investigative Engine

All three modes call the same engine rather than reimplementing analysis. Per the Skill Implementation Principle in CLAUDE.md, the deterministic work lives in scripts under skills/j-uncharted/scripts/, not in this file:

ScriptResponsibilityImplemented by
enumerate-target.shResolves a target to file / directory / repo-root and emits its structure as JSON. Respects .gitignore; supports a --max-depth bound.E40_S01_T02
detect-dependencies.shSeparates internal from external dependencies; lists manifests found in or above the target.E40_S01_T03
detect-tests.shReports whether tests actually cover the target, distinguished from "the repo has tests but none reference it".E40_S01_T03
run-engine.shMode-agnostic entry point. Invokes the three detectors above, merges their JSON, renders the understanding document, and prints the written path on stdout.E40_S01_T04

Invoke run-engine.sh, never the individual detectors. It is the only supported entry point; calling a detector directly gets you raw JSON and no document.

DOC=$(bash skills/j-uncharted/scripts/run-engine.sh --mode segment <target>)
OptionEffect
--mode segment|import|onboardMode hint. Default segment. Reflected in the filename and the document's Target section. onboard also defaults the tree depth to 2, because it is coarse-first by design.
--max-depth NTree depth bound (default 3, or 2 for onboard; 0 = unlimited). Bounds the tree only — file and line counts always cover the whole target.
--top NHow many largest-files rows to report. Default 10.
--no-gitignoreEnumerate .gitignore'd content too. Needed when import has staged a source into an ignored path.
--origin "<text>"Value for the Target section's Origin row. import mode passes its acquired source here, e.g. --origin "imported from https://…". Defaults to in-repo, or an explicit "outside this repository" when the target is.
--out-dir <dir>Override the output directory. Default project/rapports/analysis/.
--json-out <file>Also write the merged detector JSON, for when you want to reason over the raw evidence rather than the rendered prose.
--template <file>Override the document template. Present for testing; production runs use the default.

Streams. stdout is exactly one line — the absolute path of the written document — so DOC=$(…) is safe. Detector notices, skipped paths, and render warnings go to stderr. Read the stderr. It is where "4 hidden directories were skipped", "reference names truncated to the first 300", and "this target is not inside a git repository" show up, and each of those changes how much weight the document's findings deserve.

ExitMeaningWhat to do
0Document writtenProceed; the path is on stdout.
1Usage errorFix the invocation. Do not retry blindly.
2Target does not exist or is unreadableRe-resolve the target with the user; in segment mode this usually means the free-text description resolved to nothing.
3A detector was missing or failedSurface the forwarded stderr to the user. Do not hand-write a document to work around it.
4Render or write failureTemplate missing, --out-dir or --json-out directory unwritable, or the rendered document failed its seven-heading self-check. Report it; nothing is left behind — both destinations are checked before any detector runs, and the document is the last thing written.

Do not restate in prose what these scripts do step by step, and do not reimplement their logic inline. Read the document (and --json-out when you need the raw evidence) and reason about it — that is the part that needs an agent.

Note: the engine is live as of E40_S01. segment (E40_S02), import (E40_S03), and onboard (E40_S04) are all complete end to end — resolution or acquisition through to board write and handoff, in each mode's own terms.


Output: the Understanding Document

Every mode produces exactly one document per target, rendered from skills/j-uncharted/assets/UNDERSTANDING_DOC_TEMPLATE.md.

Where it goes: project/rapports/analysis/, named uncharted-<mode>-<slug>-<YYYYMMDDTHHMMSSZ>.md. Nothing is ever overwritten — a name collision gets a -2, -3… suffix, so repeated runs against one target leave a diffable history.

This reuses the existing analysis rapport type already defined in $([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md). /uncharted introduces no new rapport type — if a change to the rapport taxonomy ever seems necessary, that is a schema change to be raised with the scrum-master, not something this skill invents.

Fixed structure — seven headings, never added to, removed, reordered, or renamed, because downstream steps read the document by heading:

## Target · ## Purpose · ## Structure · ## Key Dependencies · ## Existing Tests · ## Risk Areas · ## Open Questions

The engine enforces this itself: a render that would drop a heading exits 4 instead of writing. Diagnostics have nowhere to live in that structure, which is exactly why they go to stderr rather than being appended as an eighth section.

Two classes of section, treated differently:

SectionClassFilled by
TargetMechanicalEngine — resolved path, target type, mode, board linkage, origin
StructureMechanicalEngine — file count, per-extension table, bounded tree, largest files
Key DependenciesMechanicalEngine — internal vs external, plus manifests found in or above the target
Existing TestsMechanicalEngine — coverage signal, referencing test files, runner configuration
PurposeJudgementYou, from the mechanical evidence
Risk AreasJudgementYou, from the mechanical evidence
Open QuestionsJudgementYou, from the mechanical evidence

The engine emits the three judgement sections as explicit _TODO(agent):_ placeholders and must never fabricate them. After the engine runs:

  1. Read the document and the stderr notices.
  2. Replace each _TODO(agent):_ line, citing what the mechanical sections actually found — a specific untested file, a named dependency, an oversized module.
  3. Where the evidence does not support a conclusion, say so under Open Questions and name who could answer it. That is a valid result, not a failure.
  4. Leave the headings alone.

Two signals deserve particular attention because they are easy to misread:

  • Coverage is reported as covered, repo_tests_only, or no_tests_in_repo. "The repo has tests but none touch this target" is a finding about this target, not about the repo's testing culture — do not soften it into "the project has tests".
  • Board linkage says unlinked when no board item mentions the target's path. That is the whole reason /uncharted exists; it is the starting condition, not a problem to report.

A document whose judgement sections are generic enough to apply to any codebase has failed its purpose. Ground every claim in something the scripts actually found.


Conversational Elicitation

Since E20_S08_T03, onboard's default behavior and segment --mode investigate both run a human-in-the-loop conversational elicitation instead of (or, for onboard, in addition to keeping available) a one-shot deterministic pass. This section defines the mechanics shared by both; each mode's own subsection below only describes what is specific to it.

What conversational elicitation produces, and how that differs from the Understanding Document above: the primary output is coarse-tier graph nodes/edges — written directly to project/knowledge-graph/graph.json, conforming to the stub schema at project/knowledge-graph/STUB_SCHEMA.md (E20_S08_T01; this is a throwaway pilot schema, swapped wholesale once E20_S01's real schema lands — do not extend it expecting stability). Every node this flow writes carries source: "human", since it comes from a person confirming or correcting a proposed understanding, not from mechanical extraction. Board representation is a [ARCH]-tagged epic, story, or task at whichever level fits the investigated scope (see $([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)'s [ARCH] — Durable Architectural Inventory convention) — not the delivery-shaped epic/story/task proposal segment --mode delivery and legacy onboard produce, and not the fixed 7-heading Understanding Document either. A written summary is produced only when warranted, filed as the resulting board item's ordinary -summary.md — there is no new artifact type or separate "Understanding Document" for conversational output.

Human-Oracle-Availability Limitation

Read this before running a conversational elicitation on code nobody currently understands. This is /uncharted's own documented, standing, accepted limitation — not only agents/developer.md's and agents/tester.md's (E20_S08_T02 covers those; this is the skill's own copy of the same limitation, since the person driving /uncharted may never open either agent file directly).

For genuinely undocumented code, there is often no reliable human oracle to confirm or correct a proposed understanding — the person answering may not know either, or may confidently confirm a wrong answer. Per the parent story's own scrutiny (scored 3/10 on this exact point) and its solution assessment's disposition ("Accept and Descope" on Problem 1): conversational elicitation does not solve this, and does not claim to. It is a complementary path for codebases where some human context exists, not a fix for the hardest, genuinely zero-oracle case.

  • The deterministic pipeline remains the tool of record for zero-oracle codebases. onboard --legacy and segment --mode delivery never depend on anyone confirming intent — they ground everything in mechanical evidence (file structure, dependencies, test coverage) and say so explicitly under Open Questions when the evidence doesn't support a conclusion. When there is no one left who understands the code, reach for one of those, not the conversational flow.
  • When running the conversational flow, do not manufacture confidence. If the user's answer is uncertain, hedged, or contradicts what discovery/Investigative Mode found, write the node honestly — do not round an uncertain answer up to a confirmed one. There is no schema field yet to tag confidence (the stub schema is intentionally minimal); until one exists, say so in the node's description text itself (e.g. "per the user, this module retries failed charges — unconfirmed against the code, which shows only a single retry attempt") rather than silently dropping the caveat.
  • verification_depth: strict is this guidance's concrete implementation, not a separate idea (E40_S06_T02). When a candidate's Familiarity Check answer is No (Convergence Loop Step 1), Step 4's risk-weighted gating never lets an escalating finding round up to a false confirmation by asking the user to bless it — it auto-flags the node with exactly the hedged-description convention this bullet describes and converges it without a prompt. This bullet states the principle; Step 4's strict branch is what enforces it mechanically, so the two sections should be read as one mechanism, not two independently-arrived-at claims.
  • A confidently wrong answer is not detectable by this flow. Corroboration against a second signal (commit history, existing docs, a second person) is the only mitigation, and it is not built here — this is the accepted residual risk, not a gap to engineer around mid-conversation.

Directory Triage

Runs once per elicitation, between discovery and the first Investigative Mode dispatch — never skipped, and never silently absorbed into the convergence loop below, because triaging noise out is exactly what keeps that loop from wasting turns (and the user's attention) on vendor/generated directories nobody wants a graph node for.

Step 1 — deterministic pass. Feed the candidate directories (from discover-subsystems.sh's output for onboard, or the target's immediate subdirectories for segment --mode investigate) to:

discover-subsystems.sh <root> | jq -r '.candidates[].path' \
  | bash skills/j-uncharted/scripts/directory-triage.sh <root>

Read ignored (already excluded by .gitignore, or matching the fixed vendor/generated pattern list — see the script's own header for the full list) and remaining. This is a mechanical classification; do not second-guess it or re-run judgement over an ignored entry.

Step 2 — judgement pass over remaining. This is the generalize-list the deterministic pattern list can never catch: content-based cases where a directory is legitimately noise or a single coarse unit for reasons a pattern match cannot see — the task's own example is "this directory is SOAP request mock-ups for a test suite." Skim remaining (directory names, a shallow listing, README/comment hints) and propose, for each one that looks like a generalize candidate, a single-sentence rationale and the disposition: exclude (like ignored, zero graph nodes) or generalize (one coarse-tier node covering the whole directory, no per-file drill-down, no Investigative Mode dispatch into it). Everything not proposed for either disposition proceeds to full investigation.

Step 3 — one confirmation gate, both lists together. Per the task's own acceptance criterion, both the deterministic ignore-list and the judgement-based generalize-list are confirmed with the user before any developer/tester Investigative Mode dispatch — not after, and not as two separate gates:

Directory triage for <target>:

Excluded (pattern/gitignore match) — N directories:
<path> — <reason>
...

Proposed for exclusion or generalization (judgement) — M directories:
<path> — exclude|generalize — <one-line rationale>
...

Everything else (K directories) proceeds to investigation.

How should this be applied?
1. Accept as proposed
2. Revise — change a disposition before proceeding
3. Show me the full excluded/generalize lists in detail
4. Other (describe below)

Silence, a counter-question, or an ambiguous reply is not consent — re-ask, the same convention used at every other confirmation gate in this skill. Option 3 does not count as a decision; re-present the same choice after showing the detail. Checkpoint the confirmed triage result immediately via elicitation-state.sh checkpoint (see Multi-Session Persistence below) so a paused-and-resumed session never re-asks a question the user already answered.

Convergence Loop

Runs once per surviving candidate (a subsystem, a named flow, a directory) after Directory Triage. This is the "propose understanding, ask the user to confirm or correct" cycle at the center of the redesign — and the one the scrutiny flagged as having no termination bound and no defense against confirmation fatigue. Both gaps are closed mechanically, not by agent discipline alone:

  1. Familiarity Check — once per candidate, before Investigative Mode dispatch. Ask (per the Interaction Pattern in CLAUDE.md — numbered list, free-text last):

    Are you familiar with this service/segment?
    1. Yes
    2. A little
    3. No
    4. Other (describe below)

    Silence, a counter-question, or an ambiguous reply is not consent — re-ask, the same convention used at every other confirmation gate in this skill. Map the answer to a verification_depth scoped to this candidate only — Yes → shallow, A little → moderate, No → strict — and persist it immediately, keyed by this candidate's node id, via elicitation-state.sh's checkpoint mechanism (see Multi-Session Persistence below for the exact call and merge semantics):

    printf '{"verification_depth": {"%s": "%s"}}' "<candidate-id>" "<shallow|moderate|strict>" \
      | bash skills/j-uncharted/scripts/elicitation-state.sh checkpoint --id <elicitation-id> --json -

    Check before asking. A candidate whose verification_depth is already present in the state file's checkpoint.verification_depth (per Multi-Session Persistence below) has already answered this — do not re-ask it, on a fresh session or otherwise.

    This question operationalizes the Human-Oracle-Availability Limitation above — it is the mechanism for finding out, per candidate, how much weight the user's own confirmations should carry, rather than assuming a uniform level of trust for every candidate in one run. verification_depth is read back and consumed by Step 4's risk-weighted gating below (E40_S06_T02), which branches its auto-accept/confirm/auto-flag behavior per depth. The fixed internal/external question template used whenever shallow/moderate gating does decide to prompt (Step 5) is skills/j-uncharted/assets/NODE_QUESTION_TEMPLATE.md (E40_S06_T03) — this step's job remains asking the question and making the answer durable for those steps to read.

  2. Dispatch Investigative Mode. Per agents/developer.md's and agents/tester.md's Investigative Mode sections (E20_S08_T02), dispatch the developer to trace what the code actually does for the candidate, and the tester to trace what the test suite actually exercises and verifies for the same candidate — two distinct vantage points, not two names for the same read. Both are read-only, worktree-sandboxed, no commits, no board writes.
  3. Propose understanding. From both traces, draft the candidate's coarse graph node(s)/edge(s) (per the stub schema) and a plain-language summary of what they represent.
  4. Risk-weighted gating — not every finding gets a prompt, and verification_depth (Step 1) decides how gating itself behaves, not just what counts as risky. This is the fix for confirmation fatigue (solution assessment, Problem 6, Solution B — RECOMMENDED). The baseline escalation criteria — the three triggers that force an explicit confirmation — are unchanged from before E40_S06:

    • T1 — inference-dependent: the node's description depends on an inference the traces don't fully support.
    • T2 — structurally central: the node has many outgoing edges.
    • T3 — already-flagged uncertain: the Human-Oracle-Availability Limitation above already flagged this finding as uncertain.

    A finding tripping none of T1-T3 is low-risk and auto-accepts regardless of depth. A finding tripping any of T1-T3 is escalating, and what happens to it now branches on the current candidate's verification_depth (read from checkpoint.verification_depth.<candidate-id>, per Step 1):

    • moderate (the default, unchanged calibration) — exactly today's behavior: every escalating finding (any of T1-T3) forces a confirm prompt (Step 5); every low-risk finding auto-accepts without a prompt. Log every auto-accepted node in the elicitation state's checkpoint data (see Multi-Session Persistence below) so the decision is auditable later, per that solution's own mitigation for "the scoring mechanism itself misjudges impact."
    • shallow (widened auto-accept) — the concrete widening rule: drop T2 (structurally central) as an escalation trigger. A finding tripping T2 alone — structurally central, but not inference-dependent and not already flagged uncertain — is reclassified low-risk and auto-accepted (still logged, same as above) instead of escalating. T1 and T3 still force a confirm prompt exactly as under moderate; only the T2-alone case widens. This is the literal reading of "findings that would sit just below today's high-impact bar" from the task's own framing — a purely structural signal with no corroborating uncertainty is no longer, by itself, enough to interrupt the user.
    • strict (no confirm prompt for escalating findings, ever) — a finding tripping any of T1-T3 is never presented to the user. Instead:

      1. Write the node directly with a hedged, low-confidence description, reusing the exact hedging convention the Human-Oracle-Availability Limitation section already specifies (e.g. "unconfirmed — traces did not fully corroborate this," adapted to name the specific gap).
      2. Call elicitation-state.sh converge directly — do not call elicitation-state.sh turn for this node. No confirmation round is spent; the node goes straight from "proposed" to "converged," never "pending":

        bash skills/j-uncharted/scripts/elicitation-state.sh converge --id <elicitation-id> --node <node-id> --note "auto-flagged under strict depth: <one-line reason, e.g. 'structurally central, traces disagree on scope'>"
      3. Log the auto-flag in the elicitation state's checkpoint data, the same way moderate/shallow auto-accepts are logged — this is an automatic decision, not a silent one, and stays auditable exactly like every other gating outcome.

      Low-risk findings under strict are unaffected — they auto-accept exactly as under moderate/shallow. strict only changes what happens to the escalating case.

    The fixed internal/external question template used whenever shallow/moderate gating does decide to prompt is skills/j-uncharted/assets/NODE_QUESTION_TEMPLATE.md (Step 5, E40_S06_T03) — dormant under strict, since no prompt ever fires there.

  5. Confirm/correct, one round per call to elicitation-state.sh turn. Never reached for a strict-depth candidate's escalating findings — those converge directly per Step 4 above. For a node requiring confirmation under shallow/moderate, do not present the draft with a fully open-ended "propose understanding, ask to confirm or correct" prompt. Instead use the fixed question set in skills/j-uncharted/assets/NODE_QUESTION_TEMPLATE.md (E40_S06_T03), selecting the variant by node kind:

    • Internal variant — the node represents the candidate/service itself (the thing this investigation is about).
    • External variant — the node represents a dependency or consumer the traces surfaced outside the candidate (something it calls, or something that calls it).

    Present the drafted node/edge summary from Step 3 first, then ask the selected variant's fixed questions, then offer the same confirm / correct-with-detail / defer-as-unconfirmed / other choice as before (per the Interaction Pattern in CLAUDE.md) — the template file spells out both the questions and this response block verbatim, so read it rather than reconstructing either from memory. Each round, call:

    bash skills/j-uncharted/scripts/elicitation-state.sh turn --id <elicitation-id> --node <node-id>

    Exit 0 means keep looping (cap not yet reached) if the user corrected rather than confirmed. Exit 3 means the hard turn cap has been reached — the node is now marked flagged in the state file. Do not loop again on that node. Instead present it as unresolved and offer an explicit choice rather than looping indefinitely (solution assessment, Problem 10, Solution A — RECOMMENDED):

    <node> has reached the confirmation round limit without converging.
    1. Accept the current best draft as-is (flagged low-confidence)
    2. Defer — skip this node for now, continue with the rest
    3. Continue past the limit (explicit override)
    4. Other (describe below)

    Option 3 is the only way past the cap, and it is a per-node, explicit, one-time override — it does not raise the cap for the rest of the run.

  6. On convergence (confirmed, corrected-and-accepted, or resolved via the cap choice above), call:

    bash skills/j-uncharted/scripts/elicitation-state.sh converge --id <elicitation-id> --node <node-id> --note "<one-line summary of what was confirmed>"

    then write the node/edge to project/knowledge-graph/graph.json per the stub schema, and checkpoint the elicitation state (next section) — after every converged node, not only at the end of the whole run.

Multi-Session Persistence

A whole-codebase onboard conversation, or an investigation of a large directory, can span more sessions than fit in one sitting. State persists via the existing SessionEnd/queue infrastructure — no new persistence mechanism (solution assessment, Problem 11, Solution A — RECOMMENDED).

  • init once, at the start of an elicitation:

    bash skills/j-uncharted/scripts/elicitation-state.sh init --id <elicitation-id> --target "<path or description>" --cap 5

    Idempotent — safe to call again on a resumed <elicitation-id> without resetting progress. Choose <elicitation-id> so it is stable and re-derivable across sessions (e.g. onboard-<root-slug>-<date>, or segment-investigate-<target-slug>), since a resuming session must be able to reconstruct it to call init again.

  • checkpoint after every converged node, after the Directory Triage confirmation gate, and after every Familiarity Check answer — never only at the end. This is what makes a mid-run pause lossless: checkpoint --id <id> --json <file> merges arbitrary progress data (triage results, draft nodes not yet converged, per-candidate verification_depth, anything else worth surviving a pause) into the state file. verification_depth is stored as one object keyed by candidate id — checkpoint.verification_depth.<candidate-id> — and, per the script's own merge semantics (see its header), checking one candidate in never clobbers another candidate already recorded there.
  • pause when a session must end before the elicitation has converged. Immediately after calling elicitation-state.sh pause --id <elicitation-id>, write the scrum-master's own SessionEnd handoff (per $([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)'s handoffs/ convention) with status: "elicitation_paused" and both elicitation_id and state_file set — hooks/on_session_end.sh routes that into an elicitation_resume trigger on scrum_triggers.jsonl, which the next scrum-master session's Drain Scrum Triggers Queue procedure picks up (agents/scrum-master.md).
  • On resume, read state_file directly — every converged node, every flagged node, and the checkpoint data (including the confirmed directory-triage lists and any per-candidate verification_depth already recorded) are already there. Do not re-run Directory Triage, re-ask the Familiarity Check for a candidate already present under checkpoint.verification_depth, or re-ask about an already-converged node; resume the Convergence Loop only for nodes still pending or explicitly deferred, and only ask the Familiarity Check for a candidate that has neither.
  • complete when every candidate has converged, been deferred, or been explicitly accepted past the cap. The state file is left on disk afterward as an audit trail — nothing currently prunes a completed elicitation's state file.

Modes

<!-- PLACEHOLDER SECTIONS — scaffolded by E40_S01_T01. Each mode below is a self-contained block under a stable `### ` heading. The owning task replaces the body of its own block and leaves the others and the surrounding shared sections untouched. -->

segment

Analyse a specific file, directory, or feature that has no board provenance. Since E20_S08_T03, segment has two explicit modes — it no longer silently always runs one:

FlagModeWhat it produces
--mode delivery (default when explicit)Delivery-shaped proposal — today's unchanged flowA standard epic/story/task proposal, per the Understanding Document
--mode investigateConversational architecture investigation (new, E20_S08_T03)Coarse graph nodes/edges plus a [ARCH]-tagged board item

Step 0 — choose a mode. If --mode is given, skip straight to that mode's subsection below. If it is missing, do not default silently — present the choice, per the Interaction Pattern in CLAUDE.md:

/uncharted segment <target> — which mode?
1. Delivery-shaped proposal (produces an epic/story/task to build on this target)
2. Conversational architecture investigation (produces graph nodes explaining what this target does)
3. Other (describe below)

Silence, a counter-question, or an ambiguous reply is not consent — re-ask. This choice is the entire mechanism by which existing callers keep getting exactly today's behavior (option 1, or --mode delivery passed explicitly) while new callers can reach the conversational path deliberately, per the parent story's own acceptance criterion that this split must be explicit, not a silent behavior change.

Delivery-shaped proposal (--mode delivery)

Unchanged from before E20_S08_T03 — every step below is exactly what segment has always done.

Step 1 — Resolve the target. Deterministic; do not eyeball it.

bash skills/j-uncharted/scripts/resolve-segment-target.sh --json-only "<path-or-description>"

It returns one results[] record. Read three fields:

FieldMeaning
kindpath — the argument is an existing file or directory, already canonicalised in target. description — it is free text (exit 2).
board_linkage.statusunlinked, linked, or not_checked (with a reason — repo root, outside the repo, or no board directory).
candidates[]Only for kind: description. Ranked path hints, capped by --limit.

When kind is description, you must ask. Present candidates[] as a numbered choice list with a free-text option last, per the Interaction Pattern in CLAUDE.md. Never silently adopt the top-scored candidate — the score is a ranking hint, not a resolution, and picking for the user is how the wrong directory gets a whole epic written against it. An empty candidates[] is a normal result, not a failure: ask for the path directly. Exit 2 still prints its JSON, so read it rather than retrying.

Report the linkage before doing anything else. unlinked is the condition that justifies this whole workflow; say so. linked is a genuine finding — the target already has board provenance, so tell the user which items reference it and confirm they still want a segment pass rather than /redo. Do not proceed silently past a linked target.

Step 1 is authoritative on linkage. run-engine.sh keeps its own private, minimal reimplementation of resolve-segment-target.sh's in-repo linkage check for the document's Board Linkage row — as of E40_S02_T05, both use the same path-boundary rule (a board reference counts only when a board file's path-like token equals the target or is a path descendant of it, and a board reference to the target's generated .agents//.claude/ mirror counts as a reference to the canonical root too), so the two should agree for every in-repo target. They can still theoretically diverge — run-engine.sh's version is a minimal reimplementation, not resolve-segment-target.sh's full BOARD_INDEX/tokenizer, and full unification (having run-engine.sh call resolve-segment-target.sh --json-only directly) remains a deliberate, separate follow-up (see below). Where they differ, trust Step 1 and correct the row when you fill in the document — do not hand the user a document that contradicts what you just told them.

When Step 1 reports not_checked (e.g. the target is outside this repository), do not render an unlinked/linked claim at all. Neither is true — nothing was searched, so nothing was verified absent or present. Render the document's Board Linkage row as "not applicable — target outside repository" (or the equivalent reason Step 1 returned, worded the same way), and say the same thing out loud per "Report the linkage before doing anything else" above. run-engine.sh's own row for this case is worded consistently (not_checked — target is outside this repository), so the two should already agree — but Step 1 stays the source of truth if they ever don't.

The same script is also /reconcile's board-linkage check (E40_S05_T02). Collapsing the two implementations into one is a deliberate follow-up, not something to do in passing — see the script's header.

Step 2 — Run the engine on the resolved absolute path:

DOC=$(bash skills/j-uncharted/scripts/run-engine.sh --mode segment "<resolved target>")

Options, streams, and exit codes are in Shared Investigative Engine above — do not restate them here, and do not reimplement enumeration, dependency, or test detection. Two mode-specific readings:

  • Exit 2 here means the resolution was wrong, not that the engine is broken. Go back to Step 1 with the user.
  • Pass --origin only when import handed the target over (E40_S03_T03). A plain in-repo segment derives its own origin.

Call the engine once, unwrapped. It writes --json-out before the document on purpose, so a failed JSON write never leaves an orphaned document behind; re-ordering or wrapping the call breaks that guarantee.

Step 3 — Fill in the judgement sections of the written document (Purpose, Risk Areas, Open Questions) per Output: the Understanding Document above, then give the user the document path.

Step 4 — Choose the parent epic before proposing anything. A segment rarely deserves an epic of its own.

List project/board/epics/ and apply the normal scrum-master intake rule (agents/scrum-master.md): consider whether the segment belongs under an existing epic before creating a new one, and treat the standing Maintenance epic as the default home for chore-shaped work that belongs nowhere else. Three inputs decide it:

  • Step 1 said linked — the epic of the item that already references the target is the default parent. Do not open a sibling epic for code that is already spoken for.
  • The document's Purpose matches an existing epic's Purpose — that epic is the parent.
  • Neither — Maintenance if the work is a chore; a new epic only when the segment is genuinely a body of work no existing epic covers.

A new epic is the last option, not the default, and needs a stated reason. Record the epics you weighed and rejected — "none fit" is a claim the user should be able to check.

Step 5 — Draft the proposal using skills/j-uncharted/assets/SEGMENT_PROPOSAL_TEMPLATE.md. Its six headings are fixed; fill every one of them. Two things it will not let you skip:

  • Every proposed task carries execution_scope and a non-empty scope_rationale containing a file-count or line-count claim, assigned against project/configs/scope-thresholds.json rather than by feel — inline at or under 1 file / 20 lines, story when tasks share files across the story (up to 5 files), task otherwise. Never self-assign execution_scope: epic: it requires epic_scope_approval: true, which only a human sets. Propose story and say the task looks bigger instead. Field semantics live in $([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md) — read them there, do not paraphrase them here.
  • The document's Open Questions carry over verbatim, not re-derived, each with who can answer it and whether it blocks confirmation. A blocking question is resolved before the proposal is accepted, because the breakdown depends on its answer.
  • Propose everything the board file will contain, not just titles. Each story's Acceptance Criteria and Definition of Done are proposed at the gate, and a new epic's Purpose and Definition of Done with it — scripts/validate-story-format.sh requires those sections, so anything missing here is text E40_S02_T03 would have to invent after the user has already said yes.

Ground every story and task in a specific finding — the untested file, the named dependency, the oversized module. A breakdown that would fit any codebase has failed for the same reason a generic understanding document has.

Step 6 — Stop at the confirmation gate. Present the filled proposal in the session and offer the choice from its ## Decision section, per the Interaction Pattern in CLAUDE.md. The template's ## Decision block is authoritative — it is the presentation contract, and the copy below is a reading convenience. If the two ever disagree, the template wins and this passage is the one to fix:

  1. Accept as proposed — write these items to project/board/
  2. Revise — change the stories, tasks, or scopes before anything is written
  3. Fit it under a different epic — re-parent the proposal and show it again
  4. Discard — keep the understanding document, write no board items
  5. Other (describe below)

Option 1 is unavailable while any Open Question is marked as blocking. Resolve it first — the answer usually changes the breakdown — then re-present.

Nothing under project/board/ is created or modified before option 1 is chosen. Not a stub epic, not a placeholder task, not an ID reservation, not "just the epic so the stories have somewhere to hang". Everything from Step 4 onward leaves git status unchanged — the only file this flow has written by now is the understanding document from Step 2, and that lives in project/rapports/analysis/.

Options 2 and 3 loop back to Step 5 (or to Step 4 for a re-parent) and re-present the proposal in full; nothing is written between rounds, because a half-written board is exactly the outcome this gate exists to prevent. Option 4 leaves the understanding document as the output — a legitimate result, not a failure. Silence, a counter-question, or an ambiguous reply is not consent; re-ask.

Where this stops. Resolution, linkage, the understanding document, and a confirmed proposal are the whole of Steps 1-6. Nothing reaches project/board/ until option 1 is chosen; then Step 7 writes it.

Step 7 — Write the accepted items to the board. Only reachable from option 1, and only after any blocking Open Question is resolved.

The proposal is the input and the only source of content. Everything the board files contain — the epic's Purpose and Definition of Done, each story's As a …, I want …, so that … line, Acceptance Criteria, and Definition of Done, each task's execution_scope and scope_rationale — was proposed at the gate and is transcribed verbatim. Nothing is composed, expanded, or improved at write time. If a field looks wrong now, that is a revision (option 2), not an edit in passing: text the user did not read has no business on the board, which is the whole point of the gate.

Shape, field names, and file naming come from $([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md). Read them there — do not paraphrase them here. Five things it will not let you skip:

  • Parent before child. Epic (if new), then stories, then tasks. The schema's Linking Convention makes the epic's stories[] and each story's tasks[] the authoritative index, so a child written before its parent leaves an index nobody has updated.
  • IDs continue the sequence they belong to. E## is the next free epic number board-wide, but S## is the next free story number within its parent epic and T## the next free task number within its parent story — that is what the E##_S##_T## shape means. Story numbers restarting per epic is normal and expected, not a collision. Nothing catches an error here: validate-board.sh checks an ID's shape, never its uniqueness or its sequence, so a well-formed wrong number passes every gate in Step 7 and quietly reuses an ID that already meant something else.
  • Take the advisory lock described under the schema's File Locking section before each write, and release it with a trap so a failed write does not leave a .lock behind that blocks the next agent for good.
  • status: Pending, date_created today, date_started empty. These items have not been executed. Only the tester moves a status off Pending — do not write anything else, however confident the proposal was.
  • jenga_assigned: true for scopes assigned at Step 5 against project/configs/scope-thresholds.json. If the user changed a scope during a Revise round, that scope was a human override: jenga_assigned: false with an override_justification saying what they changed and why. Never set epic_scope_approval — only a human sets that.

Then prove it mechanically rather than asserting it:

bash skills/j-uncharted/scripts/validate-proposed-items.sh <every file just written>

It runs scripts/validate-board.sh over every file and scripts/validate-story-format.sh over every story file, and exits non-zero listing each failure — not just the first, because deciding whether to repair or roll back needs the whole list. Exit 2 means a usage error or a missing validator, not a bad board file.

A non-zero exit leaves you mid-write, and that is the one state this flow must not end in. Repair the named files and re-run, or delete everything written in this step and return to Step 5 with the failures. Deleting is safe here and only here: every one of these files is new, so there is nothing to restore. Never report success, and never hand off to Step 8, on a board that has not passed.

On success, tell the user exactly which files were created, with their IDs.

Step 8 — Hand off to the standard path. Queue each new task with the canonical todo owner — bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" add "<entry>", one call per task, referencing the task ID — and the work then proceeds through the ordinary /todo → /do → developer → tester path, with no special casing anywhere along it. Point the tasks' Description at the understanding document from Step 2; it is the context the developer picking one up would otherwise lack.

/uncharted writes board files and stops there. It does not adapt the segment to project conventions, edit or move the code it just analysed, open a worktree, or write an execution plan. That is ordinary developer work, driven by ordinary task files, and it is the developer agent's job — the same as for a task that came from /brainstorm or /pi-plan. A segment that has reached the board is no longer a special case, and this skill growing its own integration path would be a second, divergent execution route for work the existing one already handles.

Conversational investigation (--mode investigate)

New in E20_S08_T03. Produces a plain-language understanding plus graph nodes for a specific target — the same conversational mechanics as onboard's default flow, applied at single-target scale instead of whole-codebase scale. Read Conversational Elicitation above (Human-Oracle-Availability Limitation, Directory Triage, Convergence Loop, Multi-Session Persistence) before running this — everything below only sequences those shared mechanics for segment's scope; it does not redefine them.

Step 1 — Resolve the target. Reuse resolve-segment-target.sh exactly as the delivery-shaped path's own Step 1 does above — do not reimplement resolution or the board-linkage check for this mode. A linked target is a normal condition here (unlike the delivery-shaped path, an existing epic/story/task referencing the target doesn't disqualify investigating it), but still tell the user before proceeding, the same as the delivery-shaped path does.

Step 2 — Directory triage, only if the target is a directory with subdirectories. A single-file target has nothing to triage; skip straight to Step 3. For a directory target, run the shared Directory Triage procedure above against the target's immediate subdirectories as the candidate set.

Step 3 — Convergence loop. Run the shared Convergence Loop procedure above. For a single-file target this is one node; for a directory target (after triage) it is one node per surviving candidate. Initialize persistence first:

bash skills/j-uncharted/scripts/elicitation-state.sh init --id "segment-investigate-$(basename "$RESOLVED_TARGET")-$(date -u +%Y%m%d)" --target "$RESOLVED_TARGET"

Step 4 — On convergence, write the graph and the board item. Write each converged node/edge to project/knowledge-graph/graph.json per the stub schema (source: "human"), then present a single [ARCH]-tagged board item proposal — epic, story, or task, whichever level fits what was actually investigated (a single flow is usually task-scale; a whole subsystem may warrant a story or, rarely, an epic) — and stop at the same kind of confirmation gate the delivery-shaped path's Step 6 uses (accept / revise / discard / other). Nothing is written to project/board/ before that gate is confirmed, matching the delivery-shaped path's own "nothing written before option 1" guarantee. On acceptance, write the board item and call elicitation-state.sh complete.

This mode never produces a delivery-shaped epic/story/task proposal. If the investigation surfaces work that should actually be built (not just understood), say so as a follow-up recommendation in the [ARCH] item's own text and let the user separately invoke --mode delivery or /todo for that — conversational investigation and delivery planning stay two distinct outputs, per this mode split's own purpose.

import

Pull an external source into the repo, then investigate it as a segment.

Status: import is complete end to end (E40_S03_T01–T03). Acquisition, provenance surfacing and placement confirmation, and the move-and-handoff into segment are all live. import contributes exactly two things segment does not — acquisition (Steps 1-2) and placement (Steps 3-6) — then Step 7 hands off into segment's own flow for everything else. No enumeration, dependency-detection, or test-detection logic is duplicated here; that all lives in segment and the shared engine.

Step 1 — Acquire into staging. Deterministic; do not hand-roll a clone or a copy.

SUMMARY_JSON=$(bash skills/j-uncharted/scripts/import-source.sh --json-only "<source>")

<source> is a git URL, a local path outside this repo, or - (with the snippet piped on stdin, --type snippet --name <filename>). Read four fields off SUMMARY_JSON: source_type, source, staging_path, content_path, and git_ref (the short HEAD SHA, present only for a git-type acquisition — import-source.sh deletes the clone's .git directory immediately after reading it, as part of treating acquired content as hostile, so this is the only point at which that SHA is ever recoverable). Exit codes and the full security contract (no hooks, no install scripts, staging always outside the repo working tree) are documented in the script's own header — read them there, do not restate them here.

A non-zero exit here means nothing was acquired. Surface the script's stderr to the user and stop; there is no staging directory to clean up in that case (the script cleans up after itself on failure).

Step 2 — Inspect provenance. Also deterministic, and mandatory before Step 3 — the destination proposal is presented alongside these findings, never before them.

PROVENANCE_JSON=$(bash skills/j-uncharted/scripts/inspect-provenance.sh \
  --origin-source "$(echo "$SUMMARY_JSON" | jq -r .source)" \
  --origin-type   "$(echo "$SUMMARY_JSON" | jq -r .source_type)" \
  --origin-ref    "$(echo "$SUMMARY_JSON" | jq -r '.git_ref // ""')" \
  "$(echo "$SUMMARY_JSON" | jq -r .content_path)")

Forward source / source_type / git_ref from Step 1's summary exactly like this — do not omit the --origin-* flags because they look redundant with what's already on disk. inspect-provenance.sh cannot recover them itself: acquisition already deleted the .git directory that held them. What it does find live on disk is reported independently: any LICENSE/LICENCE/COPYING/UNLICENSE/NOTICE file (with a best-effort type classification), any SPDX-License-Identifier headers, copyright lines near the top of files, and any nested .git directory the acquisition didn't strip (a vendored checkout, for instance).

Read every section's message field, not just found. inspect-provenance.sh states explicitly, per category, when nothing was found — license.message, spdx_identifiers.message, copyright.message, git_origin.message are all non-null exactly when that section is empty — and overall.message restates it plainly when every section comes back empty. Never translate "no license file was found" into "this source is unencumbered" or anything implying it. This is an informational surface, not a legal clearance: state what was found, state plainly when nothing was, and let the user decide. The script's own stderr also carries scan-scope notices (directories excluded from the content scan, symlinked files that were found but never opened for safety, a --max-files cap being hit) — read them, the same as any other engine script's stderr.

Step 3 — Propose a destination. Judgement, not a script: derive a short slug from the source (the repo name, the snippet's --name, the last path component of a local source) and propose a location under the repo that fits where similar content already lives — alongside a related existing area when one is evident from the source's contents, or a clearly-named new top-level location when nothing existing fits. State why briefly; a bare path with no rationale gives the user nothing to evaluate at Step 4.

Step 4 — Confirm before anything leaves staging. Present the proposed destination together with the Step 2 findings, then require an explicit numbered choice, per the Interaction Pattern in CLAUDE.md — free-text last:

Provenance findings for <source>:
<Step 2's findings, summarised — license/SPDX/copyright status, and the overall message
 verbatim when nothing was found>

Proposed destination: <path>
<one-line rationale>

How should this be placed?
1. Use the proposed path
2. Use a different path (name it)
3. Abort the import
4. Other (describe below)

Silence, a counter-question, or an ambiguous reply is not consent — re-ask, the same convention segment's Step 6 uses. Option 2 loops back to Step 3 with the user's named path in place of the derived one and re-presents this same confirmation; it does not silently accept a path that was never shown back to the user for approval.

Nothing under the repo working tree is written by reaching this gate. Content stays in content_path, exactly where Step 1 left it, until the user picks option 1 or a confirmed option 2 path.

Step 5 — Abort leaves no trace. Option 3 removes the entire staging root (not just content_path) —

rm -rf "$(echo "$SUMMARY_JSON" | jq -r .staging_path)"

— and stops. Confirm with git status that the working tree is unchanged; nothing from this flow was ever written under it, so there is nothing to revert, only the staging directory to discard.

Step 6 — Move into place. Reachable only from a confirmed destination: option 1 at Step 4, or a confirmed option 2 path. This is a plain filesystem operation — import-source.sh staged content, it does not place it, and there is no dedicated placement script because the semantics are simple and specific to this one call site:

DESTINATION="<confirmed path, repo-relative>"
CONTENT_PATH="$(echo "$SUMMARY_JSON" | jq -r .content_path)"
STAGING_PATH="$(echo "$SUMMARY_JSON" | jq -r .staging_path)"

if [ -e "$DESTINATION" ] && [ -n "$(ls -A "$DESTINATION" 2>/dev/null)" ]; then
  echo "Destination already exists and is not empty — this would overwrite existing content." >&2
  # Stop. Go back to Step 4 with a different path; do not merge into or overwrite it.
else
  mkdir -p "$DESTINATION"
  cp -R "$CONTENT_PATH/." "$DESTINATION/"
  rm -rf "$STAGING_PATH"
fi

content_path's contents land directly under the destination directory — never nested inside an extra subdirectory — whether content_path holds a whole tree (a cloned repo, an imported directory) or a single file (a snippet, a single imported file). The staging root is removed afterward the same way Step 5 removes it on abort, but for the opposite reason: the content now has a permanent home, not because it is being discarded.

Refuse to overwrite. A destination that already exists and is non-empty is not merged into or clobbered — stop and return to Step 4 for a different path. This is the same "never silently written into an arbitrary path" guarantee the confirmation gate exists to uphold; it applies just as much to what is already there as to what the user did not confirm.

The placed files are new, uncommitted content in the working tree at this point — /uncharted places them and stops; it does not commit. Committing them is ordinary work for whichever task Step 7 below eventually queues, the same as any other new file a task depends on.

Step 7 — Hand off to segment. The source is now at its final in-repo path. From here, import contributes nothing further: everything below is segment mode's own flow (above), run against the destination, not a second implementation of it.

  • Run segment's Step 1 (resolve-segment-target.sh) against $DESTINATION for its board-linkage status. A freshly placed path is normally unlinked, but check rather than assume — a board item could already reference the intended path from prior planning.
  • Run segment's Step 2 (run-engine.sh --mode segment "$DESTINATION" --origin "imported from $(echo "$SUMMARY_JSON" | jq -r .source)") — exactly the case segment's own Step 2 note anticipates ("Pass --origin only when import handed the target over").
  • At segment's Step 3 (filling the judgement sections), carry the provenance findings from this section's Step 2 (PROVENANCE_JSON) into Risk Areas — do not re-derive or rediscover them:
    • Read PROVENANCE_JSON's license, spdx_identifiers, copyright, and git_origin sections, plus overall.message, and fold every finding — and the fact of an empty one — into Risk Areas, grounded exactly as segment's Step 3 already requires elsewhere: a specific license file (or its stated absence), a specific SPDX identifier, a specific copyright line, a nested .git left over from a vendored checkout.
    • An unclear or absent license is itself a Risk Area entry. Word it the same cautious way inspect-provenance.sh's own overall.message already does — the scan found nothing, which is not the same claim as the source being unencumbered — and never soften it into "no licensing concerns".
    • Where the licensing question needs a human answer before the segment is safely integrated (no license file, an unrecognised SPDX identifier, an un-vetted nested .git), also add it as an Open Questions entry, marked Blocks confirmation? yes when it is serious enough to hold up acceptance. Segment's Step 5 already carries Open Questions into the proposal verbatim — recording it once here is the entire mechanism by which a provenance finding reaches the board proposal. There is no separate provenance field on the proposal template and none is needed.
  • Continue through segment's Steps 4-8 exactly as written above: choose the parent epic, draft the proposal, stop at the confirmation gate, and — only on acceptance — write the board and queue the tasks. Do not skip Step 6's confirmation gate because this section's Step 4 already asked a question; that gate confirmed placement, segment's Step 6 confirms the board breakdown, and they are different decisions the user must see separately.

Nothing about enumeration, dependency detection, or test detection is re-specified here — segment's own Step 2 (run-engine.sh) already does all of that, once, against the placed destination.

onboard

Give an entire pre-existing codebase board representation at framework-adoption time. Since E20_S08_T03, onboard has two modes:

InvocationModeOutput
onboard <root> (default)Conversational — human-in-the-loop elicitation seeded by the same discovery scripts[ARCH]-tagged board items + coarse graph nodes in project/knowledge-graph/graph.json
onboard <root> --legacyFully-automated, zero-prompt, capped-backfilled-epic pass — E40_S04's original behavior, byte-for-byte unchangedprovenance: backfilled epics

--legacy is not a deprecated fallback — it is the designated tool for a codebase with no available human oracle. Read Human-Oracle-Availability Limitation under Conversational Elicitation above before choosing between the two; that section states explicitly when --legacy is the correct choice, not a lesser one.

Build status: the legacy pipeline (E40_S04_T01-T05: provenance field, subsystem discovery, cap enforcement, backfilled epic generation, PROJECT_SUMMARY.md population) is complete and unchanged by this rework — see Legacy mode below. The conversational default is new as of E20_S08_T03 — see Conversational default below.

The hard constraint: onboard never touches application code

This holds in both modes — conversational and legacy alike.

onboard mode must never modify, move, rename, delete, or restructure any file that belongs to the consumer's application. This is not a best-effort convention — it is the reason onboard exists as a board-only mode rather than a generic migration tool. Its entire output surface, without exception, is:

  • project/board/ (backfilled epics in --legacy mode; [ARCH]-tagged epics/stories/tasks in conversational mode)
  • project/rapports/analysis/ (understanding documents and the subsystem cap record — --legacy mode only; conversational mode's primary output is the graph, not this document type — see Conversational Elicitation above). Both modes additionally write a committed scan-record (*.scan-record.json, E40_S07_T01) into this same directory at the end of every successful run — distinguished from an understanding document by filename suffix, never overloading one artifact with two purposes.
  • project/PROJECT_SUMMARY.md (populated by E40_S04_T05, --legacy mode only)
  • project/knowledge-graph/graph.json (coarse graph nodes/edges — conversational mode only, per the stub schema)
  • project/queue/elicitation-state/ (multi-session persistence scratch state — conversational mode only, git-ignored, not a durable artifact)

Nothing under any other path is ever created, edited, or deleted by onboard mode, in either mode. Jenga's board and skills live alongside the application; the application never has to conform to a Jenga convention to be onboarded. This guarantee is enforced in three independent places, not just stated here:

  1. This prohibition, read by any agent driving onboard mode.
  2. A structural write-path guard in skills/j-uncharted/scripts/write-backfilled-epics.sh — its --epics-dir and --json-out destinations are canonicalised and checked against <repo-root>/project/ before any file is written, with no flag able to point either one outside it. A path that resolves outside project/ is a hard failure (exit 3), nothing written — not a warning that can be missed.
  3. A verifiable post-run check (below): after a full onboard run, git status in the analysed repository must show changes only under project/.

Conversational default

New in E20_S08_T03. Runs when onboard is invoked without --legacy.

Step 1 — discovery stays scripted. Run the exact same deterministic discovery chain the legacy pipeline uses — discover-subsystems.sh — unchanged. Evidence-gathering is not where this rework touches anything; only what happens with the output differs. Capture its output — Step 5 reuses it to write the scan-record once the run completes successfully.

DISCOVERY_JSON=$(bash skills/j-uncharted/scripts/discover-subsystems.sh <root>)

Step 2 — directory triage. Feed the discovery output's candidate paths into the shared Directory Triage procedure (see Conversational Elicitation above), and stop at its confirmation gate before anything else happens.

Step 3 — initialize persistence.

bash skills/j-uncharted/scripts/elicitation-state.sh init --id "onboard-$(basename "$(cd "$root" && pwd)")-$(date -u +%Y%m%d)" --target "<root>" --cap 5

Step 4 — convergence loop, once per surviving candidate. Run the shared Convergence Loop procedure (see Conversational Elicitation above) for each candidate that survived triage — this is where the legacy pipeline's apply-subsystem-cap.sh and write-backfilled-epics.sh would have silently produced a capped set of provenance: backfilled epics; the conversational default asks about each one instead, subject to the same risk-weighted gating and hard turn cap. There is deliberately no subsystem cap on the conversational path — the turn cap already bounds cost per candidate, and capping the candidate count the way the legacy path does would silently drop subsystems from a human-in-the-loop conversation the same way the legacy path drops them from an unattended one, which defeats the point of asking. A codebase with far more subsystems than is practical to walk through conversationally in one sitting is exactly the multi-session case Multi-Session Persistence exists for — pause, resume across sessions, rather than truncate the candidate list.

Step 5 — on convergence, write the graph and the board item(s). Per candidate: write the converged node(s)/edge(s) to project/knowledge-graph/graph.json, then present an [ARCH]-tagged board item proposal at whichever level fits (an individual subsystem is usually story-scale; the whole run may warrant a single [ARCH] epic containing one story per converged subsystem — judgement call, not a fixed rule) and stop at a confirmation gate before writing to project/board/, exactly as segment --mode investigate's Step 4 does. Call elicitation-state.sh complete once every candidate has converged, been deferred, or been resolved past the turn cap.

Write the scan-record once the run has completed successfully (elicitation-state.sh complete has been called) — not on every candidate, and not gated on refresh mode existing or ever being invoked (E40_S07_T01). Reuse $DISCOVERY_JSON captured at Step 1; this is the only place in the conversational path that needs it after Step 2:

bash skills/j-uncharted/scripts/write-scan-record.sh <<< "$DISCOVERY_JSON"

This is deliberately not the elicitation state file — that persistence is transient session scratch (see Multi-Session Persistence above); the scan-record is committed and must survive indefinitely between onboard/refresh runs. Baseline discovery and diff classification against this record are separate, not-yet-implemented follow-on tasks (E40_S07_T02, E40_S07_T03); this step only writes it.

PROJECT_SUMMARY.md population still applies, unchanged in spirit. Once the conversational pass has produced its [ARCH] items, hand off to the scrum-master for the same PROJECT_SUMMARY.md Overview/Architecture & Structure drafting-and-confirmation flow described under Updating PROJECT_SUMMARY.md from onboard evidence below (Steps A-D) — substituting the conversational pass's converged understanding for the legacy pipeline's kept array as the evidence source. Do not skip the stub-vs-real-content check in Step B just because the evidence came from a conversation instead of a script.

Legacy mode (--legacy)

Everything below is E40_S04's original, fully-automated, zero-prompt pipeline — unchanged by this rework, reachable only via the explicit --legacy flag.

The subsystem cap

Live as of E40_S04_T03. onboard does not create one epic per discovered subsystem — a 40-subsystem repository would bury the board on day one. It caps how many become epics, and skills/j-uncharted/scripts/apply-subsystem-cap.sh applies that cap to discover-subsystems.sh's ranked output:

bash skills/j-uncharted/scripts/discover-subsystems.sh <root> \
  | bash skills/j-uncharted/scripts/apply-subsystem-cap.sh --rapport "$DOC"

It emits JSON with two explicit arrays — kept (the subsystems that become backfilled epics) and dropped (everything below the cap, each entry carrying its path, rank, score and the reason string below cap of N).

OptionEffect
--cap NThe cap. Default 8. Raise it to backfill more subsystems. Must be 1 or higher — --cap 0 or a negative cap exits non-zero, because "produce no epics at all" is never a meaningful onboard run.
--rapport <file>Append the cap record to the onboard analysis document run-engine.sh --mode onboard already wrote. This is the normal flow: the cap record belongs with the analysis that produced it.
--out-dir <dir>Where a standalone cap record goes when --rapport is not given. Default project/rapports/analysis/.
--json-out <file>Also write the report to a file. stdout gets it either way.
--label "<text>"Human label for the codebase in the record. Defaults to the analysed root.

Dropped subsystems are always surfaced, and are never silently truncated. Every run writes a human-readable ## Subsystem Cap section into an analysis rapport under project/rapports/analysis/ naming every dropped subsystem individually, with its rank, score and reason. That record is the point of the script, not a side effect of it: a user who onboards a 40-subsystem repo and gets 8 epics must be able to find out, later and on disk, which 32 were left off and why — long after the chat message saying so has scrolled away. There is deliberately no flag to skip that write, no elision in the list, and an unwritable rapport fails the whole run rather than returning a clean result with no audit trail.

Tell the user the drop count and the rapport path. Do not paste the whole dropped list into the conversation — it is on disk, in full, which is exactly the durability being bought here.

Nothing is dropped when the candidate count is at or below the cap: dropped is an empty array and the run still exits 0. A dropped subsystem is not a rejected one — it simply has no backfilled epic, and can be brought onto the board individually later with /uncharted segment <path>, or by re-running onboard with a higher --cap.

ExitMeaning
0Cap applied; record written (including the nothing-was-dropped case).
1Usage error — unknown flag, non-integer cap, or a cap of 0 or below.
2Input error — the report is missing, unreadable, not JSON, or has no candidates array.
4The drop record could not be written. Fatal by design.

Generating the backfilled epics

Live as of E40_S04_T04. skills/j-uncharted/scripts/write-backfilled-epics.sh is the only thing that actually writes backfilled epics to the board — it consumes apply-subsystem-cap.sh's kept array and renders one epic file per entry, following the Epic format in $([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md) exactly (provenance: backfilled, status: Pending, an empty stories array, a Purpose section built from the discovery evidence, and a Definition of Done framed around understanding and integration, never original construction):

DISCOVERY_JSON=$(bash skills/j-uncharted/scripts/discover-subsystems.sh <root>)
echo "$DISCOVERY_JSON" \
  | bash skills/j-uncharted/scripts/apply-subsystem-cap.sh --rapport "$DOC" \
  | bash skills/j-uncharted/scripts/write-backfilled-epics.sh
OptionEffect
--epics-dir <dir>Where epic files are written. Default <repo-root>/project/board/epics. Must resolve under <repo-root>/project/ — see the write-path guard above.
--json-out <file>Also write this script's JSON summary to a file. Same guard applies.
--dry-runCompute IDs and render content without writing anything — useful for previewing what a run would produce.
--label "<text>"Human label for the analysed codebase, used in each epic's Purpose section.

Write the scan-record once epic generation has succeeded (E40_S07_T01) — not gated on refresh mode existing or ever being invoked; every successful onboard --legacy run leaves one, the same as the conversational default does. Reuse $DISCOVERY_JSON captured above — it carries discover-subsystems.sh's own candidates array, which is what write-scan-record.sh expects; apply-subsystem-cap.sh's kept/dropped output is a different shape and is not what gets piped here:

bash skills/j-uncharted/scripts/write-scan-record.sh <<< "$DISCOVERY_JSON"

This is a committed record (never git-ignored), distinct from elicitation-state.sh's transient session scratch — see the conversational default's own note on this above. Baseline discovery and diff classification against it are separate, not-yet-implemented follow-on tasks (E40_S07_T02, E40_S07_T03); this step only writes it.

Epic ID continuation. The next free E## is one past the highest epic number found under both --epics-dir and the canonical project/board/epics/, so generated epics always continue the existing board's numbering and never collide with an epic already on it.

Evidence honesty. apply-subsystem-cap.sh's kept entries carry only path, rank, score, files, and lines — not the richer per-candidate signals (manifests, test_paths, doc_paths, signals) that discover-subsystems.sh computes internally but does not pass through the cap step. Each generated epic's Purpose section says exactly this, and points at /uncharted segment <path> for a full understanding document before the epic is broken into stories. Never fabricate deeper Purpose detail than the kept entry actually supports.

Verifying the read-only guarantee. After a full onboard run (discovery → cap → epic generation) against a repository containing application code, confirm the guarantee held:

git status --porcelain

Every line must start with a path under project/. Any other path in that output is a defect — onboard mode has no legitimate reason to touch it — and the run should be treated as failed even if every script above exited 0.

git status --porcelain has a blind spot: git does not track empty directories, so a run that creates (and leaves behind) an empty directory outside project/ — for example from a misconfigured or typo'd --epics-dir/--json-out — would pass this check while still having violated the guarantee. write-backfilled-epics.sh's write-path guard resolves its target paths before creating anything, specifically so this case cannot arise from a rejected path, but when verifying by hand it is worth also diffing the raw filesystem tree, which has no such blind spot:

find . -mindepth 1 ! -path './project/*' ! -path './project' -newer <timestamp-file-from-before-the-run>

An empty result confirms nothing outside project/ was even touched, not merely that nothing outside project/ ended up tracked by git.

ExitMeaning
0Epics written (including a kept array of length zero: 0 epics is a valid outcome).
1Usage error — unknown flag, missing value.
2Input error — the report is missing, unreadable, not JSON, or has no kept array.
3Write-path guard — --epics-dir or --json-out resolved outside <repo-root>/project/.
4Write failure — an epic file could not be written, or an existing epic file could not be read while computing ID continuation.

Updating PROJECT_SUMMARY.md from onboard evidence

Live as of E40_S04_T05, and reused by both onboard modes since E20_S08_T03 — the conversational default's own Step 5 above hands off here too, substituting its converged understanding for the kept array as the evidence source described below. Nested under Legacy mode structurally only because it was written before the conversational path existed; treat "Steps A-D" as shared, not legacy-only.

This is the last step of an onboard run, after the backfilled epics (legacy) or [ARCH] items (conversational) above have been written (or confirmed skipped). Its job is to close the gap the epic itself describes: a project adopting Jenga should not end up with a populated board sitting underneath a PROJECT_SUMMARY.md that still reads as if the codebase were empty.

This is a scrum-master action, not a script. Nothing under skills/j-uncharted/scripts/ writes PROJECT_SUMMARY.md, and the developer agent never touches it either — both agents/developer.md and agents/scrum-master.md already establish PROJECT_SUMMARY.md as scrum-master-owned, sole writer, no exceptions, and onboard does not get to be the exception just because the content originated from an automated discovery pass. Whichever agent is driving onboard performs the scripted steps above itself, but for this step it hands the drafting and the write to the scrum-master rather than doing it inline.

Inputs — reuse the evidence already produced, derive nothing new:

  • The onboard understanding document(s) under project/rapports/analysis/ written by run-engine.sh --mode onboard (in particular their Purpose and Structure sections).
  • The kept array from apply-subsystem-cap.sh — the same subsystems that became backfilled epics, with the same path, rank, score, files, and lines fields described under Evidence honesty above. Do not re-run discovery or invent detail those entries don't carry; if the epics' Purpose sections had to point at /uncharted segment <path> for deeper detail, the summary draft is bound by the same limit.

Step A — Draft, don't write yet. From the inputs above, draft replacement text for two sections of project/PROJECT_SUMMARY.md:

  • Overview — what the project is, in the terms the onboard evidence actually supports (what it does, for whom, at what scale), not a generic description that would fit any codebase.
  • Architecture & Structure — one entry per kept subsystem: what it is and how it relates to the others (depends on, is depended on by, sits alongside). This is prose about responsibilities and relationships, not a listing of file paths. A draft that reads as "src/, lib/, api/" with no relationship stated has failed this step, even if every path is correct.

Step B — Check both sections for existing content before proposing anything. A section counts as a stub only if its body is empty, whitespace-only, or is (or is limited to) the literal placeholder text from skills/j-init/assets/PROJECT_SUMMARY_template.md — _To be completed._. Anything else — a sentence, a partial list, a paragraph someone already wrote by hand — is real, non-stub content, however short, and is never silently overwritten. Check the Overview and Architecture & Structure sections independently; one can be a stub while the other is not.

Step C — Present for confirmation, every time, stub or not. Consistent with the confirm-before-writing convention segment mode already uses at its Step 6, and with Confirm before writing to the board under Constraints below (which this step extends explicitly to PROJECT_SUMMARY.md, since that file sits outside project/board/): show the drafted Overview and Architecture & Structure text in the session before writing anything. What is offered depends on what Step B found:

  • Both sections are stubs. Show the draft and ask for a straight go/no-go:

    Ready to populate PROJECT_SUMMARY.md's Overview and Architecture & Structure from the onboard
    evidence?
    1. Write it as drafted
    2. Revise — change the draft before writing
    3. Skip — leave PROJECT_SUMMARY.md untouched
    4. Other (describe below)
  • Either section has real, non-stub content. Never overwrite it by default. Present the numbered choice from the task's Acceptance Criteria, per the Interaction Pattern in CLAUDE.md:

    PROJECT_SUMMARY.md's <Overview and/or Architecture & Structure> section already has content.
    How should the onboard findings be applied?
    1. Merge — integrate the onboard findings into the existing text, keeping what's there
    2. Replace — overwrite the existing section with the onboard draft
    3. Skip — leave this section untouched
    4. Other (describe below)

    Ask this once per affected section if only one of the two is non-stub, or once covering both if both are. Replace is the only option that removes existing prose. Merge means the scrum-master integrates the two — existing text stays, onboard findings are woven in or appended — never a silent supersede dressed up as a merge.

Silence, a counter-question, or an ambiguous reply is not consent, the same as at segment's Step 6 — re-ask rather than proceeding.

Step D — Write, scoped to exactly what was confirmed. Only the scrum-master writes, only to project/PROJECT_SUMMARY.md, and only the section(s) and content actually confirmed in Step C — a "skip" on one section must not carry an incidental edit to it from a "replace" on the other. Like epic generation above it, "skip" on both sections is a valid outcome, not a failure: a run that leaves PROJECT_SUMMARY.md untouched still respects the read/write surface named under The hard constraint above, since that file was never a required write, only a permitted one.

Closing suggestion — j.conventions (non-blocking)

The very last thing onboard does, in both modes (conversational default and --legacy), after the PROJECT_SUMMARY.md step above has finished or been skipped: run bash "$([ -f scripts/conventions-suggest.sh ] && echo scripts/conventions-suggest.sh || echo node_modules/@jenga-ai/agent/scripts/conventions-suggest.sh)" and print its output, if any (a one-line tip to run j.conventions; it prints nothing when the project already has a conventions.json).

This is a non-blocking suggestion, not a question. It must not interrupt onboard's conversational flow (it runs only after the convergence loop, the board items and the PROJECT_SUMMARY.md step are complete), must not change its convergence or exit status, and must not halt the run, ask a blocking question, or run j.conventions on the user's behalf. The script always exits 0 and writes nothing, so it adds nothing to the output surface named under The hard constraint. If it cannot be run or prints nothing, say nothing and finish. Only onboard has this step: segment, import and refresh do not.

refresh

Incremental re-scan for a codebase that has already been through onboard at least once. Detects what changed since the last scan and only reinvestigates the delta, so keeping the board and graph current does not mean re-running the whole of onboard every time. Like onboard, refresh has the same bare-vs---legacy split (see the Invocation Contract table above) — read Conversational Elicitation above (Human-Oracle-Availability Limitation, Directory Triage, Convergence Loop, Multi-Session Persistence) before running the conversational default. Everything below only sequences those shared mechanics, plus the three baseline/diff scripts introduced by this story (E40_S07), for refresh's own scope — it does not redefine any of them. refresh is also bound, without exception or restatement, by the Constraints section below — read-only against application code, confirm before writing to the board, no new rapport type — the same as every other mode.

refresh introduces no new understanding mechanism. Every node, epic, story, and task it writes goes through exactly the same write paths onboard already uses — the Convergence Loop for the conversational default, write-backfilled-epics.sh for --legacy. refresh only changes which candidates reach those paths: find-scan-baseline.sh (E40_S07_T02) locates a baseline and diff-since-baseline.sh (E40_S07_T03) classifies each previously-known candidate as unchanged/changed/new/removed before either write path ever runs.

Baseline discovery and diff — shared by both modes

Read find-scan-baseline.sh's and diff-since-baseline.sh's own header comments before invoking either — their exact flag names and exit-code numbers are load-bearing for this sequencing, and are not restated in full here (per Shared Investigative Engine's "do not restate in prose what these scripts do step by step" convention above).

Step 1 — run fresh discovery once, keep it. Both the diff below and (for --legacy) the backfill step later need the same fresh discover-subsystems.sh output, so it is captured once here rather than re-run per step — the same pattern onboard's own Step 1 already uses:

DISCOVERY_JSON=$(bash skills/j-uncharted/scripts/discover-subsystems.sh <root>)

Step 2 — locate a baseline.

BASELINE_JSON=$(bash skills/j-uncharted/scripts/find-scan-baseline.sh <root>); RC=$?

Three outcomes, per the script's own exit-code contract:

  • Exit 0, "source": "scan-record". The precise case — a prior write-scan-record.sh run for this root was found under project/rapports/analysis/. Its candidates[] array (path + files/lines per candidate) is what Step 3 below diffs against.
  • Exit 0, "source": "inferred". No scan-record exists, but a provenance: backfilled epic or an [ARCH]-tagged board item whose docs: overlaps the root gave an approximate baseline commit via git history on that board file. This shape carries no candidates[] array at all — only baseline_commit and inferred_from[]. Say this plainly to the user before proceeding: an inferred baseline has no prior candidate set to compare membership against, so diff-since- baseline.sh (Step 3) can only ever classify candidates as unchanged/changed against it — its new/removed arrays stay empty by construction. A refresh against an inferred baseline cannot tell you a subsystem disappeared or a brand-new one appeared, only that a previously-known one did or didn't change. Do not imply otherwise to the user.
  • Exit 3 — no baseline found. Neither a scan-record nor board evidence exists for this root. Stop here and run onboard's own conversational default in full (its Steps 1-5 above, including its own scan-record write at the end) — this is the first scan for this root, and nothing else in this refresh subsection applies to that run. The next refresh invocation against this root then finds that scan-record at Tier 1. --legacy refresh takes the equivalent fallback: a full onboard --legacy run, which likewise ends by writing the first scan-record per its own "Write the scan-record once epic generation has succeeded" step above.

Any other exit (1 usage error, 2 environment error, 4 write failure) is not "no baseline" — surface the script's stderr and fix the invocation rather than falling back to onboard.

Step 3 — classify what changed.

DIFF_JSON=$(echo "$BASELINE_JSON" \
  | bash skills/j-uncharted/scripts/diff-since-baseline.sh --fresh <(echo "$DISCOVERY_JSON"))

--fresh is passed explicitly here (rather than letting the script re-run discovery itself) specifically so Step 1's $DISCOVERY_JSON is the one candidate set both this diff and the --legacy backfill step below reason about — one discovery pass per refresh run, not two that could in principle disagree if the tree changed between them. Read back unchanged, changed, new, and removed (each entry carrying at least path; changed entries also carry changed_files) — see the script's own header for the full shape. As Step 2 already flagged, a Tier 2 (inferred) baseline always yields empty new/removed arrays; that is documented, intentional behavior of the script, not a defect in this sequencing.

Conversational default

Runs when refresh is invoked without --legacy, once Steps 1-3 above have produced $DIFF_JSON.

  1. unchanged candidates are skipped entirely. No Familiarity Check, no Directory Triage entry, no prompt of any kind — they never enter the candidate set below at all.
  2. changed and new candidates proceed through Directory Triage (if applicable) and the Convergence Loop exactly as onboard's conversational default already does (its Steps 2-5 above) — no new understanding mechanism, no different gating, no different question templates. The candidate set fed to Directory Triage is the union of $DIFF_JSON's changed and new paths, in place of onboard's own full discover-subsystems.sh output:

    echo "$DIFF_JSON" | jq -r '.changed[].path, .new[].path' \
      | bash skills/j-uncharted/scripts/directory-triage.sh <root>

    Initialize persistence the same way onboard's own Step 3 does, with an id that distinguishes a refresh run from an onboard run over the same root:

    bash skills/j-uncharted/scripts/elicitation-state.sh init \
      --id "refresh-$(basename "$(cd "$root" && pwd)")-$(date -u +%Y%m%d)" --target "<root>" --cap 5
  3. removed candidates are never silently deleted or status-changed. For each entry in $DIFF_JSON's removed array:

    • Locate the corresponding graph node(s) in project/knowledge-graph/graph.json — the node(s) written for that path during the run that originally converged it. The stub schema (project/knowledge-graph/STUB_SCHEMA.md) has no dedicated path field on a node, so this correspondence is read from what the node's own label/description and edges recorded about the candidate at convergence time, not looked up by a formal key. Where more than one node plausibly corresponds and the traces don't disambiguate, say so under the board-item flag below rather than guessing which one to mark.
    • Mark it status: superseded, per the stub schema's Evidence-Wins Conflict Rule. That rule's superseded_by field is documented as "required when status: superseded... points at the node that superseded this one," and every worked example in the stub schema is a real replacement node — there is no successor node for a subsystem that was simply removed. Rather than inventing a new schema field to express "no successor" (the stub schema is deliberately minimal per its own header, and the Human-Oracle-Availability Limitation above already establishes the convention for an unrepresentable nuance: say it in the node's description text, not a new field), set superseded_by to a plain sentinel string that cannot be mistaken for a real node id — "removed-no-successor" — and state the reason in the node's own description, e.g. "Subsystem removed from the codebase as of the refresh run on <YYYY-MM-DD>; no successor node exists." This sentinel is refresh's own documented convention, not a stub-schema addition — if it's ever questioned, say so plainly rather than treating it as if the stub schema itself defined it.
    • Flag the corresponding board item for review, reusing existing mechanisms rather than a new frontmatter field (templates/SCRUM_BOARD_SCHEMA.md has no flagged_for_review field or equivalent, and adding one is a schema change for the scrum-master to make, not something this skill invents in passing):
      • If the item is already in a terminal status (Passed, Passed with remarks, Rejected, Done, Blocked), set reopened_on/reopened_reason per the schema's Reopen Tracking Fields, with a reason naming the removed path and the superseded node's id — without changing status itself. This keeps the flag visible on the item without the side effect of silently reopening it into active work; a human decides whether it actually needs reopening.
      • Regardless of status, also append a dated prose note to the board item's body — the same "Reconcile Note" convention already used elsewhere on this board (see e.g. project/board/stories/E40_S01_shared-investigative-engine.md's "Reconcile Note — 2026-09-23" section for a live example) — naming the removed path, the superseded node id, and the refresh run's date, so a reader sees why the item needs a look even before checking reopened_reason.
      • Never delete the board item and never change its status field as part of this flagging step — status changes remain the tester's exclusive responsibility (per agents/developer.md and agents/tester.md), and this is a flag for a human to act on, not an automatic resolution.

    Both the conversational path and --legacy (below) use this exact supersede-and-flag treatment for removed candidates — it is not conversational-only.

Write the scan-record once this run completes (elicitation-state.sh complete has been called), exactly as onboard's conversational default's own step does. Reuse $DISCOVERY_JSON from Step 1 above — the full fresh discovery output, not $DIFF_JSON's classified subset, and not only the changed/new candidates that went through the Convergence Loop — so the next baseline correctly reflects every candidate currently present, including the unchanged ones that were skipped this run:

bash skills/j-uncharted/scripts/write-scan-record.sh <<< "$DISCOVERY_JSON"

PROJECT_SUMMARY.md population applies the same way onboard's conversational default already hands it off — see Updating PROJECT_SUMMARY.md from onboard evidence above (Steps A-D), substituting this run's converged understanding (the changed/new candidates only) as the evidence source, the same substitution onboard's own conversational default already makes for its own evidence.

--legacy mode

Baseline discovery and diff are exactly the shared Steps 1-3 above — there is no --legacy-specific variant of find-scan-baseline.sh or diff-since-baseline.sh.

  1. Backfill only changed/new subsystems. apply-subsystem-cap.sh requires candidates[] entries carrying rank and score (see its own header) — fields diff-since-baseline.sh's changed/new entries do not carry (they carry path/files/lines, plus changed_files for changed). Building a synthetic report from $DIFF_JSON directly would therefore be missing fields apply-subsystem-cap.sh actually needs. Instead, filter Step 1's full $DISCOVERY_JSON — which already carries rank/score for every candidate — down to just the paths $DIFF_JSON classified as changed or new:

    CHANGED_NEW_PATHS=$(echo "$DIFF_JSON" | jq -c '[.changed[].path, .new[].path]')
    FILTERED_REPORT=$(echo "$DISCOVERY_JSON" | jq --argjson keep "$CHANGED_NEW_PATHS" \
      '.candidates |= map(select(.path as $p | $keep | index($p) != null))')
    
    echo "$FILTERED_REPORT" \
      | bash skills/j-uncharted/scripts/apply-subsystem-cap.sh --rapport "$DOC" \
      | bash skills/j-uncharted/scripts/write-backfilled-epics.sh

    This is the "backfill only" behavior the story's Design section agrees to (E40_S07 Design, point 6): existing epics for unchanged subsystems are never touched, never re-capped, never renumbered — they simply never enter apply-subsystem-cap.sh's input. The subsystem cap (default 8, apply-subsystem-cap.sh --cap N) still applies, but now scoped to the changed/new set only, not the full fresh discovery output the way a plain onboard --legacy run scopes it.

  2. removed candidates get the identical graph-node-supersede-and-flag treatment described under the conversational default's step 3 above — mark the corresponding graph node(s) status: superseded with the removed-no-successor sentinel, and flag the board item via reopened_on/reopened_reason (terminal items) plus a dated Reconcile Note (any item), never a silent delete or status change. This part of the behavior is identical between the two modes.
  3. Write the scan-record once epic generation succeeds, exactly as a plain onboard --legacy run's own step does. Reuse the full $DISCOVERY_JSON from Step 1 above — not the filtered changed/new-only report built for apply-subsystem-cap.sh — for the same reason the conversational default reuses the full set: the next baseline must reflect everything currently present, including the unchanged subsystems this run never touched:

    bash skills/j-uncharted/scripts/write-scan-record.sh <<< "$DISCOVERY_JSON"

Constraints

These hold across every mode:

  • Read-only against application code, with one exception: import mode writes an acquired source to a location the user has explicitly confirmed. Nothing else in this skill modifies, moves, or restructures a consumer's code.
  • Confirm before writing to the board. Proposals are presented for approval first, consistent with the brainstorm-before-commit convention. Since E20_S08_T03, this also covers Directory Triage's confirmation gate and each converged node's graph/board write in the conversational elicitation flow — same convention, applied to a new output type (graph nodes), not a new exception to it.
  • No new rapport type. Understanding documents use the existing analysis type and land in project/rapports/analysis/. Conversational elicitation's output (graph nodes + [ARCH] board items) is not an understanding document and does not need one — see Conversational Elicitation above for what it produces instead.
  • Never invent findings. If the evidence does not support a conclusion, say so under Open Questions (delivery-shaped/legacy paths) or state the uncertainty plainly in the node itself (conversational paths — see Human-Oracle-Availability Limitation above).
  • Deterministic work belongs in skills/j-uncharted/scripts/, agent judgement belongs here.
  • Existing zero-prompt behavior is never silently retired. onboard --legacy and segment --mode delivery reproduce exactly what /uncharted did before E20_S08_T03, with no behavior drift for a caller who keeps using them.

Entry Points

/uncharted is invocable directly, and is also offered automatically at the two moments it is most needed (E40_S05):

  • /init — when scaffolding detects a non-empty, non-Jenga-scaffolded directory, it offers onboard instead of proceeding as though the project were empty. Since E20_S08_T03, this offer surfaces both onboard modes — the user picks conversational (default) or --legacy at that point, per the mode choice this section describes; /init itself makes no decision about which is appropriate.
  • /reconcile — when its normal sync pass finds code with no board linkage, it offers segment for the affected paths. Since E20_S08_T03, this offer surfaces both segment modes the same way.

Both are offers, never automatic execution.


Session End

When this skill's session concludes, emit the following signal on its own line so the Jenga Router clears the active session:

[JENGA:SESSION_END:uncharted]

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.