@aperant/framework 0.6.2

package/src/cli/task/outputs-guard.mjs

@@ -0,0 +1,166 @@
+/**
+ * @internal
+ * outputs-guard.mjs — task outputs allowlist enforcement (R11).
+ *
+ * Roundtable recommendation (Innovation Scout): every task record declares
+ * the path set its lifecycle commits are allowed to touch. Before any
+ * partial-commit staging (roadmap sync, team sync), we intersect the dirty
+ * file list with the task's `outputs` globs. Anything outside the declared
+ * path set fails loud with the offending path.
+ *
+ * This is a belt to R7's suspenders: even if a future refactor forgets to
+ * route a git cwd to the worktree, the outputs guard catches the leak at the
+ * contract level by rejecting paths that don't belong to this task.
+ *
+ * Precedent: Buck2 hermetic outputs, Kubernetes managedFields, Nix
+ * allowedReferences. The glob matcher is deliberately tiny — hand-rolled to
+ * avoid pulling in minimatch/picomatch for one use site.
+ */
+
+/**
+ * Default outputs applied to brand-new tasks.
+ *
+ *   - `unlinked`: permissive `**` for tasks without milestone/phase linkage
+ *     (quick tasks, investigations). The user opted out of lifecycle commits
+ *     by not linking, so the allowlist is effectively unbounded.
+ *   - `phase-linked`: the exact path set that lifecycle commits and
+ *     bookkeeping writes need. Excludes the app source (apps/, packages/,
+ *     etc.) so the lifecycle machinery cannot stage project code — those
+ *     writes belong to the executor, not the framework.
+ *
+ * @internal
+ */
+export const DEFAULT_TASK_OUTPUTS = Object.freeze({
+	unlinked: Object.freeze(['**']),
+	'phase-linked': Object.freeze([
+		'.aperant/tasks/<id>/**',
+		// C11 — explicit entry for the per-task token telemetry file. Already
+		// covered by the wildcard above, but listed by name so the artifact's
+		// existence is discoverable when grepping the allowlist.
+		'.aperant/tasks/<id>/tokens.json',
+		'.aperant/tasks/INDEX.md',
+		'.aperant/roadmap/<scope>/phases/<phase-id>.json',
+		'.aperant/roadmap/<scope>/phases/**',
+		'.aperant/roadmap/<scope>/milestones.json',
+		'.aperant/roadmap/<scope>/ROADMAP.md',
+		'.aperant/roadmap/**',
+		'.aperant/events/**',
+		'.aperant/team-status/**',
+		'.aperant/state.json',
+		// C17 — declarative YAML workflow runs emit artifacts under
+		// .aperant/wfrun/{run-id}/ (manifest.json, plan.json, result.json).
+		// The `<id>` placeholder used for tasks doesn't apply here — run-ids
+		// are orthogonal, so the allowlist uses a literal wildcard.
+		'.aperant/wfrun/**',
+		// C27 — apt-tools design-scan writes tokens.json plus future design
+		// artifacts under .aperant/design/. Shared across tasks (a single
+		// design-scan run feeds every downstream apt:design task), so the
+		// allowlist is a literal wildcard rather than task-scoped.
+		'.aperant/design/**',
+	]),
+})
+
+/**
+ * Resolve the canonical outputs for a new task based on its linkage.
+ *
+ * @internal
+ */
+export function resolveDefaultOutputs(task) {
+	const linked = Boolean(task?.milestone_id && task?.phase_id)
+	const template = linked ? DEFAULT_TASK_OUTPUTS['phase-linked'] : DEFAULT_TASK_OUTPUTS.unlinked
+	// Expand `<id>`, `<scope>`, `<phase-id>` tokens so the stored allowlist is
+	// self-contained (no re-expansion at check time).
+	const id = task?.id || task?.task_id || ''
+	const scope = task?.scope || 'project'
+	const phaseId = task?.phase_id || ''
+	return template.map((pat) =>
+		pat
+			.replace(/<id>/g, id)
+			.replace(/<scope>/g, scope)
+			.replace(/<phase-id>/g, phaseId),
+	)
+}
+
+/**
+ * Minimal glob matcher. Supports:
+ *   - `**` matches any sequence of characters including `/`
+ *   - `*`  matches any sequence of non-`/` characters
+ *   - literal `.` and other path characters escaped safely
+ *
+ * Intentionally does NOT support negation, character classes, or braces —
+ * the outputs templates above are the only consumers, and they never need
+ * those features.
+ *
+ * @internal
+ */
+export function globToRegex(pat) {
+	let re = ''
+	for (let i = 0; i < pat.length; i++) {
+		const c = pat[i]
+		if (c === '*' && pat[i + 1] === '*') {
+			re += '.*'
+			i++
+		} else if (c === '*') {
+			re += '[^/]*'
+		} else if ('+.()|^$?{}[]\\'.includes(c)) {
+			re += `\\${c}`
+		} else if (c === '/') {
+			re += '/'
+		} else {
+			re += c
+		}
+	}
+	return new RegExp(`^${re}$`)
+}
+
+/**
+ * Check whether `path` is allowed by any glob in `patterns`.
+ *
+ * @internal
+ */
+export function matchesAny(path, patterns) {
+	for (const pat of patterns) {
+		if (!pat) continue
+		if (globToRegex(pat).test(path)) return true
+	}
+	return false
+}
+
+/**
+ * Validate a list of paths against the task's declared outputs. Returns an
+ * array of offending paths (empty if everything is allowed).
+ *
+ * @internal
+ */
+export function findOutputsViolations(outputs, paths) {
+	// Treat a missing or empty outputs list as "reject everything" — the
+	// sentinel originally exercised by C29's smoke-drain harness (retired in
+	// C30 in favor of src/__tests__/command-coverage.test.ts). Callers that
+	// want unrestricted writes pass `['**']` explicitly.
+	if (!Array.isArray(outputs)) return paths.slice()
+	if (outputs.length === 0) return paths.slice()
+	const bad = []
+	for (const p of paths) {
+		if (!matchesAny(p, outputs)) bad.push(p)
+	}
+	return bad
+}
+
+/**
+ * Throw-on-violation variant. Error shape is structured so callers can emit
+ * a machine-readable JSON diagnostic.
+ *
+ * @internal
+ */
+export function assertWithinOutputs(outputs, paths) {
+	const violations = findOutputsViolations(outputs, paths)
+	if (violations.length > 0) {
+		const err = new Error(
+			`outputs-violation: ${violations.length} path(s) outside task outputs: ${violations.slice(0, 5).join(', ')}`,
+		)
+		err.code = 'outputs-violation'
+		err.violations = violations
+		err.outputs = outputs
+		throw err
+	}
+}

package/src/cli/task/worktree-cleanup.mjs

@@ -0,0 +1,129 @@
+/**
+ * task/worktree-cleanup.mjs — honor task_isolation.cleanup_on_close on task close (C29).
+ *
+ * Extracted from cmdTask close-case to keep bin/apt-tools.mjs → commands/task.mjs
+ * under the 800 LOC gate. Pure behavior move, no semantic change.
+ *
+ * Modes:
+ *   'never' → no-op, return action:'noop'
+ *   'ask'   → return cleanup_command for the skill to prompt
+ *   'auto'  → merge back into base_branch, then remove the worktree + branch
+ */
+
+import { execFileSync } from 'node:child_process'
+
+/**
+ * @param {object} task - closed task record with worktree_path/branch/base_branch.
+ * @param {string} mode - 'never' | 'ask' | 'auto'
+ * @param {string} targetDir - main-repo project directory (cwd for git ops).
+ * @returns {object|null} cleanup report block, or null if no worktree on task.
+ */
+export function computeWorktreeCleanup(task, mode, targetDir) {
+	if (!task?.worktree_path) return null
+
+	const wtPath = task.worktree_path
+	const taskBranch = task.branch
+	const baseBranch = task.base_branch || 'main'
+
+	if (mode === 'never') {
+		return {
+			mode,
+			worktree_path: wtPath,
+			branch: taskBranch,
+			base_branch: baseBranch,
+			action: 'noop',
+		}
+	}
+
+	if (mode === 'ask') {
+		return {
+			mode,
+			worktree_path: wtPath,
+			branch: taskBranch,
+			base_branch: baseBranch,
+			action: 'pending',
+			cleanup_command: `git checkout ${baseBranch} && git merge --no-edit ${taskBranch} && git worktree remove ${wtPath} && git branch -d ${taskBranch}`,
+		}
+	}
+
+	// mode === 'auto' — attempt merge-back in the main repo (never in the worktree).
+	let mergeOk = false
+	let mergeError = null
+	try {
+		execFileSync('git', ['checkout', baseBranch], {
+			cwd: targetDir,
+			encoding: 'utf-8',
+			stdio: 'pipe',
+		})
+		execFileSync('git', ['merge', '--no-edit', taskBranch], {
+			cwd: targetDir,
+			encoding: 'utf-8',
+			stdio: 'pipe',
+		})
+		mergeOk = true
+	} catch (err) {
+		mergeError = (err.stderr || err.message || '')
+			.toString()
+			.trim()
+			.split('\n')
+			.slice(0, 3)
+			.join(' ')
+		// Abort the failed merge so the main repo is left clean.
+		try {
+			execFileSync('git', ['merge', '--abort'], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: 'pipe',
+			})
+		} catch {
+			/* */
+		}
+	}
+
+	if (mergeOk) {
+		try {
+			execFileSync('git', ['worktree', 'remove', wtPath], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: 'pipe',
+			})
+		} catch {
+			try {
+				execFileSync('git', ['worktree', 'remove', '--force', wtPath], {
+					cwd: targetDir,
+					encoding: 'utf-8',
+					stdio: 'pipe',
+				})
+			} catch {
+				/* */
+			}
+		}
+		try {
+			execFileSync('git', ['branch', '-d', taskBranch], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: 'pipe',
+			})
+		} catch {
+			/* already deleted or unmerged */
+		}
+		return {
+			mode,
+			worktree_path: wtPath,
+			branch: taskBranch,
+			base_branch: baseBranch,
+			action: 'merged_and_removed',
+		}
+	}
+
+	// Preserve the branch + worktree — surface merge-pending.
+	return {
+		mode,
+		worktree_path: wtPath,
+		branch: taskBranch,
+		base_branch: baseBranch,
+		action: 'merge_pending',
+		merge_error: mergeError,
+		message: `Task branch ${taskBranch} has merge conflicts against ${baseBranch}. Worktree preserved at ${wtPath}. Resolve manually: git checkout ${baseBranch} && git merge ${taskBranch}`,
+	}
+}

package/src/cli/team/team.mjs

@@ -0,0 +1,361 @@
+/**
+ * team.mjs — team-mode enablement + team.json + sync helpers (C29).
+ */
+
+import { execFileSync, execSync, spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getGitIdentity } from '../git/identity.mjs'
+import { findOutputsViolations } from '../task/outputs-guard.mjs'
+import { withFileLock } from '../util/fs-lock.mjs'
+import { atomicWriteJson } from '../util/io.mjs'
+
+/**
+ * Check if team mode is enabled for this project.
+ */
+export function isTeamEnabled(targetDir) {
+	const teamPath = join(targetDir, '.aperant', 'team.json')
+	if (!existsSync(teamPath)) return false
+	try {
+		const team = JSON.parse(readFileSync(teamPath, 'utf-8'))
+		return team.enabled === true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Auto-register the current user as a team member (called on every task op).
+ * Safe no-op if team mode is not enabled.
+ *
+ * Lock-protected: concurrent wave-mode agents may call this simultaneously;
+ * without the lock the read-modify-write clobbers sibling members. Same
+ * pattern as state.json writers (withFileLock + atomicWriteJson).
+ */
+export function updateTeamMember(targetDir) {
+	if (!isTeamEnabled(targetDir)) return
+	const identity = getGitIdentity(targetDir)
+	if (!identity) return
+
+	const teamPath = join(targetDir, '.aperant', 'team.json')
+
+	try {
+		withFileLock(teamPath, () => {
+			let team
+			try {
+				team = JSON.parse(readFileSync(teamPath, 'utf-8'))
+			} catch {
+				return
+			}
+			if (!team.members) team.members = {}
+
+			const existing = team.members[identity.email]
+			if (existing) {
+				if (existing.name === identity.name) return
+				existing.name = identity.name
+			} else {
+				team.members[identity.email] = {
+					name: identity.name,
+					email: identity.email,
+					joined_at: new Date().toISOString(),
+				}
+			}
+
+			atomicWriteJson(teamPath, team)
+		})
+	} catch {
+		// Lock acquisition failed — silent skip.
+	}
+}
+
+/**
+ * Allowlist of `.aperant/` paths that `team sync` is permitted to stage.
+ * Any path outside this set — including source code — is NEVER staged by sync,
+ * even if dirty. The `.aperant/roadmap/` glob is expanded at runtime from the
+ * actual tracked file list (picks up per-scope milestones.json + ROADMAP.md).
+ */
+const TEAM_SYNC_ALLOWLIST = ['.aperant/tasks/INDEX.md', '.aperant/team.json']
+
+/**
+ * Compute the set of files that `team sync` should stage. Returns a sorted
+ * array of repo-relative paths (forward-slash). Scans `git status --porcelain`
+ * for any modified/untracked files under `.aperant/` and intersects with the
+ * allowlist (plus any tracked roadmap markdown/json).
+ *
+ * Pure function over git output so it's easy to reason about in tests.
+ */
+export function computeTeamSyncFiles(targetDir, opts = {}) {
+	const gitCwd = opts.cwd ?? targetDir
+	let porcelain = ''
+	try {
+		porcelain = execSync('git status --porcelain -- .aperant 2>/dev/null', {
+			cwd: gitCwd,
+			encoding: 'utf-8',
+		})
+	} catch {
+		return []
+	}
+
+	// Parse porcelain lines. Format: "XY path" where XY is 2-char status.
+	// Rename lines look like "R  old -> new"; we only care about the new path.
+	const dirty = new Set()
+	for (const rawLine of porcelain.split('\n')) {
+		if (!rawLine) continue
+		const line = rawLine.slice(3) // strip "XY "
+		const arrowIdx = line.indexOf(' -> ')
+		const path = arrowIdx >= 0 ? line.slice(arrowIdx + 4) : line
+		const clean = path.replace(/^"(.*)"$/, '$1').trim()
+		if (clean.startsWith('.aperant/')) dirty.add(clean)
+	}
+
+	// Expand allowlist: static list plus any tracked roadmap .md / .json files.
+	const allowed = new Set(TEAM_SYNC_ALLOWLIST)
+	try {
+		const tracked = execSync('git ls-files -- .aperant/roadmap 2>/dev/null', {
+			cwd: gitCwd,
+			encoding: 'utf-8',
+		})
+		for (const line of tracked.split('\n')) {
+			const f = line.trim()
+			if (!f) continue
+			if (f.endsWith('.md') || f.endsWith('.json')) allowed.add(f)
+		}
+	} catch {
+		/* not in git, or no roadmap */
+	}
+
+	const staged = []
+	for (const f of dirty) {
+		if (allowed.has(f)) staged.push(f)
+	}
+	staged.sort()
+	return staged
+}
+
+/**
+ * Filter the staging list through `git check-ignore --stdin` so files matched
+ * by the project's `.gitignore` (e.g. a repo that ignores `.aperant/roadmap/`)
+ * are silently skipped instead of crashing the downstream `git add`. Returns
+ * `{ kept, skipped }` — both arrays of repo-relative paths, preserving order.
+ *
+ * Conservative fallback: if `git check-ignore` exits with a status other than
+ * 0 (ignored matches) or 1 (no ignored matches) — e.g. git not in PATH, repo
+ * corruption, or the binary unavailable — we return every file as kept so the
+ * existing `git add` path can run and surface its own error if needed.
+ */
+export function filterGitignored(files, gitCwd) {
+	if (!Array.isArray(files) || files.length === 0) {
+		return { kept: [], skipped: [] }
+	}
+	let proc
+	try {
+		// `--no-index` is the key: without it, check-ignore returns exit 1 for
+		// paths that are tracked by the index even when they match a gitignore
+		// pattern (because `git` respects "already tracked" as override). But
+		// `git add` on the same tracked+ignored path STILL fails with "paths
+		// are ignored", so we need the gitignore rule check to win here. This
+		// is the PR #63 regression's actual shape: `.aperant/roadmap/foo.json`
+		// was tracked before `.aperant/roadmap/` was added to .gitignore.
+		proc = spawnSync('git', ['-C', gitCwd, 'check-ignore', '--no-index', '--stdin'], {
+			input: files.join('\n'),
+			encoding: 'utf-8',
+		})
+	} catch {
+		return { kept: [...files], skipped: [] }
+	}
+	// check-ignore: 0 = some ignored, 1 = none ignored, anything else = error.
+	if (!proc || (proc.status !== 0 && proc.status !== 1)) {
+		return { kept: [...files], skipped: [] }
+	}
+	const ignored = new Set(
+		(proc.stdout || '')
+			.split('\n')
+			.map((s) => s.trim())
+			.filter(Boolean),
+	)
+	const kept = []
+	const skipped = []
+	for (const f of files) {
+		if (ignored.has(f)) skipped.push(f)
+		else kept.push(f)
+	}
+	return { kept, skipped }
+}
+
+/**
+ * team sync implementation — shared entry used by cmdTeam and the task-close
+ * hook. Returns the result object (does not emit output).
+ *
+ * options: { push?: boolean, message?: string, cwd?: string }
+ *
+ * `options.cwd` controls where git runs — defaults to `targetDir`. Lifecycle
+ * handlers running against a worktree task pass the worktree path so the
+ * bookkeeping commit lands on the worktree's feature branch (R7 — fixes the
+ * C29 leak that landed bookkeeping on the main repo's branch).
+ */
+export function teamSync(targetDir, options = {}) {
+	const gitCwd = options.cwd ?? targetDir
+	if (!isTeamEnabled(targetDir)) {
+		return {
+			status: 'skipped',
+			reason: 'team mode disabled',
+			committed: false,
+			files: [],
+			pushed: false,
+			skipped_gitignored: 0,
+		}
+	}
+
+	const candidateFiles = computeTeamSyncFiles(targetDir, { cwd: gitCwd })
+	if (candidateFiles.length === 0) {
+		return {
+			status: 'ok',
+			committed: false,
+			files: [],
+			pushed: false,
+			skipped_gitignored: 0,
+			reason: 'team bookkeeping clean',
+		}
+	}
+
+	// Filter out anything the project-level .gitignore rejects. `git add` of
+	// an ignored path crashes with "paths are ignored by one of your
+	// .gitignore files" (seen on PR #63 where this repo ignores
+	// `.aperant/roadmap/`). Skipping silently is the correct behavior —
+	// ignored files by definition should never be staged.
+	const { kept: files, skipped: skippedIgnored } = filterGitignored(candidateFiles, gitCwd)
+	const skippedCount = skippedIgnored.length
+
+	if (files.length === 0) {
+		return {
+			status: 'ok',
+			committed: false,
+			files: [],
+			pushed: false,
+			skipped_gitignored: skippedCount,
+			reason: skippedCount > 0 ? 'all candidate files are gitignored' : 'team bookkeeping clean',
+		}
+	}
+
+	// R11 outputs enforcement: if the caller declared a task output allowlist,
+	// the final file list must be contained in it. A mismatch means the
+	// task's lifecycle commits tried to sync a path outside the contract.
+	if (Array.isArray(options.outputs)) {
+		const violations = findOutputsViolations(options.outputs, files)
+		if (violations.length > 0) {
+			return {
+				status: 'error',
+				committed: false,
+				files,
+				pushed: false,
+				skipped_gitignored: skippedCount,
+				error: `outputs-violation: team sync refused ${violations.length} path(s) outside task outputs: ${violations.slice(0, 5).join(', ')}`,
+				violations,
+				outputs: options.outputs,
+			}
+		}
+	}
+
+	// Stage — pathspec-limited so we can never touch anything outside the allowlist.
+	try {
+		execFileSync('git', ['add', '--', ...files], { cwd: gitCwd, stdio: 'pipe' })
+	} catch (err) {
+		return {
+			status: 'error',
+			committed: false,
+			files,
+			pushed: false,
+			skipped_gitignored: skippedCount,
+			error: `git add failed: ${err.message}`,
+		}
+	}
+
+	// Verify nothing outside the allowlist is staged. `git diff --cached --name-only`
+	// limited to the files we asked for should match exactly.
+	let stagedNames = ''
+	try {
+		stagedNames = execSync('git diff --cached --name-only -- .aperant', {
+			cwd: gitCwd,
+			encoding: 'utf-8',
+		})
+	} catch {
+		/* ignore */
+	}
+	const actuallyStaged = stagedNames
+		.split('\n')
+		.map((s) => s.trim())
+		.filter(Boolean)
+	const outsideAllowlist = actuallyStaged.filter((f) => !files.includes(f))
+	if (outsideAllowlist.length > 0) {
+		// Defensive: unstage the stray files so we never commit them.
+		try {
+			execFileSync('git', ['reset', 'HEAD', '--', ...outsideAllowlist], {
+				cwd: gitCwd,
+				stdio: 'pipe',
+			})
+		} catch {
+			/* ignore */
+		}
+	}
+
+	// If after the guard there's nothing staged (e.g. all files had identical
+	// content after normalization), bail out cleanly.
+	if (actuallyStaged.filter((f) => files.includes(f)).length === 0) {
+		return {
+			status: 'ok',
+			committed: false,
+			files: [],
+			pushed: false,
+			skipped_gitignored: skippedCount,
+			reason: 'nothing staged after filter',
+		}
+	}
+
+	const message = options.message || 'chore(aperant): sync team bookkeeping'
+	const fullMessage = `${message}\n\nCo-Authored-By: Aperant Framework <noreply@aperant.dev>\n`
+
+	try {
+		execFileSync('git', ['commit', '-m', fullMessage, '--', ...files], {
+			cwd: gitCwd,
+			stdio: 'pipe',
+		})
+	} catch (err) {
+		return {
+			status: 'error',
+			committed: false,
+			files,
+			pushed: false,
+			skipped_gitignored: skippedCount,
+			error: `git commit failed: ${err.message}`,
+		}
+	}
+
+	let sha = null
+	try {
+		sha = execSync('git rev-parse HEAD', { cwd: gitCwd, encoding: 'utf-8' }).trim()
+	} catch {
+		/* ignore */
+	}
+
+	let pushed = false
+	let pushError = null
+	if (options.push) {
+		try {
+			execFileSync('git', ['push'], { cwd: gitCwd, stdio: 'pipe' })
+			pushed = true
+		} catch (err) {
+			pushError = `git push failed: ${err.message}`
+		}
+	}
+
+	const result = {
+		status: 'ok',
+		committed: true,
+		sha,
+		files,
+		pushed,
+		skipped_gitignored: skippedCount,
+	}
+	if (pushError) result.push_error = pushError
+	return result
+}