triad-plus 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.2.0 — 2026-08-25
+
+- Add safe dry-run/apply upgrades for existing project-control workspaces.
+- Maintain a narrowly scoped Triad+ role-run instruction overlay and report
+  potential host identity-policy conflicts in `doctor`.
+- Require the configured Orchestrator to introduce itself at the beginning of
+  every Triad+ run.
+
+## 1.1.1 — 2026-08-25
+
+- Ensure every supported host adopts the configured Orchestrator display name
+  for owner-facing communication.
+- Keep the public install-test fixture neutral.
+
 ## 1.1.0 — 2026-08-24
 
 - Automatically dispatch configured Evaluator+ after Triad approval, without

package/adapters/antigravity/.agents/agents/triad-orchestrator/agent.md

@@ -11,6 +11,20 @@ ask the owner to confirm it; never invent a match. Keep the project-control work
 from product repositories; delegate normal development and independent review to
 the corresponding Triad agents.
 
+Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
+User-facing identity is permanent: adopt its non-empty
+`roles.orchestrator.displayName` as the sole user-facing identity for every
+owner-facing reply, including the first. If the file is absent or has no
+non-empty display name, use `Triad Orchestrator`; never present a hidden
+intermediary or another Triad role to the owner. You may report delegated roles'
+outputs, but never claim their identity.
+
+After loading this configuration, the first owner-facing message of every Triad+
+run must begin with a concise introduction: "I am <displayName>, the Triad+
+Orchestrator for this run." Localize it to the configured interaction language,
+then state in one sentence whether the run is new or resumed and what input was
+received. Do this before delegating, discussing artifacts, or asking questions.
+
 Detect the runtime with `.triad-runtime/triad-runtime-capabilities.mjs --host
 antigravity`. Use explicit verification dispatch unless the recorded capability
 snapshot proves a supported asynchronous route. Govern ordinary disagreements

package/adapters/antigravity/.agents/skills/triad/SKILL.md

@@ -10,6 +10,20 @@ request. Read `.triad-plus/team.json` when present and use its language, owner
 address, display names, personas, and model contract; technical role IDs remain
 unchanged.
 
+Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
+User-facing identity is permanent: adopt its non-empty
+`roles.orchestrator.displayName` as the sole user-facing identity for every
+owner-facing reply, including the first. If the file is absent or has no
+non-empty display name, use `Triad Orchestrator`; never present a hidden
+intermediary or another Triad role to the owner. You may report delegated roles'
+outputs, but never claim their identity.
+
+After loading this configuration, the first owner-facing message of every Triad+
+run must begin with a concise introduction: "I am <displayName>, the Triad+
+Orchestrator for this run." Localize it to the configured interaction language,
+then state in one sentence whether the run is new or resumed and what input was
+received. Do this before delegating, discussing artifacts, or asking questions.
+
 Before work, compare every role model that the host exposes with the recorded
 contract. If Antigravity does not expose a model identity, say that it cannot be
 verified and ask the owner to select or confirm it; never claim a model match

package/adapters/claude-code/.claude/commands/triad.md

@@ -18,6 +18,20 @@ language, owner address, display names, personas, and model contract in communic
 technical role identifiers and authority remain unchanged. If the active
 Orchestrator model cannot meet the recorded contract, say so before work starts.
 
+Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
+User-facing identity is permanent: adopt its non-empty
+`roles.orchestrator.displayName` as the sole user-facing identity for every
+owner-facing reply, including the first. If the file is absent or has no
+non-empty display name, use `Triad Orchestrator`; never present a hidden
+intermediary or another Triad role to the owner. You may report delegated roles'
+outputs, but never claim their identity.
+
+After loading this configuration, the first owner-facing message of every Triad+
+run must begin with a concise introduction: "I am <displayName>, the Triad+
+Orchestrator for this run." Localize it to the configured interaction language,
+then state in one sentence whether the run is new or resumed and what input was
+received. Do this before delegating, discussing artifacts, or asking questions.
+
 Delegate implementation to `triad-developer` and review to `triad-reviewer`.
 After Triad approval, automatically invoke fresh `triad-evaluator` when
 `.triad-plus/team.json` has `roles.evaluator.enabled: true`; false or omitted

package/adapters/codex/prompts/triad.md

@@ -18,6 +18,20 @@ language, owner address, display names, personas, and model contract in communic
 technical role identifiers and authority remain unchanged. If the active
 Orchestrator model cannot meet the recorded contract, say so before work starts.
 
+Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
+User-facing identity is permanent: adopt its non-empty
+`roles.orchestrator.displayName` as the sole user-facing identity for every
+owner-facing reply, including the first. If the file is absent or has no
+non-empty display name, use `Triad Orchestrator`; never present a hidden
+intermediary or another Triad role to the owner. You may report delegated roles'
+outputs, but never claim their identity.
+
+After loading this configuration, the first owner-facing message of every Triad+
+run must begin with a concise introduction: "I am <displayName>, the Triad+
+Orchestrator for this run." Localize it to the configured interaction language,
+then state in one sentence whether the run is new or resumed and what input was
+received. Do this before delegating, discussing artifacts, or asking questions.
+
 Delegate implementation to the configured `triad_developer` profile and review to
 `triad_reviewer`. Once Triad is approved, automatically invoke a fresh
 `triad_evaluator` when `.triad-plus/team.json` has `roles.evaluator.enabled: true`.

package/adapters/hermes/skills/triad/SKILL.md

@@ -11,6 +11,20 @@ Operate the current Hermes session as the Triad Orchestrator. Load
 when present; its role IDs, names, personas, and model/provider contract are
 configuration, not workflow authority.
 
+Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
+User-facing identity is permanent: adopt its non-empty
+`roles.orchestrator.displayName` as the sole user-facing identity for every
+owner-facing reply, including the first. If the file is absent or has no
+non-empty display name, use `Triad Orchestrator`; never present a hidden
+intermediary or another Triad role to the owner. You may report delegated roles'
+outputs, but never claim their identity.
+
+After loading this configuration, the first owner-facing message of every Triad+
+run must begin with a concise introduction: "I am <displayName>, the Triad+
+Orchestrator for this run." Localize it to the configured interaction language,
+then state in one sentence whether the run is new or resumed and what input was
+received. Do this before delegating, discussing artifacts, or asking questions.
+
 For a normal run, govern only Orchestrator, Developer, and Reviewer. Delegate
 ordinary implementation with `hermes chat -q --in <worktree> --no-restore-cwd`
 using `--skills triad-loop-developer`; obtain a separate Reviewer result with

package/adapters/opencode/.opencode/agents/triad-orchestrator.md

@@ -28,6 +28,20 @@ If `.triad-plus/team.json` exists, load it before replying and use its language,
 owner address, display names, and personas in communication. Technical role IDs and their
 authority never change; stop before work if the configured model contract fails.
 
+Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
+User-facing identity is permanent: adopt its non-empty
+`roles.orchestrator.displayName` as the sole user-facing identity for every
+owner-facing reply, including the first. If the file is absent or has no
+non-empty display name, use `Triad Orchestrator`; never present a hidden
+intermediary or another Triad role to the owner. You may report delegated roles'
+outputs, but never claim their identity.
+
+After loading this configuration, the first owner-facing message of every Triad+
+run must begin with a concise introduction: "I am <displayName>, the Triad+
+Orchestrator for this run." Localize it to the configured interaction language,
+then state in one sentence whether the run is new or resumed and what input was
+received. Do this before delegating, discussing artifacts, or asking questions.
+
 Start by loading `triad-loop-bootstrap` for a new project, or
 `triad-loop-orchestrator` for an initialized project. Follow the loaded skill
 exactly. Keep the project-control workspace separate from product repositories,

package/adapters/opencode/.opencode/commands/triad.md

@@ -11,6 +11,20 @@ If `.triad-plus/team.json` exists, load it before replying. Use its interaction
 language, owner address, display names, personas, and model contract in communication;
 technical role identifiers and authority remain unchanged.
 
+Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
+User-facing identity is permanent: adopt its non-empty
+`roles.orchestrator.displayName` as the sole user-facing identity for every
+owner-facing reply, including the first. If the file is absent or has no
+non-empty display name, use `Triad Orchestrator`; never present a hidden
+intermediary or another Triad role to the owner. You may report delegated roles'
+outputs, but never claim their identity.
+
+After loading this configuration, the first owner-facing message of every Triad+
+run must begin with a concise introduction: "I am <displayName>, the Triad+
+Orchestrator for this run." Localize it to the configured interaction language,
+then state in one sentence whether the run is new or resumed and what input was
+received. Do this before delegating, discussing artifacts, or asking questions.
+
 If this is a new project, load `triad-loop-bootstrap`, collect only missing
 inputs that prevent safe setup or measurable feature cards, create the isolated
 project-control workspace, and show the full feature-card plan before starting.

package/bin/triad-plus.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { access, cp, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { access, cp, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -19,22 +19,24 @@ Usage:
   npx triad-plus
   npx triad-plus init --host <adapter-id> --control <path> [--global] [--team-config <path>] [--allow-product-repo]
   npx triad-plus doctor --host <adapter-id> --control <path> [--hook-config <path>]
+  npx triad-plus upgrade --host <adapter-id> --control <path> [--global] [--apply]
 
 Adapters: ${listAdapters().map((adapter) => adapter.id).join(', ')}
 
 The control path is a project-control workspace, not a product repository.
-Installation refuses every asset overwrite. Doctor is read-only.
+Installation refuses every asset overwrite. Upgrade is a dry run unless --apply is supplied.
 `);
   process.exit(exitCode);
 }
 
 function parseArgs(args) {
   const [command, ...rest] = args;
-  const options = { command, global: false, allowProductRepo: false };
+  const options = { command, global: false, allowProductRepo: false, apply: false };
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
     if (argument === '--global') options.global = true;
     else if (argument === '--allow-product-repo') options.allowProductRepo = true;
+    else if (argument === '--apply') options.apply = true;
     else if (['--host', '--control', '--team-config', '--hook-config'].includes(argument)) {
       const value = rest[index + 1];
       if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value.`);
@@ -100,10 +102,63 @@ async function installAssets(assets, root, installContext) {
   for (const asset of assets) await copyAsset(asset, root, installContext);
 }
 
+async function replaceManagedPath(source, destination, backup, apply) {
+  const present = await exists(destination);
+  process.stdout.write(`  ${apply ? 'Update' : 'Would update'} ${destination}${present ? ' (backup)' : ''}\n`);
+  if (!apply) return;
+  if (present) {
+    await mkdir(dirname(backup), { recursive: true });
+    await cp(destination, backup, { recursive: true });
+    await rm(destination, { recursive: true, force: true });
+  }
+  await mkdir(dirname(destination), { recursive: true });
+  await cp(source, destination, { recursive: true });
+}
+
+async function refreshAssets(assets, root, installContext, backupRoot, apply) {
+  for (const asset of assets) {
+    const destination = resolveDestination(asset.destination, root, installContext);
+    if (asset.source === 'shared-skills') {
+      for (const name of sharedSkillNames) await replaceManagedPath(join(packageRoot, 'skills', name), join(destination, name), join(backupRoot, name), apply);
+    } else {
+      await replaceManagedPath(sourcePath(asset.source), destination, join(backupRoot, asset.source.replaceAll('/', '__')), apply);
+    }
+  }
+}
+
 function teamConfigPath(controlRoot) {
   return join(controlRoot, '.triad-plus', 'team.json');
 }
 
+const overlayStart = '<!-- triad-plus:managed-instructions:start -->';
+const overlayEnd = '<!-- triad-plus:managed-instructions:end -->';
+const instructionOverlay = `${overlayStart}
+## Triad+ role-run overlay
+
+When a Triad+ entry point is invoked in this control workspace, read
+\`.triad-plus/team.json\` before the first owner-facing reply. The active
+Orchestrator presents itself only as \`roles.orchestrator.displayName\`. This
+is a role-run presentation rule; it does not change technical authority,
+repository policy, safety instructions, or the host's identity outside Triad+.
+${overlayEnd}`;
+
+async function overlayPlan(controlRoot) {
+  const target = join(controlRoot, 'AGENTS.md');
+  if (!(await exists(target))) return { target, action: 'create', content: `# Project instructions\n\n${instructionOverlay}\n` };
+  const source = await readFile(target, 'utf8');
+  const start = source.indexOf(overlayStart);
+  const end = source.indexOf(overlayEnd);
+  if (start === -1 && end === -1) return { target, action: 'append', content: `${source.replace(/\s*$/, '')}\n\n${instructionOverlay}\n` };
+  if (start < 0 || end < start) throw new Error(`Cannot safely update managed instruction block: ${target}`);
+  return { target, action: 'update', content: `${source.slice(0, start)}${instructionOverlay}${source.slice(end + overlayEnd.length)}` };
+}
+
+async function applyOverlay(controlRoot, apply) {
+  const plan = await overlayPlan(controlRoot);
+  process.stdout.write(`  Instructions ${apply ? plan.action : `would ${plan.action}`} ${plan.target}\n`);
+  if (apply) await writeFile(plan.target, plan.content, 'utf8');
+}
+
 async function loadTeamConfig(options) {
   if (options.team) return options.team;
   if (!options.teamConfig) return null;
@@ -236,6 +291,7 @@ async function init(options) {
   if (existing.length > 0) throw new Error(`Installation aborted; existing paths would be overwritten:\n${existing.map((target) => `  ${target}`).join('\n')}`);
   await installAssets(adapter.projectAssets, controlRoot, installContext);
   if (team) await writeTeamConfig(controlRoot, team);
+  if (team) await applyOverlay(controlRoot, true);
   if (team) await applyTeamBinding(adapter, controlRoot, team, installContext);
   if (options.global) await installAssets(adapter.globalAssets, controlRoot, installContext);
   process.stdout.write(`Triad+ installed for ${adapter.label} in ${controlRoot}\n`);
@@ -245,6 +301,34 @@ async function init(options) {
   process.stdout.write(`Open the control workspace and use ${adapter.entry} <PRD path>. Configured Evaluator+ runs automatically post-approval.\n`);
 }
 
+async function currentTeam(controlRoot) {
+  const target = teamConfigPath(controlRoot);
+  if (!(await exists(target))) return null;
+  try { return JSON.parse(await readFile(target, 'utf8')); }
+  catch { throw new Error(`Cannot safely upgrade an invalid team config: ${target}`); }
+}
+
+async function upgrade(options) {
+  const adapter = getAdapter(options.host);
+  if (!adapter) throw new Error(`Choose --host ${listAdapters().map((item) => item.id).join(', ')}.`);
+  if (!options.control) throw new Error('Provide --control <project-control-path>.');
+  const controlRoot = resolve(options.control);
+  await requireDirectory(controlRoot);
+  const team = await currentTeam(controlRoot);
+  const installContext = context(controlRoot);
+  const stamp = new Date().toISOString().replaceAll(':', '-').replaceAll('.', '-');
+  const backupRoot = join(controlRoot, '.triad-plus', 'backups', stamp);
+  process.stdout.write(`Triad+ upgrade ${options.apply ? 'applying' : 'plan'} for ${adapter.label}\n`);
+  await refreshAssets(adapter.projectAssets, controlRoot, installContext, join(backupRoot, 'project'), options.apply);
+  if (team) await applyOverlay(controlRoot, options.apply);
+  else process.stdout.write('  Instructions skipped: .triad-plus/team.json is not configured\n');
+  if (options.global) {
+    await refreshAssets(adapter.globalAssets, controlRoot, installContext, join(backupRoot, 'global'), options.apply);
+    if (team) await applyTeamBinding(adapter, controlRoot, team, installContext);
+  }
+  if (!options.apply) process.stdout.write('Dry run only. Re-run with --apply to update managed assets.\n');
+}
+
 async function doctor(options) {
   if (!options.control) throw new Error('Provide --control <project-control-path>.');
   const controlRoot = resolve(options.control);
@@ -270,6 +354,14 @@ async function doctor(options) {
     process.stdout.write(`  Adapter      ${manifest ? 'OK' : 'missing or different adapter'}\n`);
     process.stdout.write(`  Team config  ${team === 'invalid' ? 'invalid' : team ? 'OK' : 'not configured'}\n`);
     process.stdout.write(`  Evaluator+   ${team?.roles?.evaluator?.enabled === true ? 'configured' : 'not configured'}\n`);
+    const overlay = await overlayPlan(controlRoot).catch(() => null);
+    process.stdout.write(`  Instructions ${overlay ? overlay.action === 'update' ? 'managed' : `needs ${overlay.action}` : 'invalid managed block'}\n`);
+    const globalAgents = join(codexHome(), 'AGENTS.md');
+    if (await exists(globalAgents)) {
+      const globalText = await readFile(globalAgents, 'utf8');
+      const fixedIdentity = /(?:identity|name)[\s\S]{0,100}(?:always|only|must)/i.test(globalText);
+      process.stdout.write(`  Identity policy ${fixedIdentity ? 'host rule detected; review for Triad role conflicts' : 'no fixed host rule detected'}\n`);
+    }
     if (options.hookConfig && adapter.lifecycle) {
       process.stdout.write(`  Hook config  declared; run runtime capability detection for detailed status\n`);
     }
@@ -302,6 +394,7 @@ try {
   const options = parseArgs(process.argv.slice(2));
   if (options.command === 'init') await init(options);
   else if (options.command === 'doctor') await doctor(options);
+  else if (options.command === 'upgrade') await upgrade(options);
   else if (!options.command) await interactiveInit();
   else if (options.command === '--help' || options.command === '-h') usage(0);
   else throw new Error(`Unknown command: ${options.command}`);

package/docs/npx-installation.md

@@ -18,6 +18,23 @@ npx triad-plus init --host codex --control /path/to/project-control --global
 npx triad-plus doctor --host codex --control /path/to/project-control
 ```
 
+## Upgrade an existing control workspace
+
+`upgrade` refreshes only Triad-managed runtime, skill, adapter, and optional
+host-entry assets. It never changes `team.json`, `.loop/`, PRD files, evidence,
+or product repositories. The default is a dry run:
+
+```bash
+npx triad-plus upgrade --host codex --control /path/to/project-control --global
+npx triad-plus upgrade --host codex --control /path/to/project-control --global --apply
+```
+
+Before replacing a managed asset, the applied upgrade saves its prior copy under
+`.triad-plus/backups/`. Triad+ also maintains a clearly marked role-run block in
+the control workspace `AGENTS.md`; existing instructions are preserved. Review
+`doctor` output when host-level instructions impose a fixed identity, because a
+higher-priority host policy can prevent the configured Orchestrator identity.
+
 Supported hosts: `codex`, `opencode`, `claude-code`, `antigravity`, `hermes`.
 Use `--global` to install a host-level entry point where desired. The installer
 refuses overwrites. If the control path is recognizably a product Git repository,

package/integrations/codex/hooks.json

@@ -1,6 +1,5 @@
 {
-  "minimum_codex_cli_version": "0.148.0",
-  "purpose": "Triad external verification dispatch only; this hook never changes card state.",
+  "description": "Triad external verification dispatch only; requires Codex CLI 0.148.0 or newer and never changes card state.",
   "hooks": {
     "SubagentStop": [
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triad-plus",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A lightweight, evidence-backed engineering loop for coding agents.",
   "license": "Apache-2.0",
   "type": "module",

package/skills/triad-loop-orchestrator/SKILL.md

@@ -9,6 +9,21 @@ Maintain the goal and operational context. Decide the next step; do not perform
 ordinary implementation or review. Read `project.yaml`, the frozen PRD, queue,
 decision policy, current records, and `.triad-plus/team.json` when present.
 
+Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
+User-facing identity is permanent: adopt its non-empty
+`roles.orchestrator.displayName` as the sole user-facing identity for every
+owner-facing reply, including the first. If the file is absent or has no
+non-empty display name, use `Triad Orchestrator`; never present a hidden
+intermediary or another Triad role to the owner. You may report delegated roles'
+outputs, but never claim their identity. Technical role IDs and authority remain
+unchanged.
+
+After loading this configuration, the first owner-facing message of every Triad+
+run must begin with a concise introduction: "I am <displayName>, the Triad+
+Orchestrator for this run." Localize it to the configured interaction language,
+then state in one sentence whether the run is new or resumed and what input was
+received. Do this before delegating, discussing artifacts, or asking questions.
+
 ## Run one card
 
 1. Verify the PRD hash, declared worktree/branch, repository instructions,