@constraint/cli 0.3.6 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constraint/cli",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Install, publish, and report Agent Skills with Constraint",
   "type": "module",
   "bin": {

package/skills/constraint-skills/SKILL.md

@@ -1,23 +1,25 @@
 ---
 name: constraint-skills
-description: Operate governed Agent Skills with the Constraint terminal CLI and report their invocations. Use when an agent needs to authenticate or diagnose Constraint access; configure agents; discover upload domains; inspect, install, update, or upload skills; query run history; or invoke any skill installed from or governed by Constraint.
+description: Operate governed Agent Skills with the Constraint terminal CLI. Use when an agent needs to authenticate or diagnose Constraint access; discover upload domains; inspect, install, update, or upload skills; review run history; or report a session transcript when the user asks to put skill work on the record.
 ---
 
 # Constraint Skills
 
-Use the `constraint` command for organization-authorized skills. Do not edit its config, lockfiles, instruction blocks, installation receipts, or authorization tokens directly.
+Use the `constraint` command for organization-authorized skills. Do not edit its
+config, lockfiles, installation receipts, or authorization tokens directly.
 
 ## Choose the operation
 
 - Authenticate or diagnose: `constraint login`, `constraint whoami`, `constraint doctor`.
-- Configure agents: `constraint setup`.
 - Discover or inspect skills: `constraint skills list`, `constraint skills inspect`.
 - Install or update: `constraint skills install`, `constraint skills update`.
 - Discover upload destinations: `constraint skills domains --json`.
 - Upload a local skill folder: `constraint skills upload`.
+- Report a session: `constraint report`.
 - Review runs: `constraint skills run list`, `constraint skills run get`.
 
-Read [references/commands.md](references/commands.md) before constructing flags or handling a less common operation.
+Read [references/commands.md](references/commands.md) before constructing flags
+or handling a less common operation.
 
 ## Upload skills
 
@@ -27,7 +29,9 @@ Upload the skill directory, not an individual `SKILL.md`. Before every upload, r
 constraint skills domains --json
 ```
 
-Use one returned `slug` exactly as `--domain`. Never guess a slug from a display name or reuse a domain from another organization. If multiple destinations are valid and ownership is unclear, ask the user.
+Use one returned `slug` exactly as `--domain`. Never guess a slug from a display
+name or reuse a domain from another organization. If multiple destinations are
+valid and ownership is unclear, ask the user.
 
 ```bash
 constraint skills upload <skill-directory> --domain <returned-slug>
@@ -35,33 +39,29 @@ constraint skills upload <skill-directory> --domain <returned-slug>
 
 ## Install skills
 
-Choose the target agent and scope explicitly. Prefer `--project`; use `--global` only when the user wants the skill across projects. Prefer managed links and use `--copy` only when independent files are required. Never overwrite locally edited installed skills.
+Choose the target agent and scope explicitly. Prefer `--project`; use
+`--global` only when the user wants the skill across projects. Prefer managed
+links and use `--copy` only when independent files are required. Never
+overwrite locally edited installed skills.
 
-## Start a run
+## Report a run
 
-Immediately after selecting and loading a governed skill, run:
+A run is the posting of a transcript in which a skill was invoked, and the user
+drives it: report only when the user asks to put a session on the record. Never
+report automatically or unprompted.
 
-```bash
-constraint skills run start <skill-name> --client <client> --session <session-id>
-```
-
-Use the invoked skill's frontmatter `name`. Normalize the client to `codex` or `claude-code`. Use the current client session identifier. Retain the exact run ID printed by the command. If one session invokes multiple skills, start and retain a distinct run ID for each invocation.
-
-If the command fails, report the failure briefly and continue the user's work. Do not fabricate a run ID.
-
-## Complete a run
-
-After finishing the governed skill's work and before ending the response, locate the current session's real JSON or JSONL transcript file and run:
+When asked, locate the current session's real JSON or JSONL transcript file and run:
 
 ```bash
-constraint skills run complete <run-id> <transcript-path>
+constraint report <transcript-path> --skill <skill-name>
 ```
 
-Pass the explicit local path. The CLI uploads the whole transcript file as it exists at that moment and completes only that run. Never create a replacement transcript, summarize it, pass a temporary file, or guess a path.
-
-For multiple invocations, complete each retained run separately. Overlapping full-session transcript prefixes are expected. If the transcript path cannot be determined, leave the run started and tell the user that reporting could not be completed.
-
-Do not run completion hooks, background flushes, or pending-run scans.
+Pass the explicit local path to the transcript as it exists at that moment.
+Use the invoked skill's frontmatter `name`. The server detects the client and
+session id from the transcript itself; re-reporting the same session later
+supersedes the earlier report. Never create a replacement transcript,
+summarize it, or pass a temporary file. If the transcript path cannot be
+determined, say so instead of guessing.
 
 ## Work safely
 

package/skills/constraint-skills/references/commands.md

@@ -12,7 +12,7 @@ constraint setup
 constraint doctor
 ```
 
-`login` uses WorkOS device authorization. Never request or embed an API key or client secret. `setup` detects Codex and Claude Code, then separately presents the managed global-instruction change and this skill's global installation destinations. It never replaces unrelated instructions.
+`login` uses WorkOS device authorization. Never request or embed an API key or client secret. `setup` detects Codex and Claude Code, installs this skill globally, and removes the legacy managed block that earlier releases injected into global instruction files. It never adds to or replaces user instructions.
 
 ## Discover, inspect, install, and update
 
@@ -40,11 +40,11 @@ constraint skills upload <skill-directory> --domain <returned-slug>
 
 `skills domains` returns only domains where the authenticated user can manage skills. JSON objects contain the exact `slug`, display `name`, and `description`. Discover first and pass one returned slug. Ask the user when multiple domains fit and ownership is unclear.
 
-## Start, complete, and review runs
+## Report and review runs
 
 ```bash
-constraint skills run start <skill> --client codex --session <stable-session-id>
-constraint skills run complete <run-id> <actual-transcript-path>
+constraint report <actual-transcript-path> --skill <skill-name>
+constraint report <actual-transcript-path> --skill <skill-name> --client codex --session <id>
 
 constraint skills run list
 constraint skills run list --team <domain> --user <workos-user-id> --skill <skill>
@@ -52,6 +52,11 @@ constraint skills run get <run-id>
 constraint skills run get <run-id> --raw
 ```
 
+`report` is user-driven: run it only when the user asks to put a session on the
+record. The server detects client and session id from the transcript;
+`--client`/`--session` are overrides for transcripts it cannot parse.
+Re-reporting the same session supersedes the earlier report.
+
 Repeat `--team`, `--user`, or `--skill` to request subsets. Review visibility is permission-controlled.
 
 `run get` never prints a transcript to stdout: it writes the run JSON (or the
@@ -67,4 +72,4 @@ Global flags: `--json`, `--quiet`, `--no-color`, `--help`, and `--version`. Inst
 - Setup uncertainty: run `constraint doctor`.
 - Upload denied: rerun `constraint skills domains --json` and respect the returned scope.
 - Install conflict: preserve local edits.
-- Missing transcript: locate the real client JSON or JSONL file before completion.
+- Missing transcript: locate the real client JSON or JSONL file before reporting; if it cannot be found, tell the user instead of guessing.

package/src/cli.js

@@ -36,7 +36,7 @@ import {
   uploadSkill,
 } from './skills.js';
 
-const VERSION = '0.3.6';
+const VERSION = '0.4.0';
 
 const HELP = `Constraint Skills CLI
 
@@ -54,8 +54,7 @@ Usage:
                            [--copy] [--yes]
   constraint skills update --all [--agent <agent>]... [--project|--global] [--yes]
   constraint skills upload <path> --domain <domain>
-  constraint skills run start <skill> --client <client> --session <session-id>
-  constraint skills run complete <run-id> <transcript-path>
+  constraint report <transcript-path> --skill <skill> [--client <client>] [--session <id>]
   constraint skills run list [--team <team>]... [--user <user>]... [--skill <skill>]...
   constraint skills run get <run-id>... [--raw] [--output <path>]  (always writes a file, prints summary + path)
 
@@ -269,10 +268,10 @@ async function setupCommand(args, out) {
   let installSkill = true;
   if (useUi) {
     note(
-      plans.map((plan) => `${humanize(plan.agent)}\n${plan.instructions.path}\n${plan.instructions.changed ? 'Managed block will be added or updated' : 'Already configured'}`).join('\n\n'),
-      '1. Configure agent instructions',
+      plans.map((plan) => `${humanize(plan.agent)}\n${plan.instructions.path}\n${plan.instructions.changed ? 'Legacy Constraint block will be removed' : 'Nothing to clean up'}`).join('\n\n'),
+      '1. Remove legacy instruction blocks',
     );
-    configureInstructions = !hasInstructionChanges || yes || await confirmPlan('Apply these instruction changes?');
+    configureInstructions = !hasInstructionChanges || yes || await confirmPlan('Remove the legacy Constraint block from these files?');
 
     note(
       [
@@ -294,10 +293,10 @@ async function setupCommand(args, out) {
   if (configureInstructions) {
     const spinner = taskSpinner(useUi && hasInstructionChanges);
     for (const plan of plans) {
-      spinner.message(`Configuring ${humanize(plan.agent)} instructions`);
+      spinner.message(`Cleaning ${humanize(plan.agent)} instructions`);
       result.instructions.push(await applyInstructionSetup(plan.agent));
     }
-    spinner.stop('Agent instructions configured.');
+    spinner.stop('Agent instructions cleaned.');
   }
   if (installSkill) {
     const spinner = taskSpinner(useUi && hasSkillChanges);
@@ -471,31 +470,36 @@ async function uploadCommand(args, config, out) {
   out.data({ skill_id: detail.skill_id, slug: detail.slug, domain: detail.domain, version: detail.version.version });
 }
 
-async function runStart(args, config, out) {
+// A run is the posting of a transcript in which a skill was invoked. The user
+// drives reporting: one command, after the session, with the finished
+// transcript. Client and session id are detected server-side from the
+// transcript; flags override when detection cannot.
+async function reportCommand(args, config, out) {
+  const skill = takeOption(args, '--skill');
   const client = takeOption(args, '--client');
   const session = takeOption(args, '--session');
   rejectUnknown(args);
-  if (args.length !== 1 || !client || !session) {
-    throw new Error('Usage: constraint skills run start <skill> --client <client> --session <session-id>');
+  if (args.length !== 1 || !skill) {
+    throw new Error('Usage: constraint report <transcript-path> --skill <skill> [--client <client>] [--session <session-id>]');
   }
-  const run = await apiRequest(config, '/skill-runs', {
-    method: 'POST',
-    ...jsonRequest({ skill: args[0], client, session_id: session }),
-  });
-  if (out.json) out.data(run);
-  else out.line(run.run_id);
-}
-
-async function runComplete(args, config, out) {
-  rejectUnknown(args);
-  if (args.length !== 2) throw new Error('Usage: constraint skills run complete <run-id> <transcript-path>');
-  const transcript = await readTranscript(args[1]);
-  const run = await apiRequest(config, `/skill-runs/${encodeURIComponent(args[0])}/complete`, {
+  const transcript = await readTranscript(args[0]);
+  const query = new URLSearchParams({ skill });
+  if (client) query.set('client', client);
+  if (session) query.set('session', session);
+  const run = await apiRequest(config, `/skill-reports?${query.toString()}`, {
     method: 'POST',
     headers: { 'Content-Type': mediaType(transcript.absolute), 'X-Transcript-Filename': transcript.filename },
     body: transcript.content,
   });
-  out.data(run);
+  out.data({
+    run_id: run.run_id,
+    skill: run.skill_slug,
+    version: run.skill_version,
+    state: run.state,
+    client: run.client,
+    session: run.client_session_id,
+    transcript_bytes: run.transcript_size,
+  });
 }
 
 async function runList(args, config, out) {
@@ -560,11 +564,9 @@ async function runGet(args, config, out) {
 
 async function runCommand(args, config, out) {
   const command = args.shift();
-  if (command === 'start') return runStart(args, config, out);
-  if (command === 'complete') return runComplete(args, config, out);
   if (command === 'list') return runList(args, config, out);
   if (command === 'get') return runGet(args, config, out);
-  throw new Error('Expected skills run start, complete, list, or get.');
+  throw new Error('Expected skills run list or get. Post a transcript with constraint report.');
 }
 
 async function skillsCommand(args, config, out) {
@@ -597,6 +599,7 @@ export async function main(argv) {
   if (['login', 'logout', 'whoami'].includes(command)) return authCommand(command, args, config, out);
   if (command === 'setup') return setupCommand(args, out);
   if (command === 'doctor') return doctorCommand(args, config, out);
+  if (command === 'report') return reportCommand(args, config, out);
   if (command === 'skills') return skillsCommand(args, config, out);
   throw new Error(`Unknown command: ${command}`);
 }

package/src/setup.js

@@ -9,25 +9,20 @@ import { agentPaths, normalizeAgent } from './paths.js';
 export const BLOCK_START = '<!-- constraint-skills:start -->';
 export const BLOCK_END = '<!-- constraint-skills:end -->';
 
-const BLOCK = `${BLOCK_START}
-## Constraint Skills
-
-When using the Constraint CLI or invoking any installed Agent Skill, load and
-follow the global \`constraint-skills\` companion skill. It contains the CLI
-workflow and records governed runs without modifying the invoked skill.
-${BLOCK_END}`;
-
-export function mergeInstructionBlock(existing) {
+// Earlier releases injected a managed instruction block into the user's global
+// CLAUDE.md/AGENTS.md. Writing into user-owned instruction files was never
+// trustworthy behavior; setup now only removes that legacy block if present.
+export function stripInstructionBlock(existing) {
   const start = existing.indexOf(BLOCK_START);
   const end = existing.indexOf(BLOCK_END);
+  if (start < 0 && end < 0) return existing;
   if ((start >= 0) !== (end >= 0)) {
     throw new Error('The existing Constraint Skills instruction block is incomplete; fix it before running setup.');
   }
-  if (start >= 0 && end >= start) {
-    return `${existing.slice(0, start)}${BLOCK}${existing.slice(end + BLOCK_END.length)}`;
-  }
-  const separator = existing.length === 0 ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
-  return `${existing}${separator}${BLOCK}\n`;
+  const before = existing.slice(0, start).replace(/\n+$/, '\n');
+  const after = existing.slice(end + BLOCK_END.length).replace(/^\n+/, '\n');
+  const stripped = `${before}${after}`;
+  return stripped.trim() === '' ? '' : stripped.replace(/\n{3,}/g, '\n\n');
 }
 
 async function writeInstructions(file, content, mode) {
@@ -58,7 +53,7 @@ async function instructionPlan(selected, paths) {
   } catch (error) {
     if (error && error.code !== 'ENOENT') throw error;
   }
-  const content = mergeInstructionBlock(existing);
+  const content = stripInstructionBlock(existing);
   return { path: paths.instructions, changed: content !== existing, content, mode };
 }
 
@@ -145,7 +140,7 @@ export async function setupAgent(agent, {
   let skillResult = null;
   if (instructions) {
     const approved = !plan.instructions.changed || yes || await confirmChange(
-      `Add the Constraint Skills block to ${plan.instructions.path}?`,
+      `Remove the legacy Constraint block from ${plan.instructions.path}?`,
     );
     if (approved) instructionResult = await applyInstructionSetup(selected);
   }
@@ -161,8 +156,8 @@ export async function setupStatus(agent) {
       fs.readFile(paths.instructions, 'utf8'),
       fs.stat(path.join(paths.skills, 'constraint-skills', 'SKILL.md')),
     ]);
-    return { agent: selected, instructions: instructions.includes(BLOCK_START), skill: skill.isFile() };
+    return { agent: selected, legacy_instruction_block: instructions.includes(BLOCK_START), skill: skill.isFile() };
   } catch {
-    return { agent: selected, instructions: false, skill: false };
+    return { agent: selected, legacy_instruction_block: false, skill: false };
   }
 }

package/src/skills.js

@@ -45,6 +45,35 @@ async function loadLock(scope, projectRoot) {
   return scope === 'global' ? loadInstallations() : loadProjectInstallations(projectRoot);
 }
 
+// Installed skill files are per-machine (symlinks into the canonical store);
+// only skills-lock.json belongs in version control. Keep the project's
+// .gitignore covering the generated paths, npm-style.
+const GITIGNORE_ENTRIES = ['.constraint/', '.claude/skills/', '.agents/skills/'];
+
+async function ensureProjectGitignore(projectRoot) {
+  try {
+    await fs.stat(path.join(projectRoot, '.git'));
+  } catch {
+    return; // not a git repository; nothing to manage
+  }
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  let existing = '';
+  try {
+    existing = await fs.readFile(gitignorePath, 'utf8');
+  } catch {
+    existing = '';
+  }
+  const lines = new Set(existing.split('\n').map((line) => line.trim()));
+  const missing = GITIGNORE_ENTRIES.filter(
+    (entry) => !lines.has(entry) && !lines.has(entry.slice(0, -1)),
+  );
+  if (!missing.length) return;
+  const block = `${missing.join('\n')}\n`;
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+  const header = existing ? '\n# Constraint skill installs (commit skills-lock.json instead)\n' : '# Constraint skill installs (commit skills-lock.json instead)\n';
+  await fs.writeFile(gitignorePath, `${existing}${prefix}${header}${block}`);
+}
+
 async function saveLock(scope, projectRoot, value) {
   if (scope === 'global') return saveInstallations(value);
   return saveProjectInstallations(projectRoot, value);
@@ -96,6 +125,7 @@ export async function installSkill(config, identifier, {
   const lock = await loadLock(scope, root);
   lock.lockfile_version = 1;
   lock.installations ||= {};
+  if (scope === 'project') await ensureProjectGitignore(root);
   const packageFiles = filesFromDetail(detail);
   const contentHash = packageDigest(packageFiles);
   const canonical = copy === true ? null : canonicalSkillPath({