x-internal-load-story-context

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

🔒 INTERNAL SKILL Esta skill é invocada apenas por outras skills (orquestradores). NÃO é destinada a invocação direta pelo usuário. Caller principal: x-implement-story (Phase 0 carve-out). Quarta skill da convenção x-internal-* (após x-internal-update-status pilot 0049-0005, x-internal-write-report 0049-0006, e x-internal-normalize-args 0049-0007). Primeira skill na subdir internal/plan/ (as três anteriores vivem em internal/ops/): o subdir reflete categoria funcional — esta skill orquestra lógica de planejamento (load+classify), não runtime ops (mutate/write).

Skill: x-internal-load-story-context

Purpose

Carve out Phase 0 of x-implement-story into a single-responsibility, read-only Bash pipeline. The skill:

1. Resolves and reads the story file under ai/epics/epic-XXXX/story-XXXX-YYYY.md.
2. Parses Section 1 (Dependencies) and validates each predecessor story reports status DONE (or an accepted synonym: MERGED / COMPLETE) inside ai/epics/epic-XXXX/execution-state.json.
3. Globs the 7 planning artifacts under ai/epics/epic-XXXX/plans/ and classifies each as fresh (artifact mtime ≥ story mtime), stale (artifact mtime < story mtime), or missing.
4. Assesses scope from Section 8 task count + Section 7 Gherkin scenario count: SIMPLE (≤ 4 tasks), STANDARD (5–7 tasks), COMPLEX (≥ 8 tasks).
5. Derives planning mode from artifact classification: PRE_PLANNED (all 7 fresh), HYBRID (some fresh, some stale or missing), INLINE (zero fresh).

The output is a single-line JSON envelope consumed by x-implement-story to drive the subsequent Phase 0.5 / Phase 1 / Phase 1.5 branching. The skill never mutates the filesystem.

Convention Anchors (x-internal-*)

Aspect	Value	Rationale
Path	internal/plan/x-internal-load-story-context/	internal/ prefix scopes visibility; plan/ aligns with sibling planning-category skills (x-plan-story, x-epic-map) and separates from internal/ops/ siblings that mutate state
Frontmatter visibility	internal	Generator filters these from /help menu
Frontmatter user-invocable	false	Declarative complement to visibility: internal
Body marker	> 🔒 **INTERNAL SKILL** block as first non-frontmatter content	Visible to humans browsing the repo; no parsing required
Allowed tools	Bash only	Minimal surface; all logic is a read-only shell pipeline built on jq + stat
Naming	x-internal-{subject}-{action}	Mirrors Rule 04 skill taxonomy; story-load-context = subject+action

Audit rule: Rule 22 (Lifecycle Integrity) validates every skill under internal/** satisfies all 6 anchors above. Violations fail the LifecycleIntegrityAuditTest.

Triggers

Bare-slash form is intentionally omitted — this skill is never invoked by a human typing /x-internal-load-story-context in chat. All invocations follow Rule 13 INLINE-SKILL pattern from a calling orchestrator:

Skill(skill: "x-internal-load-story-context",
      args: "--story-id story-0049-0011 --epic-id 0049")

Parameters

Parameter	Required	Default	Description
--story-id <id>	M	—	Story identifier (story-XXXX-YYYY canonical form)
--epic-id <id>	M	—	4-digit epic identifier (XXXX) — used to resolve ai/epics/epic-XXXX/

Response Contract

When successful, the skill writes a single-line JSON object to stdout:

Field	Type	Always Present	Description
storyFile	String	yes	Absolute path to the resolved story markdown
storyMtime	Number	yes	Unix epoch seconds of the story file's last modification
dependencies	Array<{id:String, status:String}>	yes	One entry per Section 1 blocker (empty array when Blocked By: —)
scope	String	yes	SIMPLE / STANDARD / COMPLEX
planningMode	String	yes	PRE_PLANNED / HYBRID / INLINE
artifacts	{fresh:Array<String>, stale:Array<String>, missing:Array<String>}	yes	Classification of the 7 planning artifact paths (relative to ai/epics/epic-XXXX/plans/)
taskCount	Number	yes	Count of ### TASK-XXXX-YYYY-NNN: headers under Section 8
scenarioCount	Number	yes	Count of Cenario: / Scenario: markers under Section 7

The seven planning-artifact basenames scanned under ai/epics/epic-XXXX/plans/ are:

1. plan-story-XXXX-YYYY.md (implementation plan)
2. arch-story-XXXX-YYYY.md (architecture plan)
3. tests-story-XXXX-YYYY.md (test plan)
4. tasks-story-XXXX-YYYY.md (task breakdown)
5. security-story-XXXX-YYYY.md (security assessment)
6. compliance-story-XXXX-YYYY.md (compliance assessment)
7. task-implementation-map-story-XXXX-YYYY.md (EPIC-0038 map)

Exit Codes

Code	Name	Condition	Message Format
0	SUCCESS	Context loaded and emitted	—
1	STORY_NOT_FOUND	ai/epics/epic-XXXX/story-XXXX-YYYY.md absent	Story file not found: <path>
2	DEPENDENCY_NOT_DONE	Any Section 1 blocker reports non-DONE status	Blocker <id> is <status>
3	EPIC_NOT_FOUND	ai/epics/epic-XXXX/ absent	Epic dir not found: ai/epics/epic-<id>

Workflow

Step 1 — Argument parsing and path resolution

Parse --story-id and --epic-id; reject unknown flags and missing required flags with exit 64 (sysexits EX_USAGE). Derive:

epic_dir="ai/epics/epic-${epic_id}"
story_file="${epic_dir}/${story_id}.md"
state_file="${epic_dir}/execution-state.json"
plans_dir="${epic_dir}/plans"

When ${epic_dir} is not a directory, exit 3 (EPIC_NOT_FOUND). When ${story_file} is not a regular file, exit 1 (STORY_NOT_FOUND).

Step 2 — Read story mtime and section markers

story_mtime=$(stat -f '%m' "${story_file}" 2>/dev/null \
            || stat -c '%Y' "${story_file}")

Extract Section 1 (Dependencies) between the ## 1. Dependências / ## 1. Dependencies header and the next ## header; extract Section 7 (Acceptance Criteria) and Section 8 (Tasks) likewise. The parser is tolerant: accepts both Portuguese (Dependências, Cenario) and English (Dependencies, Scenario) section titles since current stories under ai/epics/epic-XXXX/ are authored in Portuguese.

Step 3 — Parse dependencies from Section 1

Section 1 is a markdown table with columns Blocked By | Blocks. The Blocked By cell is either — (empty) or a comma-separated list of story IDs. Collect IDs; for each, resolve its status via execution-state.json:

status=$(jq -r ".stories[\"${dep_id}\"].status // \"UNKNOWN\"" \
         "${state_file}")

When state_file is absent, fall back to parsing the dep story's own **Status:** header inside its markdown file (supports epics where execution-state.json has not yet been initialized). Accepted synonyms for success: DONE, MERGED, COMPLETE, Concluída, Concluida.

On any blocker with non-DONE status, exit 2 (DEPENDENCY_NOT_DONE) with the offending ID and status in the error message.

Step 4 — Artifact freshness classification

For each of the 7 planning-artifact basenames:

artifact="${plans_dir}/${name}"
if [[ ! -f "${artifact}" ]]; then
  missing+=("${name}")
elif [[ $(stat -f '%m' "${artifact}" 2>/dev/null \
          || stat -c '%Y' "${artifact}") -ge ${story_mtime} ]]; then
  fresh+=("${name}")
else
  stale+=("${name}")
fi

Artifacts not present in the plans directory tree (common in early stories) populate missing. Artifacts with mtime strictly less than the story's mtime populate stale. The rest populate fresh.

Step 5 — Scope assessment

Count Section 8 tasks via grep -cE '^### TASK-[0-9]{4}-[0-9]{4}-[0-9]{3}:'. Classification:

Task count	Scope
≤ 4	SIMPLE
5–7	STANDARD
≥ 8	COMPLEX

Scenario count is computed for telemetry (Section 7 grep -cE '^(Cenario|Scenario):') but does not influence the scope label in this story; reserved for future tuning per story-0049-0011 §3.2.

Step 6 — Planning mode detection

Fresh artifact count	Planning mode
7 (all fresh)	PRE_PLANNED
1–6 (mixed)	HYBRID
0	INLINE

Step 7 — Emit response envelope

Compose the response using jq -n so the shape is authoritative and the stdout stream is a single line terminated by \n:

jq -nc \
  --arg storyFile "${story_file}" \
  --argjson storyMtime "${story_mtime}" \
  --argjson dependencies "${deps_json}" \
  --arg scope "${scope}" \
  --arg planningMode "${mode}" \
  --argjson artifacts "${artifacts_json}" \
  --argjson taskCount "${task_count}" \
  --argjson scenarioCount "${scenario_count}" \
  '{storyFile:$storyFile, storyMtime:$storyMtime,
    dependencies:$dependencies, scope:$scope,
    planningMode:$planningMode, artifacts:$artifacts,
    taskCount:$taskCount, scenarioCount:$scenarioCount}'

Exit 0.

Examples

Example 1 — Happy path: simple story, no dependencies, no planning yet

Skill(skill: "x-internal-load-story-context",
      args: "--story-id story-0049-0001 --epic-id 0049")

Output:

{"storyFile":"ai/epics/epic-XXXX/story-XXXX-0001.md","storyMtime":1745343600,"dependencies":[],"scope":"SIMPLE","planningMode":"INLINE","artifacts":{"fresh":[],"stale":[],"missing":["plan-story-XXXX-0001.md","arch-story-XXXX-0001.md","tests-story-XXXX-0001.md","tasks-story-XXXX-0001.md","security-story-XXXX-0001.md","compliance-story-XXXX-0001.md","task-implementation-map-story-XXXX-0001.md"]},"taskCount":3,"scenarioCount":4}

Exit: 0.

Example 2 — Dependency not DONE

Skill(skill: "x-internal-load-story-context",
      args: "--story-id story-0049-0008 --epic-id 0049")

Stderr:

Blocker story-0049-0001 is PENDING

Exit: 2.

Example 3 — Planning mode PRE_PLANNED

Given all 7 artifacts under ai/epics/epic-XXXX/plans/ with mtime ≥ story mtime, output includes "planningMode":"PRE_PLANNED" and every artifact in artifacts.fresh.

Exit: 0.

Example 4 — Boundary: COMPLEX scope (10 tasks)

Output contains "scope":"COMPLEX" and "taskCount":10. Exit: 0.

Example 5 — Missing story file

Skill(skill: "x-internal-load-story-context",
      args: "--story-id story-9999-0001 --epic-id 9999")

Stderr:

Epic dir not found: ai/epics/epic-XXXX

Exit: 3.

When the epic directory exists but the story file does not:

Stderr:

Story file not found: ai/epics/epic-XXXX/story-XXXX-9999.md

Exit: 1.

Outputs

Artifact	Path	Description
Response envelope	stdout	Single-line JSON matching the Response Contract
Error diagnostic	stderr	Single line, non-empty only on exit ≠ 0

No file is created or modified. The skill is strictly read-only (enforced by convention and by the allowed-tools: Bash frontmatter — no Write / Edit tool is available).

Error Handling

Scenario	Action
Missing required flag	Print usage: banner to stderr; exit 64 (sysexits EX_USAGE)
jq absent on PATH	Exit 127 with jq is required; abort before any stat
stat flavour mismatch (GNU vs BSD)	Try stat -f %m (BSD) first, fall back to stat -c %Y (GNU)
execution-state.json absent	Fall back to parsing each dep story's own **Status:** header
Dep story file absent AND state file absent	Treat dep status as UNKNOWN; exit 2
Section 1 table unparseable (malformed markdown)	Treat dependencies as empty; log warning to stderr; continue
Unknown section-title language	Try both Dependências / Dependencies, Cenario / Scenario; stop at first hit
task-implementation-map-* file name variant (legacy map-story-*)	Also accept map-story-XXXX-YYYY.md as the 7th artifact when the canonical name is missing

Performance Contract

Target: < 500 ms for a typical epic with 20 stories in execution-state.json and all 7 planning artifacts present. The implementation reads at most 9 files (1 story, 1 state, 7 artifacts via stat only — no body read) and spawns a single jq invocation for JSON assembly. No network I/O; no recursive traversal beyond ai/epics/epic-XXXX/plans/.

Testing

The story ships the following acceptance test scenarios, mirroring Section 7 of story-0049-0011:

1. Degenerate — no dependencies. story-0049-0001 reports dependencies=[] and valid scope / planningMode.
2. Dependency not DONE. Ancillary story depends on a blocker with PENDING status → exit 2, message "Blocker <id> is PENDING".
3. Fresh artifacts → PRE_PLANNED. Fabricate 7 artifacts with mtime > story; assert planningMode=PRE_PLANNED.
4. Missing story file. --story-id story-9999-0001 with epic dir absent → exit 3; epic dir present but story missing → exit 1.
5. Boundary — COMPLEX scope. Story with 10 tasks → scope=COMPLEX.

Goldens under src/test/resources/golden/internal/plan/x-internal-load-story-context/ lock the SKILL.md rendering. Coverage requirement: ≥ 95% line / ≥ 90% branch across the invoking Bash codepaths.

Generator Filter Contract

The ia-dev-env generator MUST exclude skills with visibility: internal from:

1. The .claude/README.md skill-inventory table.
2. The /help menu listing surfaced by Claude Code.
3. User-facing autocomplete in the chat input.

Internal skills are still copied into .claude/skills/ (flat layout) so Skill(skill: "x-internal-...") invocations from other skills resolve correctly. The invariant: user cannot see them; orchestrators can invoke them.

Telemetry

Internal skills DO NOT emit phase.start / phase.end markers — telemetry is produced by the invoking orchestrator (the phase wrapping the orchestrator's own step is the correct aggregation boundary). Passive hooks still capture tool.call for the underlying Bash invocation.

Reference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle Integrity Audit), ADR-0010 (Interactive Gates Convention — exempts internal skills from the 3-option menu contract).

Integration Notes

Skill	Relationship	Context
x-implement-story	caller (primary)	Phase 0 carve-out: the skill's stdout envelope replaces ~140 inline lines previously executed by the orchestrator
x-implement-epic	caller (indirect, via story-0049-0019 downstream)	Consumes the same envelope when iterating stories at the epic scope
x-internal-update-status	peer	Sibling x-internal-* skill; this skill reads execution-state.json, the other mutates it; both acquire the same <file>.lock when their lifetimes overlap (this skill uses flock -s shared lock)
x-internal-normalize-args	delegate (optional)	Future refactor: the argument parser in Step 1 can be replaced by a call to x-internal-normalize-args once its schema-driven mode covers read-only skills
x-reconcile-status	consumer (peer)	Reads the same story **Status:** header this skill inspects; no shared mutation

Downstream stories that depend on this carve-out: story-0049-0019 (orchestrator consumes the envelope and deletes the inline Phase 0 block).

Full workflow detail (argument-parser rejection matrix, section-extraction regex catalogue, artifact-classification edge cases, and the execution-state.json schema contract) lives in references/full-protocol.md per ADR-0011.