# Discussion Framework

Deterministic CLI for managing `discussion/` workflow state without spending AI
tokens on mechanical maintenance.

AI should write and review content. This CLI should manage state.

## Install

From this repository:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e tools/discussion-framework
```

After moving this directory to its own GitHub repository:

```bash
pip install "git+ssh://git@git-local.bquarkz.net:2222/Intrepid/discussion-framework.git@master"
```

## Commands

```bash
discussion init
discussion start pbs-autocomplete-parameter-names "PBS autocomplete parameter names" --tag compiler-pbs --tag lsp
discussion accept-agenda DSC-0037
discussion add-decision DSC-0037 --title "Canonical PBS parameter names for editor assistance"
discussion accept-decision DSC-0037
discussion add-plan DSC-0037 --title "Propagate canonical parameter names to stdlib and LSP surfaces"
discussion mark-plan PLN-0078 in_progress
discussion mark-plan PLN-0078 done
discussion status
discussion status --json
discussion validate
discussion validate --json
discussion inspect DSC-0035
discussion inspect DSC-0035 --json
discussion context DSC-0035
discussion context DSC-0035 --json
discussion next-actions
discussion backup-index
discussion housekeep DSC-0035 --lesson discussion/lessons/.../LSN-0051-name.md
discussion housekeep DSC-0035 --no-lesson
```

Use `--root <path>` when running outside the repository root.

When a command is executed from inside the existing `discussion/` directory, the
CLI resolves the repository root to the parent directory instead of creating a
nested `discussion/discussion` tree.

## Contract

- `init` creates the canonical `discussion/` layout and `index.ndjson`.
- `start` creates a new discussion record and its first agenda artifact.
- `accept-agenda` marks an agenda as accepted once the discussion is ready for
  a decision.
- `add-decision` creates a decision artifact from an accepted agenda and indexes
  it under the discussion.
- `accept-decision` marks a decision as accepted once its content is normative.
- `add-plan` creates a plan artifact from an accepted decision and indexes it
  under the discussion.
- `mark-plan` moves a plan through `open`, `review`, `accepted`,
  `in_progress`, `done`, or `abandoned`.
- `status` prints a compact discussion overview.
- `inspect` shows one discussion and its indexed artifacts.
- `context` prints compact AI-ready context and suggested next actions.
- `next-actions` lists operational next steps across discussions.
- `validate` checks the index, counters, artifact references, and lesson files.
- `backup-index` replaces the old shell backup script by copying
  `discussion/index.ndjson` into `discussion/.backups/`.
- `housekeep` marks a discussion `done`, removes workflow artifacts, clears
  workflow arrays from the index, and optionally registers an existing lesson.

The command does not generate agenda, decision, plan, or lesson prose. That work
belongs to humans or AI agents.

## Codex Integration

Repository instructions and Codex skills should treat this CLI as the mechanical
state manager.

Recommended policy:

- Agents use AI for content: agenda, decision, plan, lesson, specs, and code.
- Agents use `discussion` for state: status, validation, housekeeping, index
  updates, and workflow artifact pruning.
- Agents should not manually edit `discussion/index.ndjson` when an equivalent
  `discussion` command exists.
- If a command is missing, agents may perform the operation manually and should
  record the missing command as a framework improvement.

Recommended skill behavior:

- `discussion-status`: run `discussion status` first, then inspect files only
  when the user asks for deeper analysis.
- `discussion-context`: run `discussion context DSC-XXXX`; this is the primary
  AI handoff surface.
- `discussion-validate`: run `discussion validate`; manual validation is a
  fallback only.
- `discussion-housekeep`: AI may decide whether a lesson is needed and write it;
  final state mutation must use `discussion housekeep --lesson ...` or
  `discussion housekeep --no-lesson`.
- `discussion-framework`: document the split between content generation and
  deterministic state operations.