@danypops/papyrus 0.12.0 → 0.13.1

package/extension/src/rules.ts

@@ -1,14 +1,14 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { RULE_STATUS_PRESENTATION, severityColor } from "./artifact-status-presentation.ts";
 import { callService } from "./service-client.ts";
 
-const RULE_GLYPHS: Record<string, string> = { active: "●", deprecated: "○" };
-
-export function ruleRowMeta(rule: Artifact): string {
-	const severity = typeof rule.extra["severity"] === "string" ? rule.extra["severity"].toUpperCase() : "INFO";
+export function ruleRowMeta(rule: Artifact, theme: Theme): string {
+	const severity = typeof rule.extra["severity"] === "string" ? rule.extra["severity"] : "info";
+	const severityText = theme.fg(severityColor(severity), severity.toUpperCase());
 	const condition = typeof rule.extra["condition"] === "string" ? `when ${rule.extra["condition"]}` : "always";
-	return `${severity} · ${condition}`;
+	return `${severityText} · ${condition}`;
 }
 
 export function ruleInjectionPreview(rule: Pick<Artifact, "title" | "body" | "extra">): string {
@@ -23,7 +23,7 @@ export async function showRules(ctx: ExtensionCommandContext): Promise<void> {
 		title: "Rules",
 		listOperation: "rules.list",
 		statusOrder: ["active", "deprecated"],
-		glyphs: RULE_GLYPHS,
+		presentation: RULE_STATUS_PRESENTATION,
 		rowMeta: ruleRowMeta,
 		actions: (rule) => ["Show details", "Preview injection", "Link gated task", rule.status === "active" ? "Disable" : "Enable"],
 		handleAction: async (choice, rule, commandCtx) => {

package/extension/src/skill-catalog-footprint.ts

@@ -0,0 +1,183 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "../../src/constants.ts";
+
+/**
+ * Pi-native skills (SKILL.md) carry a real, permanent context tax independent of Papyrus:
+ * per Pi's own docs, every discovered skill's name+description is injected into the system
+ * prompt unconditionally at startup (the Agent Skills spec's "catalog" tier, ~50-100 tokens
+ * per skill). This module measures that tax by replicating Pi's own documented discovery
+ * rules (docs/skills.md "Locations" section) directly against the filesystem, rather than
+ * trying to parse it back out of the assembled system prompt -- Pi does not document (and
+ * this repo must not depend on) the exact wire format it uses to inject the catalog, so
+ * re-deriving the same inputs Pi itself reads is the robust approach, not a fragile one.
+ * Package-declared skills (pi.skills in package.json / packages' own skills/ directories)
+ * are deliberately out of scope: enumerating every installed package for skill declarations
+ * is a materially larger, slower scan than reading a handful of known directories, and this
+ * tool is a budget estimate, not an exhaustive audit.
+ */
+export interface SkillCatalogEntry {
+	name: string;
+	description: string;
+	location: string;
+	characters: number;
+	estimatedTokens: number;
+}
+
+export interface SkillCatalogFootprint {
+	entries: SkillCatalogEntry[];
+	totalCharacters: number;
+	totalEstimatedTokens: number;
+	scannedDirectories: string[];
+}
+
+export const SKILL_SCAN_MAX_DEPTH = 6;
+export const SKILL_SCAN_MAX_DIRECTORIES = 2000;
+export const SKILL_SCAN_MAX_SKILLS = 500;
+
+function unquote(value: string): string {
+	if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+		return value.slice(1, -1);
+	}
+	return value;
+}
+
+/**
+ * Extracts `name` and `description` from a SKILL.md's YAML frontmatter, tolerating the
+ * folded (`>`) and literal (`|`) block-scalar forms real-world skills commonly use for
+ * multi-line descriptions. Deliberately not a general YAML parser -- only the two fields
+ * the Agent Skills spec requires are extracted; anything else in the frontmatter is ignored.
+ */
+export function parseSkillFrontmatter(content: string): { name: string; description: string } | null {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) return null;
+	const lines = match[1]!.split(/\r?\n/);
+	let name = "";
+	let description = "";
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index]!;
+		const nameMatch = line.match(/^name:\s*(.*)$/);
+		if (nameMatch) {
+			name = unquote(nameMatch[1]!.trim());
+			continue;
+		}
+		const descriptionMatch = line.match(/^description:\s*(.*)$/);
+		if (!descriptionMatch) continue;
+		const rest = descriptionMatch[1]!.trim();
+		if (rest === ">" || rest === ">-" || rest === "|" || rest === "|-") {
+			const collected: string[] = [];
+			let cursor = index + 1;
+			while (cursor < lines.length && (lines[cursor] === "" || /^\s+/.test(lines[cursor]!))) {
+				collected.push(lines[cursor]!.trim());
+				cursor++;
+			}
+			description = collected.join(rest.startsWith("|") ? "\n" : " ").trim();
+			index = cursor - 1;
+		} else {
+			description = unquote(rest);
+		}
+	}
+	if (!name || !description) return null;
+	return { name, description };
+}
+
+/** True at the filesystem root on POSIX (`/`) and Windows (`C:\`, `D:\`, ...). */
+function isFilesystemRoot(path: string): boolean {
+	return dirname(path) === path;
+}
+
+/**
+ * Global and project skill directories per Pi's own documented discovery rules, plus any
+ * explicit paths configured in settings.json's `skills` array. Project directories are
+ * collected walking from `cwd` up to the git repository root (or filesystem root when not
+ * in a repo), matching "up to git repo root, or filesystem root when not in a repo" exactly.
+ */
+export function discoverSkillDirectories(homeDirectory: string, cwd: string, settingsSkills: readonly string[] = []): string[] {
+	const directories = [join(homeDirectory, ".pi", "agent", "skills"), join(homeDirectory, ".agents", "skills")];
+	let current = cwd;
+	for (let depth = 0; depth < SKILL_SCAN_MAX_DIRECTORIES; depth++) {
+		directories.push(join(current, ".pi", "skills"), join(current, ".agents", "skills"));
+		if (existsSync(join(current, ".git")) || isFilesystemRoot(current)) break;
+		current = dirname(current);
+	}
+	directories.push(...settingsSkills);
+	return [...new Set(directories)];
+}
+
+interface ScanContext {
+	entries: SkillCatalogEntry[];
+	seenLocations: Set<string>;
+	directoriesVisited: number;
+}
+
+/** Root-level .md files count as individual skills only in these two locations, per Pi's docs. */
+function allowsRootMarkdownFiles(directory: string): boolean {
+	return directory.endsWith(join(".pi", "agent", "skills")) || directory.endsWith(join(".pi", "skills"));
+}
+
+function recordSkillFile(context: ScanContext, path: string): void {
+	if (context.seenLocations.has(path) || context.entries.length >= SKILL_SCAN_MAX_SKILLS) return;
+	let content: string;
+	try {
+		content = readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+	const parsed = parseSkillFrontmatter(content);
+	if (!parsed) return;
+	context.seenLocations.add(path);
+	const characters = parsed.name.length + parsed.description.length;
+	context.entries.push({
+		name: parsed.name,
+		description: parsed.description,
+		location: path,
+		characters,
+		estimatedTokens: Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN),
+	});
+}
+
+function walk(context: ScanContext, directory: string, depth: number, allowRootMarkdown: boolean): void {
+	if (depth > SKILL_SCAN_MAX_DEPTH || context.directoriesVisited >= SKILL_SCAN_MAX_DIRECTORIES) return;
+	context.directoriesVisited++;
+	let names: string[];
+	try {
+		names = readdirSync(directory);
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		if (name === "node_modules" || name === ".git") continue;
+		const path = join(directory, name);
+		let stat: ReturnType<typeof statSync>;
+		try {
+			stat = statSync(path);
+		} catch {
+			continue;
+		}
+		if (stat.isDirectory()) {
+			const skillFile = join(path, "SKILL.md");
+			if (existsSync(skillFile)) recordSkillFile(context, skillFile);
+			else walk(context, path, depth + 1, false);
+		} else if (allowRootMarkdown && depth === 0 && name.toLowerCase().endsWith(".md")) {
+			recordSkillFile(context, path);
+		}
+	}
+}
+
+/** Bounded, best-effort scan: a missing or unreadable directory is silently skipped, not an error. */
+export function scanSkillCatalogFootprint(directories: readonly string[]): SkillCatalogFootprint {
+	const context: ScanContext = { entries: [], seenLocations: new Set(), directoriesVisited: 0 };
+	const scanned: string[] = [];
+	for (const directory of directories) {
+		if (!existsSync(directory) || !statSync(directory).isDirectory()) continue;
+		scanned.push(directory);
+		walk(context, directory, 0, allowsRootMarkdownFiles(directory));
+	}
+	const entries = context.entries.sort((a, b) => b.characters - a.characters);
+	return {
+		entries,
+		totalCharacters: entries.reduce((sum, entry) => sum + entry.characters, 0),
+		totalEstimatedTokens: entries.reduce((sum, entry) => sum + entry.estimatedTokens, 0),
+		scannedDirectories: scanned,
+	};
+}

package/extension/src/skills.ts

@@ -3,11 +3,10 @@ import type { Artifact } from "../../src/domain/artifact.ts";
 import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
 import type { TaskGraph } from "../../src/task-service.ts";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { SKILL_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
 import { callService } from "./service-client.ts";
 import { showTaskGraph } from "./task-graph.ts";
 
-const SKILL_GLYPHS: Record<string, string> = { active: "●", deprecated: "○" };
-
 function strings(value: unknown): string[] {
 	return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
 }
@@ -73,7 +72,7 @@ export async function showSkills(ctx: ExtensionCommandContext): Promise<void> {
 		title: "Skills",
 		listOperation: "skills.list",
 		statusOrder: ["active", "deprecated"],
-		glyphs: SKILL_GLYPHS,
+		presentation: SKILL_STATUS_PRESENTATION,
 		rowMeta: skillRowMeta,
 		actions: (skill) => [
 			"Show details",

package/extension/src/task-widget.ts

@@ -8,6 +8,18 @@ export interface TaskWidgetRow {
 	hasOpenChildren: boolean;
 	active: boolean;
 	focusStatus?: "active" | "paused";
+	/**
+	 * Task containment is a DAG, not a tree: a task may have more than one parent (design
+	 * decision -- see decide-and-execute... no single-parent enforcement was ever wanted).
+	 * This bounded widget still renders one spanning tree (it only has room for one position
+	 * per task), so a multi-parent task is only ever shown once, under whichever parent this
+	 * walk reaches first -- exactly the git-log-graph / npm-ls-dedup pattern of picking one
+	 * canonical position and flagging the rest, rather than silently dropping the information.
+	 * parentCount > 1 means "this task also lives under other parents not shown here" --
+	 * the full DAG (every parent edge, not just one) is always available via the task graph's
+	 * composition view, which renders true multi-parent edges through Mermaid's flowchart layout.
+	 */
+	parentCount: number;
 }
 
 export interface TaskWidgetProjection {
@@ -36,7 +48,7 @@ export function buildTaskWidgetProjection(
 		if (!node) return;
 		visited.add(id);
 		const open = isOpen(node.task);
-		if (open) ordered.push({ task: node.task, depth: openDepth, hasOpenChildren: false, active: node.active === true, focusStatus: node.focusStatus });
+		if (open) ordered.push({ task: node.task, depth: openDepth, hasOpenChildren: false, active: node.active === true, focusStatus: node.focusStatus, parentCount: node.parentIds.length });
 		const childDepth = open ? openDepth + 1 : openDepth;
 		for (const childId of node.childIds) visit(childId, childDepth);
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/constants.ts

@@ -30,6 +30,23 @@ export const PAPYRUS_TASK_FOCUS_CHANNEL = "papyrus.task-focus.v1";
 export const PAPYRUS_TASK_FOCUS_SCHEMA = "papyrus.task-focus/v1";
 export const CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN = 4;
 
+/**
+ * A Papyrus Rule's condition+action+body is injected into EVERY relevant turn's system
+ * prompt for the lifetime of the rule -- the same permanent, always-on-context role as an
+ * Agent Skill's name+description (per the Agent Skills spec's progressive-disclosure model:
+ * metadata ~100 tokens, always loaded; full instructions <5000 tokens, loaded only on
+ * activation). Anthropic's own context-engineering guidance is not a hard length rule but a
+ * signal-density principle -- "the smallest possible set of high-signal tokens", explicitly
+ * NOT "minimal means short" -- so RULE_TEXT_SOFT_TARGET_CHARACTERS is a target to aim for,
+ * not a rejection threshold. RULE_TEXT_HARD_LIMIT_CHARACTERS is the actual enforced ceiling,
+ * generous enough to allow a real rule to breathe, but catching genuinely runaway bloat that
+ * would tax every single turn. Above the hard limit, split into a short Rule (condition +
+ * the invariant) plus a linked Doc for full reasoning -- the pattern this codebase's own
+ * active rules already use via "Source: Lexicon <path>" references.
+ */
+export const RULE_TEXT_SOFT_TARGET_CHARACTERS = 600;
+export const RULE_TEXT_HARD_LIMIT_CHARACTERS = 4000;
+
 /** Compact task-context limits keep recurring prompt injection bounded. */
 export const TASK_CONTEXT_CURRENT_LIMIT = 3;
 export const TASK_CONTEXT_REJECTED_LIMIT = 3;
@@ -57,6 +74,28 @@ export const SKILL_MAX_ENUM_VALUES = 32;
 export const SKILL_MAX_BLUEPRINTS = 100;
 export const SKILL_MAX_LINKS = 500;
 export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
+
+/**
+ * Skills are special: invoking one queries Papyrus for whatever it's actually graph-linked
+ * to (existing Tasks/Rules/Docs via ordinary edges, not just its own static body/extra
+ * fields), and a Skill can link to and invoke other Skills. Both traversals are bounded and
+ * cycle-safe -- a skill-calls-skill edge cycle must not infinite-loop invocation, matching
+ * the cycle-safety discipline already established for ConversationJournal reply chains and
+ * task dependency graphs.
+ */
+export const SKILL_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
+export const SKILL_INVOCATION_MAX_CALL_DEPTH = 4;
+
+/**
+ * At the core, a workflow Skill creates Tasks and begins a pipeline -- an Ansible playbook or
+ * a Jenkins job, not just a text prompt. A pipeline step can itself trigger another workflow
+ * Skill's run (a nested sub-pipeline, like a Jenkins job triggering a downstream job and
+ * waiting for it), bounded and cycle-safe: a real skill-calls-skill cycle during EXECUTION
+ * (not just invocation preview) must fail loudly and roll back the whole atomic run, not
+ * silently truncate, since a silently-truncated pipeline would leave a confusing partial
+ * Task graph behind.
+ */
+export const SKILL_WORKFLOW_MAX_NESTING_DEPTH = 4;
 export const SKILL_RUN_ID_MAX_LENGTH = 64;
 /** Bounded automatic Pi continuations while a focused Papyrus Task remains. */
 export const TASK_DRIVER_MAX_TURNS = 20;

package/src/domain/skill-definition.ts

@@ -46,10 +46,29 @@ export interface SkillTaskBlueprint {
 	extra?: Record<string, unknown>;
 }
 
+/**
+ * A pipeline step that nests another workflow Skill's run inside this one -- the Jenkins
+ * "trigger downstream job and wait" / Ansible "include_tasks" primitive. `skillId` is late-
+ * bound: existence and workflow-subtype are checked at execution time (skill-execution.ts),
+ * not here, since this validator has no store access. `dependsOn`/`parent` place this step in
+ * the SAME dependency graph as ordinary task blueprints -- a task can depend on a skill-call
+ * ref (meaning: depend on every task the nested run creates), and a skill-call's own `parent`
+ * contains the nested run's root tasks under an outer task.
+ */
+export interface SkillCallBlueprint {
+	ref: string;
+	title: string;
+	skillId: string;
+	arguments?: Record<string, unknown>;
+	dependsOn?: string[];
+	parent?: string;
+}
+
 export interface SkillBlueprints {
 	docs: SkillDocBlueprint[];
 	rules: SkillRuleBlueprint[];
 	tasks: SkillTaskBlueprint[];
+	skills: SkillCallBlueprint[];
 }
 
 export interface SkillBlueprintLink {
@@ -142,19 +161,34 @@ function placeholders(value: unknown, result: Set<string> = new Set()): Set<stri
 	return result;
 }
 
-function assertAcyclic(tasks: SkillTaskBlueprint[]): void {
-	const byRef = new Map(tasks.map((task) => [task.ref, task]));
+/** Steps sharing one dependency graph: ordinary tasks and skill-call pipeline steps alike. */
+interface DependentStep {
+	ref: string;
+	dependsOn?: string[];
+}
+
+function assertAcyclic(steps: DependentStep[]): void {
+	const byRef = new Map(steps.map((step) => [step.ref, step]));
 	const visiting = new Set<string>();
 	const visited = new Set<string>();
 	const visit = (ref: string): void => {
-		if (visiting.has(ref)) throw new Error(`skill task dependency cycle includes "${ref}"`);
+		if (visiting.has(ref)) throw new Error(`skill step dependency cycle includes "${ref}"`);
 		if (visited.has(ref)) return;
 		visiting.add(ref);
 		for (const dependency of byRef.get(ref)?.dependsOn ?? []) visit(dependency);
 		visiting.delete(ref);
 		visited.add(ref);
 	};
-	for (const task of tasks) visit(task.ref);
+	for (const step of steps) visit(step.ref);
+}
+
+function validateSkillCallBlueprint(value: unknown): SkillCallBlueprint {
+	const source = record(value, "skill call blueprint");
+	const ref = string(source["ref"], "skill call blueprint ref");
+	if (!NAME_PATTERN.test(ref)) throw new Error(`invalid skill blueprint ref "${ref}"`);
+	const title = string(source["title"], "skill call blueprint title");
+	const skillId = string(source["skillId"], "skill call blueprint skillId");
+	return { ...source, ref, title, skillId } as SkillCallBlueprint;
 }
 
 export function validateSkillDefinition(value: unknown): SkillDefinition {
@@ -165,23 +199,38 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 	const docs = array(rawBlueprints["docs"] ?? [], "skill doc blueprints").map((entry) => validateBlueprint<SkillDocBlueprint>(entry, "doc"));
 	const rules = array(rawBlueprints["rules"] ?? [], "skill rule blueprints").map((entry) => validateBlueprint<SkillRuleBlueprint>(entry, "rule"));
 	const tasks = array(rawBlueprints["tasks"] ?? [], "skill task blueprints").map((entry) => validateBlueprint<SkillTaskBlueprint>(entry, "task"));
-	const all = [...docs, ...rules, ...tasks];
+	const skillCalls = array(rawBlueprints["skills"] ?? [], "skill call blueprints").map(validateSkillCallBlueprint);
+	const all = [...docs, ...rules, ...tasks, ...skillCalls];
 	if (all.length === 0 || all.length > SKILL_MAX_BLUEPRINTS) throw new Error(`skill blueprints must contain 1-${SKILL_MAX_BLUEPRINTS} artifacts`);
 	const refs = new Set<string>();
 	for (const blueprint of all) {
 		if (refs.has(blueprint.ref)) throw new Error(`duplicate skill blueprint ref "${blueprint.ref}"`);
 		refs.add(blueprint.ref);
 	}
+	// Tasks and skill-call pipeline steps share one dependency graph: a task may depend on a
+	// skill-call ref (meaning: depend on every task that nested run creates), and vice versa.
+	const stepRefs = new Set<string>([...tasks.map((task) => task.ref), ...skillCalls.map((call) => call.ref)]);
 	for (const task of tasks) {
 		if (task.dependsOn !== undefined && !Array.isArray(task.dependsOn)) throw new Error(`skill task "${task.ref}" dependsOn must be an array`);
 		for (const dependency of task.dependsOn ?? []) {
-			if (!tasks.some((candidate) => candidate.ref === dependency)) throw new Error(`unknown skill task dependency ref "${dependency}"`);
+			if (!stepRefs.has(dependency)) throw new Error(`unknown skill task dependency ref "${dependency}"`);
 		}
+		// parent stays task-only: containment under a skill-call step's exploded task SET has no
+		// single natural parent, so parent must name an actual task blueprint.
 		if (task.parent !== undefined && !tasks.some((candidate) => candidate.ref === task.parent)) {
 			throw new Error(`unknown skill task parent ref "${task.parent}"`);
 		}
 	}
-	assertAcyclic(tasks);
+	for (const call of skillCalls) {
+		if (call.dependsOn !== undefined && !Array.isArray(call.dependsOn)) throw new Error(`skill call "${call.ref}" dependsOn must be an array`);
+		for (const dependency of call.dependsOn ?? []) {
+			if (!stepRefs.has(dependency)) throw new Error(`unknown skill call dependency ref "${dependency}"`);
+		}
+		if (call.parent !== undefined && !tasks.some((candidate) => candidate.ref === call.parent)) {
+			throw new Error(`unknown skill call parent ref "${call.parent}"`);
+		}
+	}
+	assertAcyclic([...tasks, ...skillCalls]);
 	for (const name of placeholders(all)) {
 		if (!Object.hasOwn(inputs, name)) throw new Error(`unknown skill input placeholder "${name}"`);
 	}
@@ -196,7 +245,7 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 		return { from, relation, to };
 	});
 	if (links.length > SKILL_MAX_LINKS) throw new Error(`skill links exceed ${SKILL_MAX_LINKS}`);
-	return { version: 1, inputs, blueprints: { docs, rules, tasks }, links };
+	return { version: 1, inputs, blueprints: { docs, rules, tasks, skills: skillCalls }, links };
 }
 
 export function resolveSkillArguments(definition: SkillDefinition, value: unknown): Record<string, SkillArgumentValue> {

package/src/domain-services.ts

@@ -1,4 +1,9 @@
-import { ARTIFACT_SCOPE_MAX_ARTIFACTS } from "./constants.ts";
+import {
+	ARTIFACT_SCOPE_MAX_ARTIFACTS,
+	RULE_TEXT_HARD_LIMIT_CHARACTERS,
+	SKILL_INVOCATION_MAX_CALL_DEPTH,
+	SKILL_INVOCATION_MAX_LINKED_ARTIFACTS,
+} from "./constants.ts";
 import type { Artifact, CreateArtifactInput } from "./domain/artifact.ts";
 import type { ArtifactEventContext } from "./domain/artifact-event.ts";
 import { normalizeProjectRoot } from "./domain/task-scope.ts";
@@ -174,7 +179,27 @@ export interface CreateRuleInput {
 
 export type RuleTransition = "enable" | "disable";
 
+/**
+ * A Rule's condition+action+body is injected into every relevant turn for the rule's entire
+ * lifetime -- a permanent tax on every future turn's context budget, not a one-time cost.
+ * Rejects (rather than silently truncating or merely warning) once a rule is unambiguously
+ * bloated, since a silently-truncated rule would inject different text than what its author
+ * reviewed, and a warning nobody reads is not a bound. See RULE_TEXT_HARD_LIMIT_CHARACTERS's
+ * own comment in constants.ts for the research this threshold is grounded in.
+ */
+function assertRuleTextWithinBounds(condition: string | undefined, action: string | undefined, body: string | undefined): void {
+	const combined = (condition ?? "").length + (action ?? "").length + (body ?? "").length;
+	if (combined > RULE_TEXT_HARD_LIMIT_CHARACTERS) {
+		throw new Error(
+			`rule condition+action+body is ${combined} characters, exceeding the ${RULE_TEXT_HARD_LIMIT_CHARACTERS}-character bound. ` +
+				"A Rule is injected into every relevant turn for its entire lifetime -- this is a permanent context-budget tax, not a one-time cost. " +
+				"Split it: keep a short Rule (the condition and the invariant itself), and move the full reasoning, examples, and research into a linked Doc.",
+		);
+	}
+}
+
 export function createRule(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateRuleInput, context?: ArtifactEventContext): Artifact {
+	assertRuleTextWithinBounds(input.condition, input.action, input.body);
 	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
 	const rule = artifacts.create({
 		kind: "rule",
@@ -328,8 +353,7 @@ export function showSkill(artifacts: ArtifactStore, id: string): Artifact {
 	return artifacts.get(id, { tree: true })!;
 }
 
-export function skillInvocation(artifacts: ArtifactStore, id: string): string {
-	const skill = requireKind(artifacts, id, "skill");
+function skillInvocationBody(skill: Artifact): string {
 	if (skill.subtype === "artifact-template") {
 		return `Create an artifact using Papyrus template "${skill.title}".\ntemplate_id: ${skill.id}\nAsk for or infer all required template fields, then call the skills domain tool instantiate action.`;
 	}
@@ -356,6 +380,48 @@ export function skillInvocation(artifacts: ArtifactStore, id: string): string {
 	].join("\n");
 }
 
+/**
+ * Skills are special: invoking one queries Papyrus for the skill's real outgoing graph edges
+ * -- not just its own static body/extra fields -- so a Skill linked to existing Tasks, Rules,
+ * or Docs surfaces that linked context on invocation. A Skill can also link to and invoke
+ * OTHER Skills (any relation whose target is itself a Skill, e.g. the same "triggers" relation
+ * workflow execution already uses for skill-to-task edges): invoking the parent recursively
+ * composes the linked skill's own invocation. Bounded and cycle-safe -- a skill-calls-skill
+ * edge cycle degrades to a marker instead of infinite-looping, matching the cycle-safety
+ * discipline already established for ConversationJournal reply chains and task dependency
+ * graphs. `visited` and `depth` are recursion-internal; callers should not pass them.
+ */
+export function skillInvocation(artifacts: ArtifactStore, id: string, visited: Set<string> = new Set(), depth = 0): string {
+	const skill = requireKind(artifacts, id, "skill");
+	visited.add(id);
+	const sections = [skillInvocationBody(skill)];
+
+	const edges = artifacts.relationships({ artifactIds: [id] }).filter((edge) => edge.from === id).slice(0, SKILL_INVOCATION_MAX_LINKED_ARTIFACTS);
+	const linkedArtifactLines: string[] = [];
+	const linkedSkillSections: string[] = [];
+	for (const edge of edges) {
+		const target = artifacts.get(edge.to);
+		if (!target) continue; // dangling edge -- defensive, should not happen
+		if (target.kind !== "skill") {
+			linkedArtifactLines.push(`- ${edge.relation} ${target.kind} "${target.title}" (${target.id})`);
+			continue;
+		}
+		if (visited.has(target.id)) {
+			linkedSkillSections.push(`Also linked via ${edge.relation} to skill "${target.title}" (${target.id}) -- already invoked above in this chain, not repeated.`);
+		} else if (depth + 1 > SKILL_INVOCATION_MAX_CALL_DEPTH) {
+			linkedSkillSections.push(`Also linked via ${edge.relation} to skill "${target.title}" (${target.id}) -- call depth limit reached, invoke it separately.`);
+		} else {
+			const nested = skillInvocation(artifacts, target.id, visited, depth + 1);
+			linkedSkillSections.push(`Also invoke linked skill (${edge.relation}) "${target.title}" (${target.id}):\n${nested}`);
+		}
+	}
+	if (linkedArtifactLines.length > 0) {
+		sections.push(["Linked context (query Papyrus for full detail before proceeding):", ...linkedArtifactLines].join("\n"));
+	}
+	for (const section of linkedSkillSections) sections.push(section);
+	return sections.join("\n\n");
+}
+
 export function transitionSkill(artifacts: ArtifactStore, id: string, action: SkillTransition, context?: ArtifactEventContext): Artifact {
 	const skill = requireKind(artifacts, id, "skill");
 	const expected = action === "enable" ? "deprecated" : "active";