Initial Commit

openspec/changes/p02-force-fetch-command/specs/fetch-run-reporting/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Command reports run outcome to operator
+The system SHALL present operator-facing output that describes whether the forced run succeeded or failed.
+
+#### Scenario: Successful run reporting
+- **WHEN** a forced fetch command completes without fatal errors
+- **THEN** the command output includes a success indication
+- **AND** includes the number of items stored in that run
+
+#### Scenario: Failed run reporting
+- **WHEN** a forced fetch command encounters a fatal execution error
+- **THEN** the command output includes a failure indication
+- **AND** includes actionable error details for operator diagnosis
+
+### Requirement: Command exposes automation-friendly exit semantics
+The system SHALL return deterministic process exit codes for command success and failure.
+
+#### Scenario: Exit code on success
+- **WHEN** the force-fetch command execution completes successfully
+- **THEN** the process exits with code 0
+- **AND** automation tooling can treat the run as successful
+
+#### Scenario: Exit code on fatal failure
+- **WHEN** the force-fetch command execution fails fatally
+- **THEN** the process exits with a non-zero code
+- **AND** automation tooling can detect the failure state

openspec/changes/p02-force-fetch-command/specs/force-fetch-command/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Operator can trigger immediate news fetch via Python command
+The system SHALL provide a Python command that triggers one immediate news aggregation run outside of the hourly scheduler.
+
+#### Scenario: Successful forced fetch invocation
+- **WHEN** an operator runs the documented force-fetch command with valid runtime configuration
+- **THEN** the system executes one full fetch cycle using the existing aggregation pipeline
+- **AND** the command terminates after the run completes
+
+#### Scenario: Command does not reconfigure scheduler
+- **WHEN** an operator runs the force-fetch command while the service scheduler exists
+- **THEN** the command performs a one-off run only
+- **AND** scheduler job definitions and cadence remain unchanged
+
+### Requirement: Forced fetch reuses existing aggregation behavior
+The system SHALL use the same retry, fallback, deduplication, image processing, and persistence logic as scheduled fetch runs.
+
+#### Scenario: Retry and fallback parity
+- **WHEN** the primary news provider request fails during a forced run
+- **THEN** the system applies the configured retry behavior
+- **AND** uses the configured fallback provider path if available
+
+#### Scenario: Deduplication parity
+- **WHEN** fetched headlines match existing duplicate rules
+- **THEN** duplicate items are skipped according to existing deduplication policy
+- **AND** only eligible items are persisted

openspec/changes/p02-force-fetch-command/specs/manual-fetch-recovery/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Manual command supports bootstrap and recovery workflows
+The system SHALL allow operators to run the forced fetch command during first-time setup and after failed scheduled cycles.
+
+#### Scenario: Bootstrap content population
+- **WHEN** the system is newly deployed and contains no current news items
+- **THEN** an operator can run the force-fetch command immediately
+- **AND** the command attempts to populate the dataset without waiting for the next hourly schedule
+
+#### Scenario: Recovery after failed scheduled fetch
+- **WHEN** a prior scheduled fetch cycle failed or produced incomplete results
+- **THEN** an operator can run the force-fetch command on demand
+- **AND** the system performs a fresh one-off fetch attempt
+
+### Requirement: Repeated manual runs remain operationally safe
+The system SHALL support repeated operator-triggered runs without corrupting data integrity.
+
+#### Scenario: Repeated invocation in same day
+- **WHEN** an operator runs the force-fetch command multiple times within the same day
+- **THEN** existing deduplication behavior prevents duplicate persistence for matching items
+- **AND** each command run completes with explicit run status output